Atualizar o Claude Managed Agents auto-hospedado

Esta página mostra como atualizar uma implantação no Kubernetes ou no Docker Compose e como reverter. No Kubernetes, o downtime depende de até onde vai a atualização:

Uma stack do Docker Compose fica fora do ar enquanto reinicia, em todos os tipos de atualização.

Antes de atualizar

Leia a seção da versão nova no CHANGELOG.md, na raiz do arquivo compactado extraído. Ela começa com as etapas de atualização específicas dessa versão. Se você pular versões, siga todas as seções mais recentes que a sua versão, da mais antiga para a mais nova.

Em seguida, revise Configurações e caminhos a verificar.

Uma atualização secundária ou principal inclui um backup do banco de dados. O dump contém todas as conversas em texto simples, por isso os comandos nesta página o criptografam com a ferramenta de criptografia age. Crie um par de chaves uma vez e mantenha a chave privada, cma-backup.agekey, longe dos backups:

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

Atualizar no Kubernetes

Os comandos kubectl nesta página leem o nome do Deployment do servidor a partir de uma variável de shell. Execute estas duas linhas em cada terminal em que você executar os comandos. A primeira linha procura o nome, e a segunda o imprime:

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

Se a segunda linha imprimir cma-server, continue. Se imprimir outro nome, leia os nomes dos seus objetos antes de atualizar. Se não imprimir nada, verifique se o kubectl aponta para o cluster correto e execute as duas linhas novamente.

1. 1

   Crie e envie as novas imagens

   Extraia o novo arquivo compactado. Crie e envie suas três imagens com a nova versão, como em Criar e enviar as imagens. Se você executa o egress gateway (gateway de saída), crie e envie a imagem dele também.

   Se você cria uma imagem de sandbox própria, recrie-a e envie-a também, com a nova versão. Compare o Dockerfile dela com kubernetes/sandbox/Dockerfile no novo arquivo compactado e consulte o que uma imagem própria precisa.

2. 2

   Defina a nova versão nos seus arquivos de valores

   Se um arquivo de valores define image.tag, altere-o para a nova versão.

3. 3

   Pare todos os servidores, se a atualização exigir

   Execute esta etapa somente nestes casos:

   • Um servidor que você executa está mais de uma versão minor atrás da nova versão.
   • O primeiro número, a versão principal, aumenta.
   • No CHANGELOG.md, uma seção mais recente que a versão que você executa diz que os servidores devem parar.

   Desde esta etapa até que os novos servidores estejam prontos, os clientes não conseguem acessar a implantação, então planeje uma janela de manutenção.

   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

   Faça backup do banco de dados

   Faça isto antes de uma atualização minor ou major, ou se você parou os servidores. Se a versão antiga não puder ser executada no esquema alterado, este backup é a única forma de voltar atrás.

   Use o pg_dump da mesma versão principal do PostgreSQL que o seu servidor de banco de dados. No lugar de <role> e <database>, use os valores user e dbname de database.url em cma-server-values.yaml. O pg_dump solicita a senha da role.

   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

   

   Se qualquer um dos comandos exibir um erro, o arquivo que ele deixar não é um backup. Corrija a causa e execute o comando novamente antes de continuar.

   Se os servidores estiverem em execução, o backup contém apenas o que os clientes escreveram antes de o dump começar.

5. 5

   Atualize o servidor e depois os sandboxes

   Execute estes comandos a partir do diretório raiz do novo arquivo compactado, usando os arquivos de valores da sua instalação:

   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

   

   Se você executa mais de um ambiente, execute o segundo comando para cada release do sandbox, com o nome, o namespace e o arquivo de valores dessa release.

   Se você parou os servidores, o primeiro comando migra o esquema, restaura a contagem de servidores e retorna assim que os novos servidores estiverem prontos.

Com os servidores em execução, o Helm inicia cada novo servidor antes de parar um antigo, então o número de servidores prontos nunca diminui. Em uma atualização minor, o primeiro comando altera o esquema enquanto os servidores antigos continuam atendendo e, em seguida, os substitui. Um stream de eventos aberto em um servidor que está sendo substituído termina de forma limpa, portanto um cliente que acompanha um stream precisa se reconectar.

Se um comando falhar, consulte Se a atualização falhar.

Atualizar no Docker Compose

As etapas são as mesmas para todos os tipos de atualização. Execute cada comando docker compose a partir do diretório do Compose de uma versão, que é o diretório que contém docker-compose.yml. No arquivo compactado extraído, esse diretório é compose. Use um terminal em que ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN não estejam definidas, porque o Compose repassa ao servidor os valores dessas variáveis no shell.

1. 1

   Faça backup do banco de dados

   Faça isto antes de uma atualização secundária ou principal, a partir do diretório do Compose da versão antiga:

   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

   

   No comando, deixe $POSTGRES_USER e $POSTGRES_DB como estão. O texto entre aspas simples é executado dentro do contêiner postgres, que guarda os nomes da sua role e do seu banco de dados nessas variáveis.

   A stack continua atendendo durante o backup, então o dump não inclui o que os clientes escreverem depois que o dump começar. Se qualquer um dos comandos exibir um erro, o arquivo que ele deixar não é um backup. Corrija a causa e execute o comando novamente antes de continuar.

2. 2

   Extraia o novo arquivo compactado

   Coloque o novo arquivo compactado em um diretório onde a nova versão possa permanecer, como o diretório pai da versão antiga. Os comandos extraem o arquivo compactado ali, e a nova stack é executada a partir dos arquivos extraídos.

   Se a sua umask for mais restritiva que 022, execute umask 022 primeiro. Em seguida, execute o seguinte a partir do diretório do Compose da versão antiga. No lugar de <directory>, escreva o caminho completo do diretório que contém o novo arquivo compactado. No lugar de <archive>, escreva o nome do arquivo compactado sem .tar.gz.

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

   

   A segunda linha também copia seus .env e compose.config.yaml para o diretório compose extraído. A stack antiga continua em execução durante as duas linhas. Se uma linha exibir um erro, corrija a causa e execute as duas linhas novamente.

3. 3

   Refaça suas outras alterações

   Apenas .env e compose.config.yaml são transferidos. Faça suas outras alterações novamente no diretório do Compose da nova versão:

   • Um arquivo que você adicionou: Copie-o.
   • Um arquivo fornecido que você editou: Faça a mesma edição na cópia da nova versão. Não copie o arquivo antigo por cima dele, porque isso desfaz as alterações da versão nesse arquivo.
   • Identidade do agente: Copie o diretório agent-identity com cp -a, usando sudo se o root for o proprietário dele, e edite novamente o bloco volumes: de docker-compose.yml.
   • Um arquivo Compose próprio: Copie-o e verifique seus caminhos relativos.

   Em seguida, faça as alterações do Docker Compose em Configurações e caminhos a verificar.

4. 4

   Pare a stack antiga e inicie a nova

   Execute estas linhas no terminal em que você extraiu o arquivo compactado, porque elas usam a variável $releases dele. Permaneça no diretório do Compose da versão antiga e escreva o mesmo nome no lugar de <archive>. Se você exportou COMPOSE_FILE para a stack antiga, exporte o mesmo valor primeiro.

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

   

   A primeira linha para a stack antiga somente se o .env da nova versão estiver no lugar. O docker compose down mantém o banco de dados. Não adicione -v, que o exclui. A nova stack assume o banco de dados, e seu contêiner migrate atualiza o esquema antes de o servidor iniciar.

Se um comando falhar, consulte Se a atualização falhar.

Se a atualização falhar

Antes de reverter, encontre a causa no log:

• Kubernetes: Se o Job de migração falhar, o helm upgrade aguarda alguns minutos enquanto o Job tenta novamente e, em seguida, falha. Durante essa espera, execute kubectl -n cma-server logs job/$server-migrate em um segundo terminal, com $server definido como em Atualizar no Kubernetes. O Kubernetes exclui o log quando o Job para de tentar novamente. Se você não conseguiu lê-lo, execute helm upgrade novamente, o que inicia o Job outra vez.
• Docker Compose: A saída de docker compose up --build -d pode não mostrar o motivo. Execute docker compose logs para encontrá-lo.

A migração pode ser concluída com sucesso enquanto os novos servidores não ficam prontos. Para encontrar a causa, leia o log dos servidores:

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

Por exemplo, no Kubernetes, uma linha que contém has invalid keys nomeia uma configuração em server.config que a nova versão não aceita. Corrija a causa e execute o comando de atualização novamente antes de considerar uma restauração, porque uma restauração perde dados. No Kubernetes, depois que o esquema muda, um servidor da versão antiga em execução continua atendendo, mas pode não iniciar novamente se parar.

Reverter

Os comandos kubectl nesta seção usam a variável $server de Atualizar no Kubernetes. Antes de reverter, verifique Se a atualização falhar. Em seguida, reverta de acordo com o tipo de atualização:

• Após uma atualização de patch: Implante a versão antiga novamente. As duas versões usam o mesmo esquema.
• Após uma atualização minor ou major: Abra o CHANGELOG.md no novo arquivo compactado. Leia a seção de cada versão que veio depois daquela para a qual você está voltando.
  • Se uma seção disser que a versão antiga não consegue iniciar no banco de dados migrado, restaure o backup.
  • Caso contrário, implante a versão antiga novamente. Se isso falhar com cannot downgrade, restaure o backup.

Implantar a versão antiga novamente

• Kubernetes: Vá para o diretório de nível superior do arquivo compactado antigo. Execute os dois comandos helm upgrade de Atualizar no Kubernetes, com os arquivos de valores como estavam para essa versão. Por exemplo, se você adicionou earlierNames para a atualização, remova-o. Execute o segundo comando somente quando o primeiro for concluído com sucesso.
• Docker Compose: Execute docker compose down no diretório do Compose da nova versão e, em seguida, docker compose up --build -d no diretório da versão antiga.

Se a versão antiga não puder ser executada no esquema alterado, o log mostra cannot downgrade:

• Kubernetes: O Job de migração falha e os servidores permanecem como estão. Se a atualização falhar explica como ler o log do Job.
• Docker Compose: O servidor não inicia. Leia o log com docker compose logs migrate.

No Docker Compose, a saída de docker compose logs pode mostrar, em vez disso, stored value is encrypted but no encryption key is configured. Nesse caso, o .env da versão antiga não tem a linha CMA_STORE__CREDENTIALS_ENCRYPTION_KEY. Copie essa linha do .env da nova versão e execute docker compose up --build -d novamente.

Restaurar o backup no Kubernetes

Seu servidor de banco de dados precisa de espaço para uma segunda cópia do banco de dados. No lugar de <role> e <database>, use os valores user e dbname de database.url em cma-server-values.yaml.

1. 1

   Restaure o backup em um novo banco de dados

   Conecte-se ao banco de dados postgres no seu servidor de banco de dados como administrador e execute:

   CREATE DATABASE <database>_restored OWNER <role>;

   

   Em seguida, na máquina que contém o backup, execute isto com os caminhos da sua chave e do arquivo de backup. Use um pg_restore da mesma versão principal que o seu servidor de banco de dados. Ele solicita a senha da role e não imprime nada se funcionar.

   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

   

   Se isto imprimir um erro, pare. Seu banco de dados não foi alterado. Execute DROP DATABASE <database>_restored; como administrador e comece esta etapa novamente.

2. 2

   Pare todos os servidores

   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

   Mude para o banco de dados restaurado

   Conecte-se ao banco de dados postgres como administrador e execute:

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

   

   Se a primeira instrução disser que outras sessões estão usando o banco de dados, feche essas sessões e execute as duas instruções novamente. Um pool de conexões pode manter essas sessões.

4. 4

   Implante a versão antiga

   Siga o item do Kubernetes de Implantar a versão antiga novamente. O primeiro comando também restaura a contagem de servidores. Se ele falhar, mas kubectl -n cma-server get pods mostrar que os servidores antigos estão prontos, consulte Se a verificação da chave falhar.

5. 5

   Exclua o banco de dados que você separou

   Esse banco de dados ainda contém o que os clientes gravaram depois do backup. Quando a versão antiga funcionar, exclua-o com DROP DATABASE <database>_upgraded;.

Se a verificação da chave falhar

Na etapa “Implante a versão antiga”, o primeiro comando helm upgrade aguarda até que os servidores antigos estejam prontos. Em seguida, ele verifica a chave com a qual os sandboxes se conectam. Se o comando falhar, mas kubectl -n cma-server get pods mostrar que os servidores antigos estão prontos, essa verificação falhou.

Seus dados foram restaurados e os servidores funcionam, mas os sandboxes ainda não conseguem se conectar a eles. Os sandboxes se conectam com uma chave do Secret cma-environment no próprio namespace deles, cma. Essa chave é mais recente que o seu backup, então o banco de dados restaurado não a reconhece.

Para confirmar a causa, execute o primeiro comando novamente. Enquanto ele aguarda, abra um segundo terminal e defina $server nele também. Em seguida, execute kubectl -n cma-server logs job/$server-environment-default, com o nome do seu ambiente no lugar de default. Procure uma linha que contenha Secret cma/cma-environment records key. Se o log mostrar outro erro, corrija o que ele indica.

Se o log mostrar essa linha, exclua o Secret com kubectl -n cma delete secret cma-environment e execute o primeiro comando novamente. Ele cria o Secret outra vez, com uma nova chave. Em seguida, execute o segundo comando.

Restaurar o backup no Docker Compose

1. 1

   Inicie apenas o banco de dados

   Execute docker compose down no diretório do Compose da nova versão. Em seguida, execute docker compose up -d --wait postgres no diretório do Compose da versão antiga. Permaneça nesse diretório para as próximas etapas.

2. 2

   Restaure o backup em um novo banco de dados

   A partir do diretório do Compose da versão antiga, execute isto com os caminhos da sua chave e do arquivo de backup:

   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'

   

   Ela funcionou se imprimir DROP DATABASE e CREATE DATABASE, sem nenhum erro.

   Deixe $POSTGRES_USER e $POSTGRES_DB como estão, aqui e nas próximas etapas. O texto entre aspas simples é executado dentro do contêiner postgres, que guarda os nomes da sua role e do seu banco de dados nessas variáveis.

   Se imprimir um erro, seu banco de dados não foi alterado, então você pode executar o comando inteiro novamente. Se o backup não puder ser restaurado, execute docker compose up --build -d no diretório do Compose da nova versão para iniciar essa versão novamente.

3. 3

   Mude para o banco de dados restaurado

   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

   Inicie a versão antiga

   Execute docker compose up --build -d.

5. 5

   Exclua o banco de dados que você separou

   Esse banco de dados ainda contém o que os clientes gravaram depois do backup. Quando a versão antiga funcionar, exclua-o:

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

   

Após uma restauração

Uma restauração leva as chaves de ambiente de volta ao momento do backup:

• Uma chave que você revogou depois do backup: Ela volta a funcionar. Revogue-a novamente.
• Uma chave que você criou depois do backup: Ela deixa de existir. Crie uma nova chave para os workers que a usavam.

Substituir uma chave de ambiente para seus próprios workers contém os comandos, que também funcionam no Docker Compose. Os sandboxes que a stack do Docker Compose inicia não precisam de nenhuma ação, porque a stack substitui a chave deles quando inicia.

Para listar as chaves de um ambiente, incluindo as revogadas, execute list-keys da seguinte forma:

• Use o terminal que você configurou em Chamar a API em um servidor auto-hospedado. Não use o terminal que executa docker compose.
• No Kubernetes, execute primeiro kubectl -n cma-server port-forward svc/$server 8400:8400 em outro terminal, com $server definido nele também.
• Execute o comando a partir do diretório de nível superior do arquivo compactado, uma vez para cada ambiente, com o ID desse ambiente.

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

Testar um backup

Para comprovar que um dump pode ser restaurado, execute apenas a etapa “Restaure o backup em um novo banco de dados”. Ela está em Restaurar o backup no Kubernetes e em Restaurar o backup no Docker Compose. Essa etapa não altera o banco de dados em uso. Em seguida, exclua o novo banco de dados. No Docker Compose, o nome dele é o nome do seu banco de dados com _restored no final.

Configurações e caminhos a verificar

Leia esta seção antes de executar um comando de atualização.

Verifique a seção web_tools do seu arquivo de configurações. Se o arquivo não tiver essa seção, ou se a seção não definir nenhuma chave, as ferramentas web_search e web_fetch ficam desativadas após a atualização. Um agente que usa o conjunto de ferramentas padrão passa então a ser executado sem elas, sem nenhum erro. Um agente cujo conjunto de ferramentas ativa qualquer uma dessas ferramentas não consegue iniciar uma sessão. Para manter as ferramentas, consulte Ferramentas web precisam de uma configuração do servidor.

No Kubernetes, verifique se cada arquivo de valores do sandbox, como cma-values.yaml, define egress.mode. Para manter o acesso dos seus sandboxes à internet pública, adicione mode: publicInternet em egress. Se um arquivo não definir nenhum modo, o chart aplica seu modo padrão, closed. O comando helm upgrade do chart do sandbox então para com um erro como egress.mode is closed and egress.closed.hosts is empty e não altera nada.

Verifique sandbox.idleTimeout nos mesmos arquivos. Se um arquivo não o definir, o pod de uma sessão desaparece cerca de 5 minutos após o fim do turno do agente. Os processos que o agente deixou em execução param junto com o pod. Por padrão, os arquivos em /workspace permanecem. Para manter o pod por 30 minutos, adicione idleTimeout: 30m em sandbox.

Verifique se o arquivo de configurações contém inference.attribution e se o ambiente do servidor contém CMA_INFERENCE__ATTRIBUTION. Exclua a linha se encontrar alguma. A versão para a qual você está atualizando não tem essa configuração, e o servidor dela não inicia se qualquer uma das duas estiver definida.

Quando a Claude API é o seu provedor de inferência, cada chamada ao modelo leva, após a atualização, os IDs da sua sessão e do agente e do ambiente dessa sessão. Consulte O que o servidor envia ao seu provedor de inferência.

Kubernetes: os nomes dos seus objetos

O cma-server-values.yaml precisa informar quais nomes a sua instalação tem, na configuração earlierNames. Para encontrar o nome do Deployment do servidor, execute kubectl -n cma-server get deployment -l anthropic.com/role=server.

Se o arquivo não tiver essa linha, adicione-a antes de atualizar e mantenha-a ali para todas as atualizações posteriores. Sem ela, o comando helm upgrade do chart do servidor para com um erro que menciona earlierNames e não altera nada.

Com earlierNames: true, os objetos do chart mantêm seus nomes cma-onprem, e os servidores ainda encontram os Secrets que você criou com esses nomes. Estas páginas usam os nomes da coluna do meio. Com earlierNames: true, use os nomes da última coluna:

Independentemente do que earlierNames diga, o namespace se chama cma-server e a imagem do servidor se chama cma-server-image.

Cada arquivo de valores do sandbox que define egress.mode: gateway precisa nomear os dois Services do servidor, em egress.gateway. Se um arquivo não fizer isso, adicione as duas linhas. Este exemplo tem os nomes para uma instalação com earlierNames: true:

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

Docker Compose: a estrutura e os caminhos do arquivo compactado

Se a versão a partir da qual você está atualizando não tiver um diretório compose, o docker-compose.yml dela fica no nível superior do arquivo compactado, ao lado de bin. No novo arquivo compactado, esse arquivo está um nível mais abaixo, em compose.

Na etapa “Refaça suas outras alterações”, faça também estas alterações:

• Um arquivo Compose próprio: Se o arquivo compactado antigo não tinha um diretório compose, o seu arquivo também passa para um nível mais abaixo. Um caminho como ./bin nele passa a ser ../bin. Se o arquivo mencionar o serviço cma-onprem, altere esse nome para cma-server.
• Caminhos em /etc/cma-onprem/ ou /run/cma-onprem/: Altere cada um para começar com /etc/cma-server/ ou /run/cma-server/. Procure nos arquivos .env e compose.config.yaml da nova versão, em um arquivo Compose próprio e em cada linha volumes: que você adicionou. Em uma linha volumes:, altere apenas a parte depois dos primeiros dois-pontos, que é o caminho dentro do contêiner.