Разделы документации

Установка агентов

Агенты сканирования — контейнер на скан-хосте с Docker или pod в Kubernetes. Как создать агента, выбрать режим, установить, масштабировать и обновлять.

Агент выполняет пайплайны на агентах: по одному репозиторию за задание. В интерфейсе агенты называются «Раннеры»: тот же агент выполняет и задания Оттеров AI-фабрики. Агент сам подключается к Archepelag по HTTPS и забирает задания, как Jenkins inbound agent или GitLab Runner. Входящий доступ к агенту не нужен. Отчёты, SBOM и логи шагов агент загружает в S3 (через Archepelag или напрямую в своё S3), а находки из них разбирает Archepelag.

Код
Archepelag ◀── HTTPS /agent-api (heartbeat, забрать задание, события, итог) ── агент
                                                                               │ git clone ──▶ VCS
                                                                               │ шаги: docker run или runner
                                                                               └ PUT файлов ──▶ Archepelag ──▶ S3 комплекта
                                                                                 или по подписанной ссылке ──▶ своё S3

У агента нет доступа к базе данных, Redis и ключам шифрования Archepelag. Он получает только задание: адрес репозитория, команды шагов и секреты, которые шаблон выдаёт этим шагам.

Варианты развёртывания

ВариантГдеИсполнительКогда
Встроенный агентРядом с сервером, профиль scan-agent в комплекте поставкиdockerТест, пилот, небольшая установка
Скан-хост с DockerОтдельный хост, комплект scan-agent/docker или shellОсновной вариант для постоянной нагрузки
KubernetesHelm-чарт: Deployment или KEDA ScaledJob (pod на задание)shellБольшие объёмы, масштаб по очереди

Встроенные шаблоны рассчитаны на исполнитель docker. В Kubernetes агент работает с исполнителем shell, и для него нужны свои шаблоны с agent.executor: shell и без image (см. ниже).

Ресурсы — ориентир, а не замер. Подбирайте их под свои сборки:

МасштабВариантЗаданий одновременноРесурсы
Тест, пилотвстроенный агент1примерно +2 CPU, 4 ГБ RAM и 20 ГБ диска к серверу
Среднийотдельный скан-хост2–44–8 CPU, 8–16 ГБ RAM, 100 ГБ диска
БольшойKubernetes + KEDAпо очередиpod на задание, примерно 2 CPU и 4 ГБ RAM

Перед установкой

  • Archepelag доступен агенту по HTTPS (PUBLIC_URL=https://…). По HTTP агент не подключается, кроме стендов (см. Без TLS).
  • Хранилище результатов. Без своего S3 агент загружает файлы через Archepelag во встроенное хранилище, и доступ к S3 ему не нужен. Если подключено своё S3-хранилище, агенту нужен доступ к его адресу для агентов. Если в таком хранилище загружен CA, агент при загрузке доверяет только ему — CA должен подходить и к адресу для агентов.
  • Сеть от агента: Archepelag (443), VCS (git clone по HTTPS), своё S3 (если подключено), registry образов шагов, репозитории зависимостей (Nexus, Artifactory) или прокси.
  • Комплект агента — каталог scan-agent/ в комплекте поставки сервера: docker-compose.yml, docker-compose.shell.yml, .env (версия и registry образов), agent.env.example, certs/, k8s/, helm/ (чарт для Kubernetes), mirror-tool-images.sh, README.md.
  • Версия агента — та же, что у сервера. Агенты протокола 1 (из прежних комплектов) этот сервер не принимает (protocol_mismatch): обновляйте их вместе с сервером.

Встроенному агенту из этого списка нужен только комплект сервера, см. Встроенный агент комплекта.

1. Создайте агента

  1. Откройте Workflow → Раннеры → Добавить раннера. Нужен интерактивный вход администратора; API-ключ для этого не подходит.
  2. Укажите имя и метки. Задание попадает только на агента, у которого есть все метки из agent.labels шаблона. Метки executor:docker и executor:shell агент получает сам по своему исполнителю.
  3. При необходимости ограничьте разрешённые пайплайны: агент будет брать задания только этих шаблонов.
  4. Скопируйте токен sa_…. Он показывается один раз. В том же окне UI показывает готовые команды установки: docker run, комплект scan-agent/ и Kubernetes.

Потеряли токен — Перевыпустить токен: старый перестаёт работать сразу, а новый нужно записать на машине агента и перезапустить его (см. Перевыпуск токена). Отключить агента — он доработает текущие задания и не будет брать новые. Удалённый агент возвращает свои задания в очередь.

2. Выберите режим

РежимГдеКак выполняются шагиКогда
docker (docker-compose.yml)Отдельный скан-хост с DockerКаждый шаг — свой контейнер со своим образом, лимиты памяти и CPU, network: none по запросуОсновной режим. Встроенные шаблоны рассчитаны на него
shell в Kubernetes (k8s/deployment.yaml)Pod из контейнеров agent и runnerВ toolbox-образе (JDK, Maven, Gradle, Node, CLI-сканеры)Кластер без docker.sock и привилегий
shell, pod на задание (k8s/optional/keda-scaledjob.yaml)KEDA ScaledJobТо жеМасштаб по очереди, чистый pod на каждое задание
shell в Docker (docker-compose.shell.yml)Хост с Docker, но без docker.sock у агентаТо жеНельзя отдать агенту docker.sock

Исполнитель shell не умеет того, что требует отдельного контейнера: image, network: none, resources, user, sourceReadOnly, entrypoint: image. Такие шаблоны уходят только агентам с исполнителем docker; для shell пишите шаблоны с agent.executor: shell и без image (см. Описание пайплайна).

3. Скан-хост с Docker

В каталоге scan-agent/ комплекта:

Shell
umask 077
printf 'Токен агента: '; read -rs ARCHEPELAG_TOKEN; echo
printf '%s' "$ARCHEPELAG_TOKEN" > token && unset ARCHEPELAG_TOKEN
chmod 600 token

cp agent.env.example agent.env
vi agent.env                  # ARCHEPELAG_SERVER_URL=https://<адрес Archepelag>
sudo mkdir -p /var/lib/archepelag-agent
docker login ghcr.io          # registry образов агента из .env; логин — любой, пароль — токен чтения
docker compose pull           # образ агента и toolbox (образ шагов без image)
docker compose up -d
docker compose logs -f scan-agent

Через несколько секунд агент в UI становится онлайн, а в карточке появляется экземпляр: хост, версия, исполнитель, свободное место.

Логин registry — на хосте. Агент скачивает образы через docker.sock своим docker CLI и docker login хоста не видит. Поэтому toolbox — образ шагов без image — скачивает docker compose pull (сервис toolbox в docker-compose.yml; его контейнер сразу завершается, так и задумано). Не ставьте ARCHEPELAG_AGENT_PULL_POLICY=always с закрытым registry: тогда агент качает toolbox сам. Если агенту всё же нужен свой логин (например, toolbox удаляют с хоста), смонтируйте каталог с config.json хоста только на чтение и укажите его в ARCHEPELAG_AGENT_DOCKER_CONFIG — строки есть в docker-compose.yml и agent.env.example. Работают только записи auths, без credsStore. Шагам этот логин не выдаётся: образы шагов из закрытого registry подключайте через registry: в шаблоне (см. ниже).

Токен не кладите в agent.env и в переменные окружения: их видно в docker inspect и /proc. Агент читает токен из файла (ARCHEPELAG_AGENT_TOKEN_FILE) и сразу убирает переменную из своего окружения, так что ни git, ни шаги её не видят.

Одинаковый путь рабочего каталога. Шаги — соседние контейнеры, и Docker монтирует в них пути хоста. Поэтому /var/lib/archepelag-agent смонтирован в агента по тому же пути, что и на хосте. При старте агент проверяет это пробным контейнером и не запускается, если пути разошлись.

Масштаб. ARCHEPELAG_AGENT_CONCURRENCY — сколько заданий выполняет один экземпляр (по умолчанию 1). Или несколько экземпляров с одним токеном: docker compose up -d --scale scan-agent=3. Каждый шаг по умолчанию получает до 4 ГБ памяти и 2 CPU (ARCHEPELAG_AGENT_DEFAULT_MEMORY, ARCHEPELAG_AGENT_DEFAULT_CPUS, в шаблоне — resources).

Как изолирован шаг: --security-opt no-new-privileges, --cap-drop ALL с минимальным набором capabilities, --pids-limit, лимиты памяти и CPU, отдельная docker-сеть archepelag-steps или --network none. Секреты передаются через временный --env-file, а не в аргументах команды.

4. Kubernetes

Основной способ — Helm-чарт scan-agent/helm/archepelag-scan-agent из комплекта. Он ставит Deployment постоянных агентов, а с keda.enabled: true — KEDA ScaledJob с pod'ом на задание. Пошаговая установка чарта и его параметры — в разделе «Kubernetes» файла scan-agent/README.md. Ниже — устройство pod'а и установка манифестами из k8s/ без Helm.

Pod — два контейнера с общим emptyDir /work:

  • agent держит токен агента, ходит в Archepelag и клонирует репозиторий. Чужой код он не исполняет.
  • runner — toolbox-образ (scan-agent-toolbox) с другим uid, без токена агента и без токена ServiceAccount, rootfs только на чтение. Он выполняет команды шагов.

Все шаги работают под одним uid runner'а. Поэтому после каждого шага runner завершает все процессы этого uid, включая ушедшие в фон, а стадия с parallel: true, где у какого-либо шага есть credentials, выполняется последовательно — соседний шаг не прочитает чужие секреты. Между заданиями runner не перезапускается, а сбрасывается на месте: так контейнер не уходит в CrashLoopBackOff при потоке коротких заданий. Чистый pod на каждое задание даёт KEDA ScaledJob (ниже).

Одно задание на pod. Настройки манифесты берут из Secret и ConfigMap archepelag-scan-agent, логин registry образов — из Secret archepelag-registry:

Shell
kubectl create namespace archepelag-scan
# registry образов агента (IMAGE_REPO), логин — любой, пароль — токен чтения образов
kubectl -n archepelag-scan create secret docker-registry archepelag-registry \
  --docker-server=ghcr.io --docker-username=archepelag --docker-password='<токен чтения>'
kubectl -n archepelag-scan create secret generic archepelag-scan-agent --from-literal=token='sa_…'
kubectl -n archepelag-scan create configmap archepelag-scan-agent \
  --from-literal=ARCHEPELAG_SERVER_URL=https://archepelag.example.corp
kubectl -n archepelag-scan apply -f scan-agent/k8s/
  • Registry: все манифесты ссылаются на imagePullSecrets: archepelag-registry. Если образы лежат в зеркале без пароля или в публичном registry, Secret можно не создавать: kubelet запишет предупреждение и скачает образы анонимно. Нет Secret при закрытом registry — pod'ы в ImagePullBackOff.
  • CA сервера: kubectl -n archepelag-scan create secret generic archepelag-server-ca --from-file=ca.pem=./server-ca.pem и ARCHEPELAG_SERVER_CA_FILE=/etc/archepelag/ca/ca.pem в ConfigMap.
  • Pod на задание: вместо Deployment — k8s/optional/keda-scaledjob.yaml (KEDA 2.x, Kubernetes 1.29+). KEDA опрашивает очередь агента и создаёт Job на каждое ожидающее задание; агент с ARCHEPELAG_AGENT_ONCE=true выполняет одно задание и завершается, runner с ARCHEPELAG_RUNNER_EXIT_AFTER_JOB=true — тоже. Свежий pod (свои /tmp и процессы) на каждое задание — самая сильная изоляция в режиме shell.
  • Сеть: пример k8s/optional/networkpolicy.example.yaml разрешает только Archepelag, VCS, S3, registry, прокси и DNS. Адрес метаданных облака 169.254.169.254 не открывайте.
  • Кэш между заданиями — k8s/optional/cache-statefulset.example.yaml (PVC на pod).

Ресурсы runner (requests/limits, ephemeral-storage, sizeLimit у emptyDir) подберите под самые тяжёлые сборки. Шаги в режиме shell не ограничены по памяти поодиночке: агент добавляет -XX:MaxRAMPercentage=50 в JAVA_TOOL_OPTIONS, если там нет своего -Xmx.

Встроенный агент комплекта

Встроенный агент запускается на сервере Archepelag из того же docker-compose.yml, что и сам Archepelag. Создавать агента в UI и копировать токен не нужно. Этот вариант подходит для пилота и небольших установок с доверенными репозиториями.

Что нужно

  • Сервер Archepelag уже установлен из комплекта поставки.
  • Свободные ресурсы на сервере: примерно 2 CPU, 4 ГБ RAM и 20 ГБ диска сверх того, что нужно самому Archepelag.
  • Выход с сервера к VCS и к registry образов шагов (Docker Hub, ghcr.io) или к их зеркалу, см. Образы шагов в закрытом контуре.

Установка

  1. Перейдите в каталог комплекта сервера:

    Shell
    cd /opt/archepelag
  2. Заполните токен агента. Скрипт допишет SCAN_AGENT_BUILTIN_TOKEN в .env, если его там нет, а уже заданные значения не тронет:

    Shell
    sh generate-secrets.sh
  3. Скачайте образы агента и запустите его:

    Shell
    docker compose --profile scan-agent pull
    docker compose --profile scan-agent up -d
  4. Откройте Workflow → Раннеры. Через несколько секунд там появится «Встроенный агент» с меткой builtin и статусом «онлайн». Встроенные шаблоны меток не требуют, поэтому их задания сразу попадают на него.

Если агент не появился, посмотрите его журнал:

Shell
docker compose --profile scan-agent logs -f scan-agent

Настройки

Лимиты задаются в .env сервера. После правки выполните docker compose --profile scan-agent up -d.

ПеременнаяПо умолчаниюЧто задаёт
SCAN_AGENT_CPUS2CPU на один шаг
SCAN_AGENT_MEMORY4gПамять на один шаг
SCAN_AGENT_CONCURRENCY1Сколько заданий агент выполняет одновременно

Как он устроен

  • Исполнитель docker. Каждый шаг идёт в отдельном контейнере со своим образом, как на скан-хосте, поэтому подходят все встроенные шаблоны и шаги каталога. Агент работает от root с docker.sock хоста, рабочий каталог — /var/lib/archepelag-scan-agent на хосте.
  • Сеть. Агент ходит в Archepelag через внутренний вход edge nginx. Порт 8088 наружу не публикуется и открывает только /agent-api/ и модельный шлюз AI-фабрики /llm-gateway/. Трафик не покидает хост, поэтому TLS, сертификат сервера и AGENT_API_ALLOW_PLAINTEXT не нужны. К базе, Redis и core у агента прямого доступа нет.
  • Токен хранится в SCAN_AGENT_BUILTIN_TOKEN в .env и передаётся агенту файлом, а не переменной окружения. Как его сменить, см. Перевыпуск токена.

Обновление встроенного агента

Команды docker compose pull, up -d и down без --profile scan-agent встроенного агента не трогают. Указывайте профиль и при обновлении сервера, тогда агент обновится вместе с ним:

Shell
docker compose --profile scan-agent pull
docker compose --profile scan-agent up -d

Остановить только агента:

Shell
docker compose --profile scan-agent stop scan-agent

Доверие к сертификату Archepelag

Если сертификат выпущен публичным CA, ничего делать не нужно. Если он самоподписанный или выпущен внутренним CA:

  1. Возьмите CA. Для самоподписанного сертификата edge на сервере Archepelag: docker cp archepelag_nginx:/var/lib/archepelag-edge/fullchain.pem ./server-ca.pem.
  2. Положите его на машину агента в scan-agent/certs/server-ca.pem.
  3. В agent.env: ARCHEPELAG_SERVER_CA_FILE=/etc/archepelag/certs/server-ca.pem, затем docker compose up -d.

В ARCHEPELAG_SERVER_URL указывайте имя из сертификата (APP_DOMAIN), а не IP-адрес. Отключить проверку сертификата у агента нельзя.

Корпоративный CA для шагов (Nexus, VCS, прокси с инспекцией TLS) задаётся отдельно: certs/extra-ca.pem и ARCHEPELAG_AGENT_CA_FILE=/etc/archepelag/certs/extra-ca.pem. Шаги получат ARCHEPELAG_CA_FILE, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE и GIT_SSL_CAINFO. Java эти переменные не читает — см. Свой CA для Java.

Прокси

HTTPS_PROXY, HTTP_PROXY и NO_PROXY в agent.env действуют на сам агент (Archepelag, своё S3, git) и передаются в шаги, кроме шагов с network: none. ARCHEPELAG_AGENT_PROXY_PASSTHROUGH=false — не передавать их в шаги. В NO_PROXY перечислите внутренние адреса, доступные напрямую.

Maven переменные прокси не читает: прокси для него задаётся в settings.xml (файл конфигурации в шаблоне). Агент передаёт шагам ARCHEPELAG_PROXY_HOST, ARCHEPELAG_PROXY_PORT и ARCHEPELAG_PROXY_NON_PROXY_HOSTS — их можно подставить в settings.xml как ${env.ARCHEPELAG_PROXY_HOST}.

Образы шагов в закрытом контуре

Встроенные шаблоны и шаги каталога берут образы с Docker Hub и ghcr.io: Maven, Gradle, Node, cdxgen, Gitleaks, Semgrep, Trivy, Grype, Noir.

  1. docker login <ваш registry> и bash mirror-tool-images.sh <registry>/<префикс> из комплекта агента. Скрипт скачает закреплённые версии и отправит их в ваш registry.
  2. Интеграции → Nexus: добавьте registry с этим адресом и префиксом.
  3. В шаблонах укажите registry: <имя из Nexus> на уровне пайплайна или шага. Образ без хоста получает адрес и префикс registry, а агент — логин только этого registry. У образов с хостом (ghcr.io/cyclonedx/cdxgen:…) уберите хост в image.

Trivy и Grype при запуске скачивают базы уязвимостей. В закрытом контуре задайте зеркало баз в env шага (TRIVY_DB_REPOSITORY, GRYPE_DB_UPDATE_URL).

Здоровье раннера

Раскройте строку раннера в Сканирование → Раннеры. Сверху вердикт: «Исправен», «Внимание» или «Проблема», и под ним причины. Например: мало места на диске, Docker не отвечает, за сутки упала половина заданий, агент устарел.

Ниже метрики каждого экземпляра на связи: сколько он работает, загрузка CPU, занятая память и диск, версия Docker, размер кэша зависимостей. Их присылает сам агент вместе с heartbeat. Агент старой версии метрики не присылает, и в плитках будет «нет метрик», пока вы его не обновите.

Под метриками задания раннера за сутки: сколько прошло и упало, среднее время задания, ожидание в очереди, график по часам и пять последних ошибок со ссылками на запуски. Блок обновляется раз в 30 секунд.

Обновление и остановка

  1. Сначала обновите сервер Archepelag, потом агенты. Если сервер перестал поддерживать протокол агента, в журнале агента protocol_mismatch и заданий он не получает, пока его не обновят. Так было при переходе на протокол 2. Встроенный агент обновляется вместе с сервером: docker compose --profile scan-agent pull && docker compose --profile scan-agent up -d.
  2. В scan-agent/.env поменяйте ARCHEPELAG_VERSION, затем docker compose pull && docker compose up -d на хосте с docker login: pull скачивает и toolbox новой версии, который агент сам скачать не сможет. В Kubernetes — helm upgrade чартом из нового комплекта или новый тег образов в манифестах.

При остановке (docker compose down, перезапуск с новой версией, SIGTERM в Kubernetes) агент останавливает свои шаги, загружает их логи и готовые отчёты и возвращает задания в очередь: попытка не тратится, задание подхватит другой экземпляр. На это у агента 120 секунд (stop_grace_period, terminationGracePeriodSeconds).

Обновление сервера тоже не роняет идущие сборки: пока API или база данных Archepelag недоступны, Archepelag не считает агентов пропавшими, а после восстановления даёт им время продлить аренду. Агент старой версии работает с новым сервером, пока сервер поддерживает его протокол; в UI такой экземпляр помечен как устаревший.

Перевыпуск токена

Агент читает токен только при старте. После Перевыпустить токен старый токен сразу отклоняется: в журнале агента unauthorized, в UI агент не онлайн. Запишите новый токен на машине агента и пересоздайте или перезапустите агента:

Shell
# Комплект scan-agent/ (docker-compose.yml)
umask 077
printf 'Новый токен агента: '; read -rs ARCHEPELAG_TOKEN; echo
printf '%s' "$ARCHEPELAG_TOKEN" > token && unset ARCHEPELAG_TOKEN
docker compose up -d --force-recreate scan-agent
# docker-compose.shell.yml: файл читает uid 10000 — вместо записи выше
#   printf '%s' "$ARCHEPELAG_TOKEN" | sudo tee token >/dev/null && unset ARCHEPELAG_TOKEN
#   sudo chown 10000 token && sudo chmod 600 token
#   docker compose -f docker-compose.shell.yml up -d --force-recreate scan-agent

# Установка командой docker run из окна UI: новый токен в /opt/archepelag-scan-agent/agent-token, затем
docker restart archepelag-scan-agent-<имя агента>

# Kubernetes (манифесты или чарт с Secret, созданным вручную): обновить Secret и перезапустить pod'ы
kubectl -n archepelag-scan create secret generic archepelag-scan-agent \
  --from-literal=token='sa_…' --dry-run=client -o yaml | kubectl apply -f -
kubectl -n archepelag-scan rollout restart deploy/archepelag-scan-agent

# Helm, если Secret создал чарт (token.value): pod'ы перезапустятся сами
helm upgrade archepelag-scan-agent ./helm/archepelag-scan-agent -n archepelag-scan \
  -f my-values.yaml --set-file token.value=./token

Простой docker compose up -d контейнер не пересоздаёт: compose не замечает, что изменилось только содержимое файла token. agent.env при перевыпуске не трогайте. Pod'ы KEDA ScaledJob берут Secret при создании, их перезапускать не нужно.

Встроенный агент. Его токен задаётся в .env сервера, и Перевыпустить токен в UI для него отвечает ошибкой. Чтобы сменить токен, очистите строку SCAN_AGENT_BUILTIN_TOKEN= в .env, выполните sh generate-secrets.sh (он заполнит её новым токеном) и перезапустите core-service и агента:

Shell
docker compose --profile scan-agent up -d --force-recreate core-service scan-agent

Без TLS (только стенды)

Агент передаёт свой токен и получает в задании токены VCS и секреты шагов, поэтому по HTTP подключение выключено с обеих сторон. На стенде без TLS нужны обе настройки: ARCHEPELAG_AGENT_ALLOW_PLAINTEXT=true в agent.env и AGENT_API_ALLOW_PLAINTEXT=true в app.env сервера. Иначе сервер отвечает insecure_transport. Встроенному агенту комплекта эти настройки не нужны: он ходит через внутренний вход на том же хосте.

Переменные агента

Полный список с описаниями — в scan-agent/README.md комплекта и в agent.env.example. Основные:

ПеременнаяПо умолчаниюОписание
ARCHEPELAG_SERVER_URL— (обязательно)Адрес Archepelag (PUBLIC_URL). Только https://.
ARCHEPELAG_AGENT_TOKEN_FILEзадаёт compose или манифестФайл с токеном sa_….
ARCHEPELAG_SERVER_CA_FILE—CA сертификата Archepelag (PEM).
ARCHEPELAG_AGENT_EXECUTORautodocker, shell или auto. В комплекте задаётся compose-файлом или манифестом.
ARCHEPELAG_AGENT_CONCURRENCY1Параллельных заданий в экземпляре (1–64). Исполнитель shell — всегда 1.
ARCHEPELAG_AGENT_LABELS—Метки для показа в UI.
ARCHEPELAG_AGENT_MIN_FREE_GB10Не брать задания, если в рабочем каталоге свободно меньше.
ARCHEPELAG_AGENT_CACHE_MAX_GBбез пределаПредел кэша зависимостей.
ARCHEPELAG_AGENT_CA_FILE—Корпоративный CA для шагов.
ARCHEPELAG_DOCKER_RUNTIMEruntime Dockerrunc или runsc (gVisor).
ARCHEPELAG_AGENT_PULL_POLICYif-not-presentКогда скачивать образ шага: if-not-present или always. При always агент качает и toolbox сам, без логина хоста.
ARCHEPELAG_AGENT_DOCKER_CONFIG—Каталог с config.json хоста (только чтение): логин registry для собственных скачиваний агента. Шагам не выдаётся.
ARCHEPELAG_AGENT_LOG_LEVELinfodebug, info, warn, error.

Связанные страницы