Обновление самостоятельно размещаемого Claude Managed Agents

На этой странице показано, как обновить развёртывание в Kubernetes или Docker Compose и как выполнить откат. В Kubernetes продолжительность простоя зависит от того, насколько далеко заходит обновление:

Стек Docker Compose недоступен на время перезапуска при обновлении любого типа.

Перед обновлением

Прочитайте раздел нового выпуска в CHANGELOG.md, который находится в корне распакованного архива. Он начинается с шагов обновления, специфичных для этого выпуска. Если вы пропускаете выпуски, выполните инструкции всех разделов новее вашей версии, начиная с самого старого.

Затем просмотрите раздел Настройки и пути для проверки.

Минорное или мажорное обновление включает резервное копирование базы данных. Дамп содержит все беседы в открытом виде, поэтому команды на этой странице шифруют его с помощью инструмента шифрования age. Создайте пару ключей один раз и храните закрытый ключ cma-backup.agekey отдельно от резервных копий:

age-keygen -o cma-backup.agekey
age-keygen -y cma-backup.agekey > cma-backup.agepub

Обновление в Kubernetes

Команды kubectl на этой странице считывают имя Deployment сервера из переменной оболочки. Выполните эти две строки в каждом терминале, где вы выполняете команды. Первая строка находит имя, а вторая выводит его:

server=$(kubectl -n cma-server get deployment -l anthropic.com/role=server -o jsonpath='{.items[*].metadata.name}')
echo "$server"

Если вторая строка выводит cma-server, продолжайте. Если выводится другое имя, перед обновлением прочитайте об именах ваших объектов. Если ничего не выводится, убедитесь, что kubectl указывает на нужный кластер, и снова выполните эти две строки.

1. 1

   Соберите и отправьте новые образы

   Распакуйте новый архив. Соберите и отправьте три его образа с новой версией, как описано в разделе Сборка и отправка образов. Если вы запускаете “egress gateway” (шлюз исходящего трафика), также соберите и отправьте его образ.

   Если вы собираете собственный образ песочницы, также пересоберите и отправьте его с новой версией. Сравните его Dockerfile с kubernetes/sandbox/Dockerfile в новом архиве и ознакомьтесь с разделом что нужно собственному образу.

2. 2

   Укажите новую версию в файлах значений

   Если в файле значений задан image.tag, измените его на новую версию.

3. 3

   Остановите все серверы, если этого требует обновление

   Выполняйте этот шаг только в следующих случаях:

   • Какой-либо из ваших серверов отстаёт от нового выпуска более чем на один минорный выпуск.
   • Первое число, мажорная версия, увеличивается.
   • В CHANGELOG.md какой-либо раздел новее выпуска, который вы запускаете, указывает, что серверы необходимо остановить.

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

   kubectl -n cma-server scale deployment/$server --replicas=0
   kubectl -n cma-server wait --for=delete pod -l anthropic.com/role=server --timeout=90s

   
4. 4

   Создайте резервную копию базы данных

   Сделайте это перед минорным или мажорным обновлением или если вы остановили серверы. Если старый выпуск не может работать с изменённой схемой, эта резервная копия — единственный путь назад.

   Используйте pg_dump той же основной версии PostgreSQL, что и ваш сервер базы данных. Вместо <role> и <database> укажите значения user и dbname из database.url в cma-server-values.yaml. pg_dump запрашивает пароль роли.

   set -o pipefail
   PGSSLMODE=require pg_dump -h <database-host> -U <role> -d <database> -Fc \
     | age -r "$(cat cma-backup.agepub)" -o cma_server-<old-version>.dump.age

   

   Если какая-либо из команд выводит ошибку, оставленный ею файл не является резервной копией. Устраните причину и выполните команду снова, прежде чем продолжить.

   Если серверы работают, резервная копия содержит только то, что клиенты записали до начала дампа.

5. 5

   Обновите сервер, затем песочницы

   Выполните эти команды из корневого каталога нового архива, используя файлы значений из вашей установки:

   helm upgrade cma-server kubernetes/server/chart --namespace cma-server -f cma-server-values.yaml --wait
   helm upgrade cma kubernetes/chart --namespace cma -f cma-values.yaml --wait

   

   Если у вас несколько окружений, выполните вторую команду для каждого релиза Helm песочниц, указав имя, пространство имён и файл значений этого релиза.

   Если вы остановили серверы, первая команда переносит схему, восстанавливает число серверов и завершается, как только новые серверы готовы.

Когда серверы работают, Helm запускает каждый новый сервер, прежде чем остановить старый, поэтому число готовых серверов никогда не уменьшается. При минорном обновлении первая команда меняет схему, пока старые серверы продолжают обслуживать запросы, а затем заменяет их. Открытый поток событий на заменяемом сервере корректно завершается, поэтому клиент, который следит за потоком, должен переподключиться.

Если команда завершается ошибкой, см. раздел Если обновление завершилось ошибкой.

Обновление в Docker Compose

Шаги одинаковы для обновления любого типа. Выполняйте каждую команду docker compose из каталога Compose выпуска, то есть из каталога, в котором находится docker-compose.yml. В распакованном архиве это каталог compose. Используйте терминал, в котором не заданы ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY и ANTHROPIC_AUTH_TOKEN, потому что Compose передаёт серверу значения этих переменных из оболочки.

1. 1

   Создайте резервную копию базы данных

   Сделайте это перед минорным или мажорным обновлением из каталога Compose старого выпуска:

   set -o pipefail
   docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
     | age -r "$(cat cma-backup.agepub)" -o cma_server-<old-version>.dump.age

   

   В команде оставьте $POSTGRES_USER и $POSTGRES_DB без изменений. Текст в одинарных кавычках выполняется внутри контейнера postgres, в котором эти переменные содержат имена его роли и базы данных.

   Во время резервного копирования стек продолжает обслуживать запросы, поэтому в дамп не попадёт то, что клиенты запишут после начала дампа. Если какая-либо из команд выводит ошибку, оставленный ею файл не является резервной копией. Устраните причину и выполните команду снова, прежде чем продолжить.

2. 2

   Распакуйте новый архив

   Поместите новый архив в каталог, где может оставаться новый выпуск, например в родительский каталог старого выпуска. Команды распаковывают архив там, и новый стек запускается из распакованных файлов.

   Если ваша umask строже, чем 022, сначала выполните umask 022. Затем выполните следующее из каталога Compose старого выпуска. Вместо <directory> укажите полный путь к каталогу, в котором находится новый архив. Вместо <archive> укажите имя архива без .tar.gz.

   releases="<directory>"
   tar -xzf "$releases/<archive>.tar.gz" -C "$releases" && cp .env compose.config.yaml "$releases/<archive>/compose/"

   

   Вторая строка также копирует ваши .env и compose.config.yaml в распакованный каталог compose. Старый стек продолжает работать во время выполнения обеих строк. Если какая-либо строка выводит ошибку, устраните причину и снова выполните обе строки.

3. 3

   Повторите остальные изменения

   Переносятся только .env и compose.config.yaml. Внесите остальные изменения заново в каталоге Compose нового выпуска:

   • Добавленный вами файл: скопируйте его.
   • Изменённый вами поставляемый файл: внесите то же изменение в копию нового выпуска. Не копируйте поверх неё старый файл, потому что это отменит изменения, внесённые выпуском в этот файл.
   • Идентификация агентов: скопируйте каталог agent-identity с помощью cp -a, используя sudo, если его владелец — root, и снова отредактируйте блок volumes: в docker-compose.yml.
   • Собственный файл Compose: скопируйте его и проверьте относительные пути в нём.

   Затем внесите изменения для Docker Compose из раздела Настройки и пути для проверки.

4. 4

   Остановите старый стек и запустите новый

   Выполните эти строки в том терминале, где вы распаковывали архив, потому что они используют заданную в нём переменную $releases. Оставайтесь в каталоге Compose старого выпуска и укажите то же имя вместо <archive>. Если вы экспортировали COMPOSE_FILE для старого стека, сначала экспортируйте то же значение.

   ls "$releases/<archive>/compose/.env" && docker compose down
   cd "$releases/<archive>/compose" && docker compose up --build -d

   

   Первая строка останавливает старый стек, только если .env нового выпуска находится на месте. docker compose down сохраняет базу данных. Не добавляйте -v, так как этот флаг её удаляет. Новый стек подхватывает базу данных, а его контейнер migrate обновляет схему до запуска сервера.

Если команда завершается ошибкой, см. раздел Если обновление завершилось ошибкой.

Если обновление завершилось ошибкой

Прежде чем выполнять откат, найдите причину в журнале:

• Kubernetes: если Job миграции завершается ошибкой, helm upgrade ожидает несколько минут, пока Job повторяет попытки, а затем завершается ошибкой. Во время этого ожидания выполните kubectl -n cma-server logs job/$server-migrate во втором терминале, задав $server, как в разделе Обновление в Kubernetes. Kubernetes удаляет журнал, когда Job прекращает повторять попытки. Если вы не успели его прочитать, снова выполните helm upgrade — эта команда снова запускает Job.
• Docker Compose: вывод docker compose up --build -d может не показывать причину. Чтобы найти её, выполните docker compose logs.

Миграция может пройти успешно, а новые серверы при этом не становятся готовыми. Чтобы найти причину, прочитайте журнал серверов:

• Kubernetes: kubectl -n cma-server logs -l anthropic.com/role=server --prefix --tail=20
• Docker Compose: docker compose logs cma-server

Например, в Kubernetes строка, содержащая has invalid keys, указывает на настройку в server.config, которую новый выпуск не принимает. Устраните причину и снова выполните команду обновления. Только после этого рассматривайте восстановление резервной копии, потому что при восстановлении теряются данные. В Kubernetes после изменения схемы работающий сервер старого выпуска продолжает обслуживать запросы, но может не запуститься снова, если остановится.

Откат

Команды kubectl в этом разделе используют переменную $server из раздела Обновление в Kubernetes. Прежде чем выполнять откат, ознакомьтесь с разделом Если обновление завершилось ошибкой. Затем выполните откат в зависимости от типа обновления:

• После обновления патч-версии: перейдите к разделу Повторное развёртывание старого выпуска. Оба выпуска используют одну и ту же схему.
• После обновления минорной или мажорной версии: откройте CHANGELOG.md в новом архиве. Прочитайте раздел каждого выпуска, вышедшего после того, к которому вы возвращаетесь.
  • Если в каком-либо разделе сказано, что старый выпуск не может запуститься на базе данных, схему которой изменила миграция, восстановите резервную копию.
  • В противном случае повторно разверните старый выпуск. Если это завершится ошибкой cannot downgrade, восстановите резервную копию.

Повторное развёртывание старого выпуска

• Kubernetes: перейдите в верхний каталог старого архива. Выполните две команды helm upgrade из раздела Обновление в Kubernetes, используя файлы значений в том виде, в каком они были для того выпуска. Например, если вы добавили earlierNames для обновления, удалите его. Выполняйте вторую команду, только когда первая выполнится успешно.
• Docker Compose: выполните docker compose down в каталоге Compose нового выпуска, а затем docker compose up --build -d в каталоге старого.

Если старый выпуск не может работать с изменённой схемой, журнал выводит cannot downgrade:

• Kubernetes: Job миграции завершается ошибкой, а серверы остаются прежними. Как прочитать журнал Job, описано в разделе Если обновление завершилось ошибкой.
• Docker Compose: сервер не запускается. Прочитайте журнал с помощью docker compose logs migrate.

В Docker Compose вывод docker compose logs может вместо этого показывать stored value is encrypted but no encryption key is configured. В этом случае в .env старого выпуска нет строки CMA_STORE__CREDENTIALS_ENCRYPTION_KEY. Скопируйте эту строку из .env нового выпуска и снова выполните docker compose up --build -d.

Восстановление резервной копии в Kubernetes

На сервере баз данных должно быть место для второй копии базы данных. Вместо <role> и <database> укажите значения user и dbname из database.url в cma-server-values.yaml.

1. 1

   Восстановите резервную копию в новую базу данных

   Подключитесь к базе данных postgres на сервере баз данных от имени администратора и выполните:

   CREATE DATABASE <database>_restored OWNER <role>;

   

   Затем на машине, где хранится резервная копия, выполните эту команду, указав пути к вашему ключу и файлу резервной копии. Используйте pg_restore той же основной версии, что и ваш сервер базы данных. Команда запрашивает пароль роли и ничего не выводит, если всё прошло успешно.

   age -d -i cma-backup.agekey cma_server-<old-version>.dump.age \
     | PGSSLMODE=require pg_restore -h <database-host> -U <role> -d <database>_restored --no-owner --exit-on-error

   

   Если команда выводит ошибку, остановитесь. Ваша база данных не изменилась. Выполните DROP DATABASE <database>_restored; от имени администратора и начните этот шаг заново.

2. 2

   Остановите все серверы

   kubectl -n cma-server scale deployment/$server --replicas=0
   kubectl -n cma-server wait --for=delete pod -l anthropic.com/role=server --timeout=90s

   
3. 3

   Переключитесь на восстановленную базу данных

   Подключитесь к базе данных postgres от имени администратора и выполните:

   ALTER DATABASE <database> RENAME TO <database>_upgraded;
   ALTER DATABASE <database>_restored RENAME TO <database>;

   

   Если первая инструкция сообщает, что базу данных используют другие сеансы, закройте эти сеансы и снова выполните обе инструкции. Такие сеансы может удерживать пул подключений.

4. 4

   Разверните старый выпуск

   Выполните пункт для Kubernetes из раздела Повторное развёртывание старого выпуска. Первая команда также восстанавливает число серверов. Если она завершается ошибкой, но kubectl -n cma-server get pods показывает, что старые серверы готовы, см. раздел Если проверка ключа не прошла.

5. 5

   Удалите отложенную базу данных

   В этой базе данных по-прежнему хранится то, что клиенты записали после создания резервной копии. Когда старый выпуск заработает, удалите её командой DROP DATABASE <database>_upgraded;.

Если проверка ключа не прошла

На шаге «Разверните старый выпуск» первая команда helm upgrade ожидает готовности старых серверов. Затем она проверяет ключ, с которым подключаются песочницы. Если команда завершается ошибкой, но kubectl -n cma-server get pods показывает, что старые серверы готовы, значит, эта проверка не прошла.

Ваши данные восстановлены и серверы работают, но песочницы пока не могут к ним подключиться. Песочницы подключаются с ключом из Secret cma-environment в своём пространстве имён cma. Этот ключ новее вашей резервной копии, поэтому восстановленная база данных его не распознаёт.

Чтобы убедиться в причине, снова выполните первую команду. Пока она ожидает, откройте второй терминал и задайте $server и там. Затем выполните kubectl -n cma-server logs job/$server-environment-default, подставив имя вашего окружения вместо default. Найдите строку, содержащую Secret cma/cma-environment records key. Если журнал показывает другую ошибку, устраните то, на что она указывает.

Если журнал показывает эту строку, удалите Secret с помощью kubectl -n cma delete secret cma-environment и снова выполните первую команду. Она снова создаёт Secret с новым ключом. Затем выполните вторую команду.

Восстановление резервной копии в Docker Compose

1. 1

   Запустите только базу данных

   Выполните docker compose down в каталоге Compose нового выпуска. Затем выполните docker compose up -d --wait postgres в каталоге Compose старого выпуска. Оставайтесь в этом каталоге для следующих шагов.

2. 2

   Восстановите резервную копию в новую базу данных

   Из каталога Compose старого выпуска выполните эту команду, указав пути к вашему ключу и файлу резервной копии:

   docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d postgres \
       -c "DROP DATABASE IF EXISTS ${POSTGRES_DB}_restored" -c "CREATE DATABASE ${POSTGRES_DB}_restored"' \
     && age -d -i cma-backup.agekey cma_server-<old-version>.dump.age \
     | docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "${POSTGRES_DB}_restored" --no-owner --exit-on-error'

   

   Она прошла успешно, если выводит DROP DATABASE и CREATE DATABASE и никаких ошибок.

   Оставьте $POSTGRES_USER и $POSTGRES_DB без изменений здесь и на следующих шагах. Текст в одинарных кавычках выполняется внутри контейнера postgres, в котором эти переменные содержат имена его роли и базы данных.

   Если команда выводит ошибку, ваша база данных не изменилась, поэтому можно снова выполнить всю команду. Если резервную копию не удаётся восстановить, выполните docker compose up --build -d в каталоге Compose нового выпуска, чтобы снова запустить этот выпуск.

3. 3

   Переключитесь на восстановленную базу данных

   docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d postgres \
       -c "ALTER DATABASE $POSTGRES_DB RENAME TO ${POSTGRES_DB}_upgraded" \
       -c "ALTER DATABASE ${POSTGRES_DB}_restored RENAME TO $POSTGRES_DB"'

   
4. 4

   Запустите старый выпуск

   Выполните docker compose up --build -d.

5. 5

   Удалите отложенную базу данных

   В этой базе данных по-прежнему хранится то, что клиенты записали после создания резервной копии. Когда старый выпуск заработает, удалите её:

   docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d postgres -c "DROP DATABASE ${POSTGRES_DB}_upgraded"'

   

После восстановления

Восстановление возвращает ключи окружения в состояние на момент создания резервной копии:

• Ключ, который вы отозвали после создания резервной копии: он снова работает. Отзовите его повторно.
• Ключ, который вы создали после создания резервной копии: он удалён. Создайте новый ключ для воркеров, которые его использовали.

Команды приведены в разделе Замена ключа окружения для собственных воркеров. Они также работают в Docker Compose. Для песочниц, которые запускает стек Docker Compose, ничего делать не нужно, потому что стек заменяет их ключ при запуске.

Чтобы вывести список ключей окружения, включая отозванные, выполните list-keys следующим образом:

• Используйте терминал, который вы настроили в разделе Вызов API на самостоятельно размещаемом сервере. Не используйте терминал, в котором выполняется docker compose.
• В Kubernetes сначала выполните kubectl -n cma-server port-forward svc/$server 8400:8400 в другом терминале, задав $server и там.
• Выполняйте команду из верхнего каталога архива по одному разу для каждого окружения, указав ID этого окружения.

echo "$ANTHROPIC_API_KEY" | ./cma-server-admin list-keys \
  -base-url http://127.0.0.1:8400 -env env_01595EKxaaTTGwwY3kyXdtbs \
  -key-file - -all

Проверка резервной копии

Чтобы убедиться, что дамп восстанавливается, выполните только шаг «Восстановите резервную копию в новую базу данных». Он есть в разделах Восстановление резервной копии в Kubernetes и Восстановление резервной копии в Docker Compose. Этот шаг не изменяет используемую базу данных. Затем удалите новую базу данных. В Docker Compose её имя — это имя вашей базы данных с _restored в конце.

Настройки и пути для проверки

Прочитайте этот раздел перед выполнением команды обновления.

Проверьте раздел web_tools в вашем файле настроек. Если в файле нет такого раздела или в разделе не задан ни один ключ, после обновления инструменты web_search и web_fetch отключены. В этом случае агент, использующий набор инструментов по умолчанию, работает без них и без ошибок. Агент, в наборе инструментов которого включён любой из этих инструментов, не может начать сеанс. Чтобы сохранить эти инструменты, см. раздел Веб-инструментам нужна настройка сервера.

В Kubernetes убедитесь, что в каждом файле значений песочниц, например cma-values.yaml, задан egress.mode. Чтобы сохранить доступ песочниц к общедоступному интернету, добавьте mode: publicInternet в egress. Если в файле не задан режим, чарт применяет свой режим по умолчанию — closed. Тогда команда helm upgrade для чарта песочниц останавливается с ошибкой вида egress.mode is closed and egress.closed.hosts is empty и ничего не изменяет.

Проверьте sandbox.idleTimeout в тех же файлах. Если в файле этот параметр не задан, под сеанса удаляется примерно через 5 минут после окончания хода агента. Процессы, которые агент оставил запущенными, останавливаются вместе с подом. По умолчанию файлы в /workspace сохраняются. Чтобы сохранять под в течение 30 минут, добавьте idleTimeout: 30m в sandbox.

Проверьте наличие inference.attribution в файле настроек и CMA_INFERENCE__ATTRIBUTION в окружении сервера. Если найдёте такую строку, удалите её. В выпуске, до которого вы обновляетесь, этой настройки нет, и его сервер не запускается, если задано любое из этих значений.

Когда ваш “inference provider” (поставщик инференса) — Claude API, после обновления каждый вызов модели передаёт ID своего сеанса, а также агента и окружения этого сеанса. См. раздел Что сервер отправляет своему поставщику инференса.

Kubernetes: имена ваших объектов

В файле cma-server-values.yaml в параметре earlierNames должно быть указано, какие имена использует ваша установка. Чтобы узнать имя Deployment сервера, выполните kubectl -n cma-server get deployment -l anthropic.com/role=server.

Если в файле нет этой строки, добавьте её перед обновлением и сохраняйте её при всех последующих обновлениях. Без неё команда helm upgrade для чарта сервера останавливается с ошибкой, в которой упоминается earlierNames, и ничего не изменяет.

При earlierNames: true объекты чарта сохраняют имена cma-onprem, и серверы по-прежнему находят Secret, созданные вами под этими именами. На этих страницах используются имена из среднего столбца. При earlierNames: true используйте вместо них имена из последнего столбца:

Независимо от значения earlierNames, пространство имён называется cma-server, а образ сервера — cma-server-image.

Каждый файл значений песочниц, в котором задан egress.mode: gateway, должен указывать два Service сервера в egress.gateway. Если в файле этого нет, добавьте обе строки. В этом примере приведены имена для установки с earlierNames: true:

egress:
  gateway:
    serverService: cma-onprem
    serverEgressService: cma-onprem-egress

Docker Compose: структура архива и пути

Если в выпуске, с которого вы обновляетесь, нет каталога compose, его docker-compose.yml находится в корне архива, рядом с bin. В новом архиве этот файл находится на один уровень глубже, в compose.

На шаге «Повторите остальные изменения» также внесите следующие изменения:

• Собственный файл Compose: если в старом архиве не было каталога compose, ваш файл тоже перемещается на один уровень глубже. Путь вида ./bin в нём становится ../bin. Если в файле указан сервис cma-onprem, измените это имя на cma-server.
• Пути в /etc/cma-onprem/ или /run/cma-onprem/: измените каждый из них так, чтобы он начинался с /etc/cma-server/ или /run/cma-server/. Проверьте .env и compose.config.yaml нового выпуска, собственный файл Compose и каждую добавленную вами строку volumes:. В строке volumes: изменяйте только часть после первого двоеточия — путь внутри контейнера.