Deploy: быстрый старт

От образа контейнера до работающего HTTPS-сервиса через Management API и acdn-agent.py.

Перед началом

Deploy запускает образ контейнера как сервис с публичным HTTPS-адресом. Всё описанное на этой странице может выполнить скрипт или ИИ-агент через Management API. Три шага с аккаунтом выполняет человек в браузере.

  • Образ должен быть собран для linux/amd64 и размещён в реестре: публичном, приватном репозитории Docker Hub или GitHub Container Registry либо в вашем собственном реестре ACDN.
  • Аккаунту нужны подтверждённый адрес электронной почты, баланс больше нуля и одобренная проверка личности. GET /api/user/deploy/requirements показывает, чего не хватает, и возвращает страницу, на которой владелец аккаунта выполняет нужный шаг.
  • В одном приложении одновременно работает до 3 экземпляров. Выпуск сервиса без томов временно добавляет один экземпляр, поэтому в приложении с таким сервисом можно настроить до 2 экземпляров.
  • Использование оплачивается с баланса аккаунта. Цены указаны в разделе «Оплата» в конце страницы.

Если запрос вернул статус 403, вызовите GET /api/user/deploy/requirements и покажите владельцу аккаунта message и action_url невыполненного требования. Решить это может только он; повторять запрос бесполезно.

Подключение acdn-agent.py

acdn-agent.py — утилита из одного файла: она получает OAuth-токен через device flow и передаёт его в curl. Команда authorize печатает ссылку и код и ждёт; владелец аккаунта открывает ссылку, входит в аккаунт и подтверждает доступ. Токен сохраняется в tmp/acdn-agent/ в текущем каталоге и обновляется автоматически.

Shell
curl -fsSLO https://acdn.uz/tools/acdn-agent.py
python3 acdn-agent.py authorize --no-browser

# чего не хватает аккаунту, доступные регионы, ограничения, цены
python3 acdn-agent.py call /api/user/deploy/requirements

Аргументы после «--» передаются в curl. В примерах используется --json, для него нужен curl 7.82 или новее; в более старых версиях передавайте --header "Content-Type: application/json" --data. При ошибке запроса печатается JSON с ошибкой, а код завершения ненулевой. Сообщения возвращаются на языке аккаунта; чтобы получать их на английском, добавьте после «--» --header "Accept-Language: en".

Создание приложения

Приложение объединяет сервисы, тома и точки доступа одного проекта в одном регионе и одной частной сети. Сохраните полученный id. Приложение подготавливается в фоне, обычно за несколько секунд; перед деплоем дождитесь статуса ready.

Shell
python3 acdn-agent.py call /api/user/deploy/applications -- \
  --json '{"name":"Chat backend","region":"UZ"}'

# повторяйте, пока не появится "status":"ready"
python3 acdn-agent.py call /api/user/deploy/applications/APPLICATION_ID
  • Опрашивайте каждые несколько секунд. Подготовка прекращается через 5 минут со статусом failed; тогда отправьте POST /api/user/deploy/applications/prepare/APPLICATION_ID, чтобы повторить её.
  • Тома, сервисы и точки доступа можно создавать при любом статусе приложения, кроме удаления. Деплой принимается, только когда статус ready; иначе запрос вернёт 409.
  • Не повторяйте запрос на создание после тайм-аута, не проверив список приложений: каждый принятый запрос создаёт ещё одно приложение.

Добавление тома и сервиса

Сначала создайте том, затем сервис, который его монтирует. endpoint_ports запрашивает публичный HTTPS-адрес для каждого указанного порта контейнера; сгенерированное имя хоста возвращается в endpoints.

Shell
python3 acdn-agent.py call /api/user/deploy/volumes -- \
  --json '{"deploy_application_id":"APPLICATION_ID","name":"data","size_gb":1}'

python3 acdn-agent.py call /api/user/deploy/services -- --json '{
  "deploy_application_id": "APPLICATION_ID",
  "name": "web",
  "image": "ghcr.io/example/chat:1.4.2",
  "http_port": 8080,
  "health_check_path": "/healthz",
  "replicas": 1,
  "volume_mounts": [{"deploy_volume_id": "VOLUME_ID", "mount_path": "/data"}],
  "environment_variables": [
    {"name": "LOG_LEVEL", "value": "info", "is_secret": false},
    {"name": "SESSION_SECRET", "value": "change-me", "is_secret": true}
  ],
  "endpoint_ports": [8080]
}'
  • http_port — порт, который слушает ваш процесс. Слушайте 0.0.0.0, а не только 127.0.0.1. Переменная PORT не задаётся.
  • health_check_path должен отвечать статусом от 200 до 399, когда сервис готов принимать трафик. Проверка отправляется напрямую экземпляру, а не через публичный адрес.
  • Поле volume_mounts обязательно; для сервиса без томов передайте пустой массив.
  • Сервис, который хранит файл базы данных на томе, должен работать с replicas 1: каждый экземпляр получает собственный отдельный диск.
  • Секреты доступны только на запись. Они попадают в контейнер как переменные окружения и никогда не возвращаются через API.
  • Пока ничего не запущено: сервис создаётся со статусом draft.

Деплой и ожидание результата

Запрос на деплой сразу возвращает новый деплой в поле latest_deployment. Запомните его id и опрашивайте сервис примерно раз в 5 секунд, пока этот деплой не получит статус active, failed или cancelled. На готовность деплою отводится 10 минут.

Shell
python3 acdn-agent.py call /api/user/deploy/services/deploy/SERVICE_ID -- --request POST

# статус сервиса и его последнего деплоя
python3 acdn-agent.py call /api/user/deploy/services/SERVICE_ID

# последние деплои с хронологией; найдите свой по id
python3 acdn-agent.py call /api/user/deploy/services/deployments/SERVICE_ID
  • Успех: у вашего деплоя статус active, у сервиса статус running. Сервис отвечает по адресу endpoints[].url через HTTPS.
  • Ошибка: поле failure вашего деплоя содержит причину, а progress — перечень событий. Прочитайте логи до любых изменений: они исчезают при замене экземпляра.
  • После неудачного деплоя платформа может добавить более новый деплой с action recover, который восстанавливает предыдущий релиз. Тогда сервис снова показывает running, хотя ваш деплой завершился ошибкой, поэтому всегда проверяйте деплой с тем id, который вы запустили.
  • Новое имя хоста публикуется в DNS при создании точки доступа. Подождите несколько минут, пока оно начнёт разрешаться повсеместно.

Статус и логи

Shell
# состояние проверки работоспособности каждого экземпляра
python3 acdn-agent.py call /api/user/deploy/services/readiness/SERVICE_ID

# последние 1000 строк первого экземпляра; в ответе перечислены все экземпляры
python3 acdn-agent.py call /api/user/deploy/services/logs/SERVICE_ID

# вывод запуска, предшествовавшего последнему перезапуску экземпляра
python3 acdn-agent.py call '/api/user/deploy/services/logs/SERVICE_ID?instance=INSTANCE_ID&instance_uid=INSTANCE_UID&previous=1'
  • Логи — это стандартный вывод и стандартный поток ошибок контейнера, с меткой времени перед каждой строкой.
  • Доступен только недавний вывод экземпляров, которые ещё существуют. Читайте логи неудачного деплоя сразу.
  • INSTANCE_ID и INSTANCE_UID берутся из предыдущего ответа с логами: instances[].id перечисляет экземпляры, а instance_uid относится к экземпляру, чей текст возвращён.
  • Для сервиса без экземпляров возвращаются пустой text и instance со значением null.

Повторный деплой, откат, остановка

Чтобы выпустить новый образ, загрузите его в реестр и выполните деплой ещё раз: при каждом деплое тег заново разрешается в дайджест. Чтобы изменить настройки, сначала обновите сервис или его окружение, затем выполните деплой. Сохранённые изменения не действуют до следующего деплоя.

Shell
# заменить окружение, затем выпустить его
python3 acdn-agent.py call /api/user/deploy/services/environment/SERVICE_ID -- --request PUT --json '{
  "environment_variables": [
    {"name": "LOG_LEVEL", "value": "debug", "is_secret": false},
    {"name": "SESSION_SECRET", "value": "", "is_secret": true}
  ]
}'
python3 acdn-agent.py call /api/user/deploy/services/deploy/SERVICE_ID -- --request POST

# вернуться к более раннему релизу: выберите деплой с "can_rollback": true
python3 acdn-agent.py call /api/user/deploy/services/rollback/SERVICE_ID -- \
  --json '{"source_deployment_id":"DEPLOYMENT_ID"}'

# запустить новые экземпляры текущего релиза или остановить сервис
python3 acdn-agent.py call /api/user/deploy/services/restart/SERVICE_ID -- --request POST
python3 acdn-agent.py call /api/user/deploy/services/stop/SERVICE_ID -- --request POST

# удалить всё, включая данные на томах
python3 acdn-agent.py call /api/user/deploy/applications/APPLICATION_ID -- --request DELETE
  • Запрос окружения заменяет весь список. Существующий секрет, переданный с пустым значением, сохраняет своё значение; переменная, которой нет в списке, удаляется.
  • Откат восстанавливает образ, конфигурацию, окружение и секреты выбранного релиза. Данные на томах не откатываются.
  • Откат не меняет сохранённую конфигурацию. Следующий deploy снова применит сохранённую конфигурацию, поэтому после отката сохраните и те настройки, которые хотите оставить.
  • Для отката подходит только деплой, который когда-либо был активным; любой другой id вернёт 404.
  • На deploy, stop, restart и rollback вместе действует ограничение 6 запросов в минуту, и у сервиса может выполняться только один деплой (иначе статус 409). В ограничении учитывается каждый запрос, включая отклонённые.

Оплата

  • CPU: 0,02 $ за CPU-час. Учитывается только фактически потреблённое процессорное время, поэтому простаивающий сервис почти ничего не стоит по CPU.
  • Память: 0,005 $ за ГиБ-час используемой памяти; измеряется рабочая память экземпляра, включая активно используемый файловый кеш.
  • Тома: 0,10 $ за ГиБ-месяц выделенного размера каждого диска, независимо от заполненности и от того, запущен ли сервис. Том ничего не стоит, пока не развёрнут сервис, который его монтирует (до этого allocated_bytes равен 0).
  • Исходящий трафик: 0,05 $ за ГиБ, отправленный вашими экземплярами. Трафик, отданный на собственном домене через pull-зону CDN, дополнительно оплачивается как доставка CDN по цене тарифа pull-зоны.
  • Нет бесплатного объёма, минимального платежа и платы за само приложение или точку доступа.
  • Использование учитывается примерно каждые 30 минут и списывается с баланса аккаунта. API возвращает использование за текущий месяц для каждого сервиса, тома и приложения.
  • Для создания приложения нужен баланс больше нуля. При обнаружении отрицательного баланса действующим сервисам Deploy даётся отсрочка оплаты на три дня (72 часа). В течение отсрочки сервисы работают, деплой и перезапуск доступны. Плата за использование продолжает начисляться.
  • Письма сообщают о начале отсрочки и точном сроке оплаты, напоминают за 24 часа до его истечения и подтверждают приостановку после остановки сервисов. GET /api/user/deploy/requirements возвращает negative_balance_grace_ends_at и deployments_blocked. Баланс проверяется каждую минуту; до обнаружения отрицательного баланса срок равен null.
  • Если к указанному сроку баланс остаётся отрицательным, все сервисы Deploy, включая личные реестры, штатно останавливаются. Деплой, перезапуск и откат возвращают 402 до погашения долга. Пополнение до нуля или выше сбрасывает отсчёт; частичная оплата, оставляющая баланс отрицательным, не продлевает срок.
  • После пополнения баланса до нуля или выше приходит подтверждение по почте, а сервисы, приостановленные из-за задолженности, автоматически запускаются с прежним релизом. Восстановление проверяется каждую минуту и дожидается завершения уже начатой остановки. Приостановленный личный реестр запускается раньше сервисов, которым нужны его образы. Вручную остановленные сервисы остаются выключенными. Настройки и сохранённые данные остаются; плата за выделенные тома и Storage реестра начисляется до их удаления.

Точные поля запросов и ответов, ограничения и ответы с ошибками приведены в справочнике Management API.