Установка агентов
Агенты сканирования — контейнер на скан-хосте с 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 | Основной вариант для постоянной нагрузки |
| Kubernetes | Helm-чарт: Deployment или KEDA ScaledJob (pod на задание) | shell | Большие объёмы, масштаб по очереди |
Встроенные шаблоны рассчитаны на исполнитель docker. В Kubernetes агент работает с исполнителем shell, и для него нужны свои шаблоны с agent.executor: shell и без image (см. ниже).
Ресурсы — ориентир, а не замер. Подбирайте их под свои сборки:
| Масштаб | Вариант | Заданий одновременно | Ресурсы |
|---|---|---|---|
| Тест, пилот | встроенный агент | 1 | примерно +2 CPU, 4 ГБ RAM и 20 ГБ диска к серверу |
| Средний | отдельный скан-хост | 2–4 | 4–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. Создайте агента
- Откройте Workflow → Раннеры → Добавить раннера. Нужен интерактивный вход администратора; API-ключ для этого не подходит.
- Укажите имя и метки. Задание попадает только на агента, у которого есть все метки из
agent.labelsшаблона. Меткиexecutor:dockerиexecutor:shellагент получает сам по своему исполнителю. - При необходимости ограничьте разрешённые пайплайны: агент будет брать задания только этих шаблонов.
- Скопируйте токен
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/ комплекта:
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:
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) или к их зеркалу, см. Образы шагов в закрытом контуре.
Установка
-
Перейдите в каталог комплекта сервера:
Shell cd /opt/archepelag -
Заполните токен агента. Скрипт допишет
SCAN_AGENT_BUILTIN_TOKENв.env, если его там нет, а уже заданные значения не тронет:Shell sh generate-secrets.sh -
Скачайте образы агента и запустите его:
Shell docker compose --profile scan-agent pull docker compose --profile scan-agent up -d -
Откройте Workflow → Раннеры. Через несколько секунд там появится «Встроенный агент» с меткой
builtinи статусом «онлайн». Встроенные шаблоны меток не требуют, поэтому их задания сразу попадают на него.
Если агент не появился, посмотрите его журнал:
docker compose --profile scan-agent logs -f scan-agentНастройки
Лимиты задаются в .env сервера. После правки выполните docker compose --profile scan-agent up -d.
| Переменная | По умолчанию | Что задаёт |
|---|---|---|
SCAN_AGENT_CPUS | 2 | CPU на один шаг |
SCAN_AGENT_MEMORY | 4g | Память на один шаг |
SCAN_AGENT_CONCURRENCY | 1 | Сколько заданий агент выполняет одновременно |
Как он устроен
- Исполнитель 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 встроенного агента не трогают. Указывайте профиль и при обновлении сервера, тогда агент обновится вместе с ним:
docker compose --profile scan-agent pull
docker compose --profile scan-agent up -dОстановить только агента:
docker compose --profile scan-agent stop scan-agentДоверие к сертификату Archepelag
Если сертификат выпущен публичным CA, ничего делать не нужно. Если он самоподписанный или выпущен внутренним CA:
- Возьмите CA. Для самоподписанного сертификата edge на сервере Archepelag:
docker cp archepelag_nginx:/var/lib/archepelag-edge/fullchain.pem ./server-ca.pem. - Положите его на машину агента в
scan-agent/certs/server-ca.pem. - В
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.
docker login <ваш registry>иbash mirror-tool-images.sh <registry>/<префикс>из комплекта агента. Скрипт скачает закреплённые версии и отправит их в ваш registry.- Интеграции → Nexus: добавьте registry с этим адресом и префиксом.
- В шаблонах укажите
registry: <имя из Nexus>на уровне пайплайна или шага. Образ без хоста получает адрес и префикс registry, а агент — логин только этого registry. У образов с хостом (ghcr.io/cyclonedx/cdxgen:…) уберите хост вimage.
Trivy и Grype при запуске скачивают базы уязвимостей. В закрытом контуре задайте зеркало баз в env шага (TRIVY_DB_REPOSITORY, GRYPE_DB_UPDATE_URL).
Здоровье раннера
Раскройте строку раннера в Сканирование → Раннеры. Сверху вердикт: «Исправен», «Внимание» или «Проблема», и под ним причины. Например: мало места на диске, Docker не отвечает, за сутки упала половина заданий, агент устарел.
Ниже метрики каждого экземпляра на связи: сколько он работает, загрузка CPU, занятая память и диск, версия Docker, размер кэша зависимостей. Их присылает сам агент вместе с heartbeat. Агент старой версии метрики не присылает, и в плитках будет «нет метрик», пока вы его не обновите.
Под метриками задания раннера за сутки: сколько прошло и упало, среднее время задания, ожидание в очереди, график по часам и пять последних ошибок со ссылками на запуски. Блок обновляется раз в 30 секунд.
Обновление и остановка
- Сначала обновите сервер Archepelag, потом агенты. Если сервер перестал поддерживать протокол агента, в журнале агента
protocol_mismatchи заданий он не получает, пока его не обновят. Так было при переходе на протокол 2. Встроенный агент обновляется вместе с сервером:docker compose --profile scan-agent pull && docker compose --profile scan-agent up -d. - В
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 агент не онлайн. Запишите новый токен на машине агента и пересоздайте или перезапустите агента:
# Комплект 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 и агента:
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_EXECUTOR | auto | docker, shell или auto. В комплекте задаётся compose-файлом или манифестом. |
ARCHEPELAG_AGENT_CONCURRENCY | 1 | Параллельных заданий в экземпляре (1–64). Исполнитель shell — всегда 1. |
ARCHEPELAG_AGENT_LABELS | — | Метки для показа в UI. |
ARCHEPELAG_AGENT_MIN_FREE_GB | 10 | Не брать задания, если в рабочем каталоге свободно меньше. |
ARCHEPELAG_AGENT_CACHE_MAX_GB | без предела | Предел кэша зависимостей. |
ARCHEPELAG_AGENT_CA_FILE | — | Корпоративный CA для шагов. |
ARCHEPELAG_DOCKER_RUNTIME | runtime Docker | runc или runsc (gVisor). |
ARCHEPELAG_AGENT_PULL_POLICY | if-not-present | Когда скачивать образ шага: if-not-present или always. При always агент качает и toolbox сам, без логина хоста. |
ARCHEPELAG_AGENT_DOCKER_CONFIG | — | Каталог с config.json хоста (только чтение): логин registry для собственных скачиваний агента. Шагам не выдаётся. |
ARCHEPELAG_AGENT_LOG_LEVEL | info | debug, info, warn, error. |
Связанные страницы
- Описание пайплайна — что выполняет агент
- S3-хранилище — куда агент загружает результаты
- Устранение неполадок — агент не онлайн, задания ждут в очереди