Aggiornare Claude Managed Agents self-hosted

Questa pagina mostra come aggiornare un deployment su Kubernetes o Docker Compose, e come eseguire il rollback. Su Kubernetes, il downtime dipende da quanto è ampio l’aggiornamento:

Uno stack Docker Compose non è disponibile durante il riavvio, per ogni tipo di aggiornamento.

Prima di aggiornare

Leggi la sezione della nuova release in CHANGELOG.md, all’inizio dell’archivio estratto. Inizia con i passaggi di aggiornamento specifici di quella release. Se salti delle release, segui ogni sezione più recente della tua versione, partendo dalla meno recente.

Poi consulta Impostazioni e percorsi da verificare.

Un aggiornamento minor o major include un backup del database. Il dump contiene ogni conversazione in chiaro, quindi i comandi in questa pagina lo cifrano con lo strumento di cifratura age. Crea una coppia di chiavi una volta sola e conserva la chiave privata, cma-backup.agekey, separata dai backup:

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

Aggiornare su Kubernetes

I comandi kubectl in questa pagina leggono il nome del Deployment del server da una variabile di shell. Esegui queste due righe in ogni terminale in cui esegui i comandi. La prima riga cerca il nome, e la seconda lo stampa:

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

Se la seconda riga stampa cma-server, prosegui. Se stampa un altro nome, leggi i nomi dei tuoi oggetti prima di aggiornare. Se non stampa nulla, verifica che kubectl punti al cluster corretto, ed esegui di nuovo le due righe.

1. 1

   Compilare e caricare le nuove immagini

   Estrai il nuovo archivio. Compila e carica le sue tre immagini con la nuova versione, come descritto in Compilare e caricare le immagini. Se esegui l’egress gateway, compila e carica anche la sua immagine.

   Se compili una tua immagine per le sandbox, ricompilala e caricala anch’essa, con la nuova versione. Confronta il suo Dockerfile con kubernetes/sandbox/Dockerfile nel nuovo archivio, e consulta cosa serve a una tua immagine.

2. 2

   Impostare la nuova versione nei file di valori

   Se un file di valori imposta image.tag, cambialo con la nuova versione.

3. 3

   Arrestare tutti i server, se l’aggiornamento lo richiede

   Esegui questo passaggio solo in questi casi:

   • Un server che esegui è indietro di più di una release minor rispetto alla nuova release.
   • Il primo numero, la versione major, aumenta.
   • Una sezione di CHANGELOG.md più recente della release che esegui indica che i server devono essere arrestati.

   Da questo passaggio fino a quando i nuovi server sono pronti, i client non possono raggiungere il deployment, quindi pianifica una finestra di manutenzione.

   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

   Eseguire il backup del database

   Fallo prima di un aggiornamento minor o major, o se hai arrestato i server. Se la release precedente non può essere eseguita sullo schema modificato, questo backup è l’unico modo per tornare indietro.

   Usa pg_dump della stessa versione principale di PostgreSQL del tuo server di database. Per <role> e <database>, usa i valori user e dbname di database.url in cma-server-values.yaml. pg_dump richiede la password del ruolo.

   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 uno dei due comandi stampa un errore, il file che lascia non è un backup. Correggi la causa ed esegui di nuovo il comando prima di proseguire.

   Se i server sono in esecuzione, il backup contiene solo ciò che i client hanno scritto prima dell’avvio del dump.

5. 5

   Aggiornare il server, poi le sandbox

   Esegui questi comandi dalla directory principale del nuovo archivio, usando i file di valori della tua installazione:

   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 esegui più di un ambiente, esegui il secondo comando per ogni release delle sandbox, con il nome, il namespace e il file di valori di quella release.

   Se hai arrestato i server, il primo comando migra lo schema, ripristina il numero di server e termina quando i nuovi server sono pronti.

Con i server in esecuzione, Helm avvia ogni nuovo server prima di arrestarne uno vecchio, quindi il numero di server pronti non diminuisce mai. In un aggiornamento minor, il primo comando modifica lo schema mentre i vecchi server restano in servizio, e poi li sostituisce. Uno stream di eventi aperto su un server in fase di sostituzione termina in modo pulito, quindi un client che segue uno stream deve riconnettersi.

Se un comando non riesce, consulta Se l’aggiornamento non riesce.

Aggiornare su Docker Compose

I passaggi sono gli stessi per ogni tipo di aggiornamento. Esegui ogni comando docker compose dalla directory Compose di una release, ovvero la directory che contiene docker-compose.yml. Nell’archivio estratto, quella directory è compose. Usa un terminale in cui ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN non sono impostate, perché Compose passa al server i valori di quelle variabili presenti nella shell.

1. 1

   Esegui il backup del database

   Fallo prima di un aggiornamento minor o major, dalla directory Compose della vecchia release:

   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

   

   Nel comando, lascia $POSTGRES_USER e $POSTGRES_DB così come sono. Il testo tra apici singoli viene eseguito all’interno del container postgres, che contiene in quelle variabili i nomi del suo ruolo e del suo database.

   Lo stack resta in servizio durante il backup, quindi il dump non include ciò che i client scrivono dopo l’avvio del dump. Se uno dei due comandi stampa un errore, il file che lascia non è un backup. Correggi la causa ed esegui di nuovo il comando prima di proseguire.

2. 2

   Estrai il nuovo archivio

   Posiziona il nuovo archivio in una directory in cui la nuova release possa restare, come la directory padre della vecchia release. I comandi estraggono l’archivio lì, e il nuovo stack viene eseguito dai file estratti.

   Se la tua umask è più restrittiva di 022, esegui prima umask 022. Poi esegui questo comando dalla directory Compose della vecchia release. Al posto di <directory>, scrivi il percorso completo della directory che contiene il nuovo archivio. Al posto di <archive>, scrivi il nome dell’archivio senza .tar.gz.

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

   

   La seconda riga copia anche i tuoi .env e compose.config.yaml nella directory compose estratta. Il vecchio stack resta in esecuzione durante entrambe le righe. Se una riga stampa un errore, correggi la causa ed esegui di nuovo entrambe le righe.

3. 3

   Ripeti le altre modifiche

   Vengono trasferiti solo .env e compose.config.yaml. Applica di nuovo le altre modifiche nella directory Compose della nuova release:

   • Un file che hai aggiunto: copialo.
   • Un file fornito che hai modificato: applica la stessa modifica alla copia della nuova release. Non copiarci sopra il vecchio file, perché annullerebbe le modifiche della release a quel file.
   • Identità dell’agente: copia la directory agent-identity con cp -a, usando sudo se appartiene a root, e modifica di nuovo il blocco volumes: di docker-compose.yml.
   • Un tuo file Compose: copialo e controlla i suoi percorsi relativi.

   Poi applica le modifiche per Docker Compose descritte in Impostazioni e percorsi da verificare.

4. 4

   Arresta il vecchio stack e avvia quello nuovo

   Esegui queste righe nel terminale in cui hai estratto l’archivio, perché usano la sua variabile $releases. Resta nella directory Compose della vecchia release, e scrivi lo stesso nome al posto di <archive>. Se hai esportato COMPOSE_FILE per il vecchio stack, esporta prima lo stesso valore.

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

   

   La prima riga arresta il vecchio stack solo se il .env della nuova release è al suo posto. docker compose down mantiene il database. Non aggiungere -v, che lo elimina. Il nuovo stack riprende il database, e il suo container migrate aggiorna lo schema prima che il server si avvii.

Se un comando non riesce, consulta Se l’aggiornamento non riesce.

Se l’aggiornamento non riesce

Prima di eseguire il rollback, trova la causa nel log:

• Kubernetes: se il Job di migrazione non riesce, helm upgrade attende alcuni minuti mentre il Job riprova, e poi non riesce. Durante questa attesa, esegui kubectl -n cma-server logs job/$server-migrate in un secondo terminale, con $server impostato come in Aggiornare su Kubernetes. Kubernetes elimina il log quando il Job smette di riprovare. Se non l’hai letto in tempo, esegui di nuovo helm upgrade, che avvia di nuovo il Job.
• Docker Compose: l’output di docker compose up --build -d potrebbe non mostrare il motivo. Esegui docker compose logs per trovarlo.

La migrazione può riuscire senza che i nuovi server diventino pronti. Per trovare la causa, leggi il log dei server:

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

Ad esempio, su Kubernetes, una riga che contiene has invalid keys nomina un’impostazione sotto server.config che la nuova release non accetta. Correggi la causa ed esegui di nuovo il comando di aggiornamento prima di valutare un ripristino, perché un ripristino fa perdere dati. Su Kubernetes, una volta modificato lo schema, un server della vecchia release in esecuzione resta in servizio, ma potrebbe non avviarsi di nuovo se si arresta.

Eseguire il rollback

I comandi kubectl in questa sezione usano la variabile $server di Aggiornare su Kubernetes. Prima di eseguire il rollback, controlla Se l’aggiornamento non riesce. Poi esegui il rollback in base al tipo di aggiornamento:

• Dopo un aggiornamento patch: Distribuire di nuovo la release precedente. Entrambe le release usano lo stesso schema.
• Dopo un aggiornamento minor o major: apri CHANGELOG.md nel nuovo archivio. Leggi la sezione di ogni release successiva a quella a cui stai tornando.
  • Se una sezione indica che la release precedente non può avviarsi sul database migrato, ripristina il backup.
  • Altrimenti, distribuisci di nuovo la release precedente. Se questo non riesce con cannot downgrade, ripristina il backup.

Distribuire di nuovo la release precedente

• Kubernetes: vai alla directory principale del vecchio archivio. Esegui i due comandi helm upgrade di Aggiornare su Kubernetes, con i file di valori com’erano per quella release. Ad esempio, se hai aggiunto earlierNames per l’aggiornamento, rimuovilo. Esegui il secondo comando solo quando il primo riesce.
• Docker Compose: esegui docker compose down nella directory Compose della nuova release, e poi docker compose up --build -d in quella della vecchia.

Se la vecchia release non può funzionare sullo schema modificato, il log mostra cannot downgrade:

• Kubernetes: il Job di migrazione non riesce e i server restano come sono. Se l’aggiornamento non riesce spiega come leggere il log del Job.
• Docker Compose: il server non si avvia. Leggi il log con docker compose logs migrate.

Su Docker Compose, l’output di docker compose logs potrebbe invece mostrare stored value is encrypted but no encryption key is configured. In tal caso, il .env della vecchia release non ha una riga CMA_STORE__CREDENTIALS_ENCRYPTION_KEY. Copia quella riga dal .env della nuova release ed esegui di nuovo docker compose up --build -d.

Ripristinare il backup su Kubernetes

Il tuo server di database ha bisogno di spazio per una seconda copia del database. Per <role> e <database>, usa i valori user e dbname di database.url in cma-server-values.yaml.

1. 1

   Ripristina il backup in un nuovo database

   Connettiti al database postgres sul tuo server di database come amministratore ed esegui:

   CREATE DATABASE <database>_restored OWNER <role>;

   

   Poi, sulla macchina che contiene il backup, esegui questo comando con i percorsi della tua chiave e del file di backup. Usa un pg_restore della stessa versione principale del tuo server di database. Chiede la password del ruolo e non stampa nulla se funziona.

   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 stampa un errore, fermati. Il tuo database non è cambiato. Esegui DROP DATABASE <database>_restored; come amministratore e ricomincia questo passaggio.

2. 2

   Arresta tutti i server

   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

   Passa al database ripristinato

   Connettiti al database postgres come amministratore ed esegui:

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

   

   Se la prima istruzione indica che altre sessioni stanno usando il database, chiudi quelle sessioni ed esegui di nuovo entrambe le istruzioni. Un connection pooler può mantenere aperte sessioni di questo tipo.

4. 4

   Distribuisci la vecchia release

   Segui la voce Kubernetes di Distribuire di nuovo la release precedente. Il primo comando ripristina anche il numero di server. Se non riesce ma kubectl -n cma-server get pods mostra che i vecchi server sono pronti, consulta Se la verifica della chiave non riesce.

5. 5

   Elimina il database che hai messo da parte

   Quel database contiene ancora ciò che i client hanno scritto dopo il backup. Quando la vecchia release funziona, eliminalo con DROP DATABASE <database>_upgraded;.

Se la verifica della chiave non riesce

Nel passaggio “Distribuisci la vecchia release”, il primo comando helm upgrade attende che i vecchi server siano pronti. Poi verifica la chiave con cui si connettono le sandbox. Se il comando non riesce ma kubectl -n cma-server get pods mostra che i vecchi server sono pronti, quella verifica non è riuscita.

I tuoi dati sono ripristinati e i server funzionano, ma le sandbox non possono ancora connettersi a essi. Le sandbox si connettono con una chiave del Secret cma-environment nel loro namespace, cma. Quella chiave è più recente del tuo backup, quindi il database ripristinato non la riconosce.

Per confermare la causa, esegui di nuovo il primo comando. Mentre attende, apri un secondo terminale e imposta anche lì $server. Poi esegui kubectl -n cma-server logs job/$server-environment-default, con il nome del tuo ambiente al posto di default. Cerca una riga che contiene Secret cma/cma-environment records key. Se il log mostra un altro errore, correggi ciò che indica.

Se il log mostra quella riga, elimina il Secret con kubectl -n cma delete secret cma-environment ed esegui di nuovo il primo comando. Crea di nuovo il Secret, con una nuova chiave. Poi esegui il secondo comando.

Ripristinare il backup su Docker Compose

1. 1

   Avvia solo il database

   Esegui docker compose down nella directory Compose della nuova release. Poi esegui docker compose up -d --wait postgres nella directory Compose della vecchia release. Resta in quella directory per i passaggi successivi.

2. 2

   Ripristina il backup in un nuovo database

   Dalla directory Compose della vecchia release, esegui questo comando con i percorsi della tua chiave e del file di 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'

   

   È riuscito se stampa DROP DATABASE e CREATE DATABASE e nessun errore.

   Lascia $POSTGRES_USER e $POSTGRES_DB così come sono, qui e nei passaggi successivi. Il testo tra apici singoli viene eseguito all’interno del container postgres, che contiene in quelle variabili i nomi del suo ruolo e del suo database.

   Se stampa un errore, il tuo database non è cambiato, quindi puoi eseguire di nuovo l’intero comando. Se il backup non può essere ripristinato, esegui docker compose up --build -d nella directory Compose della nuova release per avviare di nuovo quella release.

3. 3

   Passa al database ripristinato

   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

   Avvia la vecchia release

   Esegui docker compose up --build -d.

5. 5

   Elimina il database che hai messo da parte

   Quel database contiene ancora ciò che i client hanno scritto dopo il backup. Quando la vecchia release funziona, eliminalo:

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

   

Dopo un ripristino

Un ripristino riporta le chiavi di ambiente al momento del backup:

• Una chiave che hai revocato dopo il backup: funziona di nuovo. Revocala di nuovo.
• Una chiave che hai creato dopo il backup: non esiste più. Crea una nuova chiave per i worker che la usavano.

Sostituire una chiave di ambiente per i tuoi worker contiene i comandi, che funzionano anche su Docker Compose. Le sandbox avviate dallo stack Docker Compose non richiedono alcuna azione, perché lo stack sostituisce la loro chiave quando si avvia.

Per elencare le chiavi di un ambiente, incluse quelle revocate, esegui list-keys come segue:

• Usa il terminale che hai configurato in Chiamare l’API su un server self-hosted. Non usare il terminale che esegue docker compose.
• Su Kubernetes, esegui prima kubectl -n cma-server port-forward svc/$server 8400:8400 in un altro terminale, impostando anche lì $server.
• Esegui il comando dalla directory principale dell’archivio, una volta per ciascun ambiente, con l’ID di quell’ambiente.

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

Testare un backup

Per verificare che un dump si possa ripristinare, esegui solo il passaggio “Ripristina il backup in un nuovo database”. Si trova in Ripristinare il backup su Kubernetes e in Ripristinare il backup su Docker Compose. Quel passaggio non modifica il database in uso. Poi elimina il nuovo database. Su Docker Compose, il suo nome è il nome del tuo database con _restored alla fine.

Impostazioni e percorsi da verificare

Leggi questa sezione prima di eseguire un comando di aggiornamento.

Controlla la sezione web_tools del tuo file delle impostazioni. Se il file non ha tale sezione, o se la sezione non imposta alcuna chiave, gli strumenti web_search e web_fetch sono disattivati dopo l’aggiornamento. Un agente che usa il set di strumenti predefinito viene quindi eseguito senza di essi, senza alcun errore. Un agente il cui set di strumenti attiva uno dei due strumenti non può avviare una sessione. Per mantenere gli strumenti, consulta Gli strumenti web richiedono un’impostazione del server.

Su Kubernetes, verifica che ogni file di valori delle sandbox, come cma-values.yaml, imposti egress.mode. Per mantenere l’accesso delle tue sandbox a Internet pubblico, aggiungi mode: publicInternet sotto egress. Se un file non imposta alcuna modalità, il chart applica la sua modalità predefinita, closed. Il comando helm upgrade del chart delle sandbox si arresta quindi con un errore come egress.mode is closed and egress.closed.hosts is empty e non modifica nulla.

Controlla sandbox.idleTimeout negli stessi file. Se un file non lo imposta, il pod di una sessione viene rimosso circa 5 minuti dopo la fine del turno dell’agente. I processi che l’agente ha lasciato in esecuzione si arrestano insieme al pod. Per impostazione predefinita, i file in /workspace restano. Per mantenere il pod per 30 minuti, aggiungi idleTimeout: 30m sotto sandbox.

Cerca inference.attribution nel file delle impostazioni, e CMA_INFERENCE__ATTRIBUTION nell’ambiente del server. Elimina la riga se ne trovi una. La release a cui stai aggiornando non ha questa impostazione, e il suo server non si avvia se una delle due è impostata.

Quando l’API Claude è il tuo provider di inferenza, dopo l’aggiornamento ogni chiamata al modello riporta gli ID della sua sessione e dell’agente e dell’ambiente di quella sessione. Consulta Cosa invia il server al suo provider di inferenza.

Kubernetes: i nomi dei tuoi oggetti

cma-server-values.yaml deve indicare quali nomi ha la tua installazione, nella sua impostazione earlierNames. Per trovare il nome del Deployment del server, esegui kubectl -n cma-server get deployment -l anthropic.com/role=server.

Se il file non ha la riga, aggiungila prima di aggiornare, e mantienila per ogni aggiornamento successivo. Senza di essa, il comando helm upgrade del chart del server si arresta con un errore che nomina earlierNames e non modifica nulla.

Con earlierNames: true, gli oggetti del chart mantengono i loro nomi cma-onprem, e i server trovano ancora i Secret che hai creato con quei nomi. Queste pagine usano i nomi nella colonna centrale. Con earlierNames: true, usa invece i nomi nell’ultima colonna:

Qualunque cosa indichi earlierNames, il namespace si chiama cma-server e l’immagine del server si chiama cma-server-image.

Ogni file di valori delle sandbox che imposta egress.mode: gateway deve nominare i due Service del server, sotto egress.gateway. Se un file non lo fa, aggiungi entrambe le righe. Questo esempio ha i nomi per un’installazione con earlierNames: true:

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

Docker Compose: la struttura e i percorsi dell’archivio

Se la release da cui stai aggiornando non ha una directory compose, il suo docker-compose.yml si trova al livello principale dell’archivio, accanto a bin. Nel nuovo archivio, quel file si trova un livello più in profondità, in compose.

Nel passaggio “Ripeti le altre modifiche”, applica anche queste modifiche:

• Un tuo file Compose: se il vecchio archivio non aveva una directory compose, anche il tuo file va un livello più in profondità. Un percorso come ./bin al suo interno diventa ../bin. Se il file nomina il servizio cma-onprem, cambia quel nome in cma-server.
• Percorsi sotto /etc/cma-onprem/ o /run/cma-onprem/: modifica ciascuno in modo che inizi con /etc/cma-server/ o /run/cma-server/. Cerca nei file .env e compose.config.yaml della nuova release, in un tuo file Compose e in ogni riga volumes: che hai aggiunto. In una riga volumes:, modifica solo la parte dopo i primi due punti, che è il percorso all’interno del container.