Actualizar Claude Managed Agents autoalojado

Esta página muestra cómo actualizar una implementación en Kubernetes o Docker Compose, y cómo revertir. En Kubernetes, el tiempo de inactividad depende de qué tan lejos llegue la actualización:

Un stack de Docker Compose queda inactivo mientras se reinicia, para cualquier tipo de actualización.

Antes de actualizar

Lee la sección de la nueva versión en CHANGELOG.md, en la raíz del archivo de la versión extraído. Comienza con los pasos de actualización específicos de esa versión. Si omites versiones, sigue cada sección más reciente que tu versión, empezando por la más antigua.

Luego revisa Ajustes y rutas que comprobar.

Una actualización menor o mayor incluye una copia de seguridad de la base de datos. El volcado contiene todas las conversaciones en texto sin cifrar, por lo que los comandos de esta página lo cifran con la herramienta de cifrado age. Crea un par de claves una sola vez y guarda la clave privada, cma-backup.agekey, lejos de las copias de seguridad:

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

Actualizar en Kubernetes

Los comandos kubectl de esta página leen el nombre del Deployment del servidor desde una variable de shell. Ejecuta estas dos líneas en cada terminal donde ejecutes los comandos. La primera línea busca el nombre y la segunda lo imprime:

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

Si la segunda línea imprime cma-server, continúa. Si imprime otro nombre, lee los nombres de tus objetos antes de actualizar. Si no imprime nada, comprueba que kubectl apunte al clúster correcto y ejecuta las dos líneas de nuevo.

1. 1

   Compila y sube las nuevas imágenes

   Extrae el nuevo archivo de la versión. Compila y sube sus tres imágenes con la nueva versión, como en Compilar y subir las imágenes. Si ejecutas el gateway de salida, compila y sube también su imagen.

   Si compilas una imagen de sandbox propia, vuelve a compilarla y súbela también, con la nueva versión. Compara su Dockerfile con kubernetes/sandbox/Dockerfile en el nuevo archivo de la versión y consulta lo que necesita una imagen propia.

2. 2

   Establece la nueva versión en tus archivos de valores

   Si un archivo de valores establece image.tag, cámbialo a la nueva versión.

3. 3

   Detén todos los servidores, si la actualización lo requiere

   Haz este paso solo en estos casos:

   • Un servidor que ejecutas está atrasado más de una versión menor respecto de la nueva versión.
   • El primer número, la versión mayor, aumenta.
   • Una sección de CHANGELOG.md más reciente que la versión que ejecutas indica que los servidores deben detenerse.

   Desde este paso hasta que los nuevos servidores estén listos, los clientes no pueden acceder a la implementación, así que planifica una ventana de mantenimiento.

   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

   Haz una copia de seguridad de la base de datos

   Haz esto antes de una actualización menor o mayor, o si detuviste los servidores. Si la versión anterior no puede ejecutarse con el esquema modificado, esta copia de seguridad es la única forma de volver atrás.

   Usa pg_dump de la misma versión principal de PostgreSQL que tu servidor de base de datos. En lugar de <role> y <database>, usa los valores user y dbname de database.url en cma-server-values.yaml. pg_dump solicita la contraseña del rol.

   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

   

   Si alguno de los comandos muestra un error, el archivo que deja no es una copia de seguridad. Corrige la causa y vuelve a ejecutar el comando antes de continuar.

   Si los servidores están en ejecución, la copia de seguridad contiene solo lo que los clientes escribieron antes de que comenzara el volcado.

5. 5

   Actualiza el servidor y luego los sandboxes

   Ejecuta estos comandos desde la raíz del nuevo archivo de la versión, con los archivos de valores de tu instalación:

   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

   

   Si ejecutas más de un entorno, ejecuta el segundo comando para cada release de sandboxes, con el nombre, el namespace y el archivo de valores de esa release.

   Si detuviste los servidores, el primer comando migra el esquema, restablece el número de servidores y termina una vez que los nuevos servidores están listos.

Con los servidores en ejecución, Helm inicia cada servidor nuevo antes de detener uno anterior, por lo que el número de servidores listos nunca disminuye. En una actualización menor, el primer comando cambia el esquema mientras los servidores anteriores siguen atendiendo solicitudes, y luego los reemplaza. Un flujo de eventos abierto en un servidor que se está reemplazando termina de forma limpia, así que un cliente que sigue un flujo tiene que volver a conectarse.

Si un comando falla, consulta Si la actualización falla.

Actualizar en Docker Compose

Los pasos son los mismos para cualquier tipo de actualización. Ejecuta cada comando docker compose desde el directorio de Compose de una versión, que es el directorio que contiene docker-compose.yml. En el archivo de la versión extraído, ese directorio es compose. Usa una terminal donde ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY y ANTHROPIC_AUTH_TOKEN no estén establecidas, porque Compose pasa al servidor los valores que tenga la shell para esas variables.

1. 1

   Haz una copia de seguridad de la base de datos

   Haz esto antes de una actualización menor o mayor, desde el directorio de Compose de la versión anterior:

   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

   

   En el comando, deja $POSTGRES_USER y $POSTGRES_DB tal como están. El texto entre comillas simples se ejecuta dentro del contenedor postgres, que guarda en esas variables los nombres de su rol y de su base de datos.

   El stack sigue atendiendo solicitudes durante la copia de seguridad, por lo que el volcado no incluye lo que los clientes escriban después de que comience el volcado. Si alguno de los comandos muestra un error, el archivo que deja no es una copia de seguridad. Corrige la causa y vuelve a ejecutar el comando antes de continuar.

2. 2

   Extrae el nuevo archivo de la versión

   Coloca el nuevo archivo de la versión en un directorio donde la nueva versión pueda quedarse, como el directorio padre de la versión anterior. Los comandos extraen el archivo allí, y el nuevo stack se ejecuta desde los archivos extraídos.

   Si tu umask es más estricta que 022, ejecuta primero umask 022. Luego ejecuta esto desde el directorio de Compose de la versión anterior. En lugar de <directory>, escribe la ruta completa del directorio que contiene el nuevo archivo de la versión. En lugar de <archive>, escribe el nombre del archivo sin .tar.gz.

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

   

   La segunda línea también copia tus .env y compose.config.yaml en el directorio compose extraído. El stack anterior sigue en ejecución durante ambas líneas. Si una línea muestra un error, corrige la causa y vuelve a ejecutar ambas líneas.

3. 3

   Repite tus otros cambios

   Solo se transfieren .env y compose.config.yaml. Vuelve a hacer tus otros cambios en el directorio de Compose de la nueva versión:

   • Un archivo que agregaste: Cópialo.
   • Un archivo incluido que editaste: Haz la misma edición en la copia de la nueva versión. No copies el archivo anterior encima, porque eso deshace los cambios que la versión hizo en el archivo.
   • Identidad del agente: Copia el directorio agent-identity con cp -a, usando sudo si root es su propietario, y vuelve a editar el bloque volumes: de docker-compose.yml.
   • Un archivo de Compose propio: Cópialo y comprueba sus rutas relativas.

   Luego haz los cambios de Docker Compose de Ajustes y rutas que comprobar.

4. 4

   Detén el stack anterior e inicia el nuevo

   Ejecuta estas líneas en la terminal donde extrajiste el archivo de la versión, porque usan su variable $releases. Permanece en el directorio de Compose de la versión anterior y escribe el mismo nombre en lugar de <archive>. Si exportaste COMPOSE_FILE para el stack anterior, exporta primero el mismo valor.

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

   

   La primera línea detiene el stack anterior solo si el .env de la nueva versión está en su lugar. docker compose down conserva la base de datos. No agregues -v, que la elimina. El nuevo stack toma la base de datos y su contenedor migrate actualiza el esquema antes de que se inicie el servidor.

Si un comando falla, consulta Si la actualización falla.

Si la actualización falla

Antes de revertir, busca la causa en el registro:

• Kubernetes: Si el Job de migración falla, helm upgrade espera unos minutos mientras el Job reintenta y luego falla. Durante esa espera, ejecuta kubectl -n cma-server logs job/$server-migrate en una segunda terminal, con $server establecida como en Actualizar en Kubernetes. Kubernetes elimina el registro cuando el Job deja de reintentar. Si no alcanzaste a leerlo, ejecuta helm upgrade de nuevo, lo que vuelve a iniciar el Job.
• Docker Compose: Es posible que la salida de docker compose up --build -d no muestre el motivo. Ejecuta docker compose logs para encontrarlo.

La migración puede tener éxito mientras los servidores nuevos no quedan listos. Para encontrar la causa, lee el registro de los servidores:

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

Por ejemplo, en Kubernetes, una línea que contiene has invalid keys nombra un ajuste debajo de server.config que la nueva versión no acepta. Corrige la causa y ejecuta el comando de actualización de nuevo antes de considerar una restauración, porque una restauración pierde datos. En Kubernetes, una vez que el esquema cambió, un servidor de la versión anterior que está en ejecución sigue atendiendo solicitudes, pero es posible que no vuelva a iniciarse si se detiene.

Revertir

Los comandos kubectl de esta sección usan la variable $server de Actualizar en Kubernetes. Antes de revertir, consulta Si la actualización falla. Luego revierte según el tipo de actualización:

• Después de una actualización de parche: Volver a implementar la versión anterior. Ambas versiones usan el mismo esquema.
• Después de una actualización menor o mayor: Abre CHANGELOG.md en el archivo de la nueva versión. Lee la sección de cada versión que vino después de aquella a la que vuelves.
  • Si una sección indica que la versión anterior no puede iniciarse con la base de datos migrada, restaura la copia de seguridad.
  • De lo contrario, vuelve a implementar la versión anterior. Si eso falla con cannot downgrade, restaura la copia de seguridad.

Volver a implementar la versión anterior

• Kubernetes: Ve a la raíz del archivo de la versión anterior. Ejecuta los dos comandos helm upgrade de Actualizar en Kubernetes, con los archivos de valores tal como estaban para esa versión. Por ejemplo, si agregaste earlierNames para la actualización, quítalo. Ejecuta el segundo comando solo cuando el primero tenga éxito.
• Docker Compose: Ejecuta docker compose down en el directorio de Compose de la nueva versión y luego docker compose up --build -d en el de la versión anterior.

Si la versión anterior no puede ejecutarse con el esquema modificado, el registro muestra cannot downgrade:

• Kubernetes: El Job de migración falla y los servidores se quedan como están. Si la actualización falla indica cómo leer el registro del Job.
• Docker Compose: El servidor no se inicia. Lee el registro con docker compose logs migrate.

En Docker Compose, es posible que la salida de docker compose logs muestre en su lugar stored value is encrypted but no encryption key is configured. En ese caso, el .env de la versión anterior no tiene la línea CMA_STORE__CREDENTIALS_ENCRYPTION_KEY. Copia esa línea del .env de la nueva versión y ejecuta docker compose up --build -d de nuevo.

Restaurar la copia de seguridad en Kubernetes

Tu servidor de base de datos necesita espacio para una segunda copia de la base de datos. En lugar de <role> y <database>, usa los valores user y dbname de database.url en cma-server-values.yaml.

1. 1

   Restaura la copia de seguridad en una base de datos nueva

   Conéctate a la base de datos postgres de tu servidor de base de datos como administrador y ejecuta:

   CREATE DATABASE <database>_restored OWNER <role>;

   

   Luego, en la máquina que contiene la copia de seguridad, ejecuta esto con las rutas de tu clave y de tu archivo de copia de seguridad. Usa un pg_restore de la misma versión principal que tu servidor de base de datos. Solicita la contraseña del rol y no imprime nada si funciona.

   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

   

   Si esto imprime un error, detente. Tu base de datos no ha cambiado. Ejecuta DROP DATABASE <database>_restored; como administrador y vuelve a empezar este paso.

2. 2

   Detén todos los 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

   Cambia a la base de datos restaurada

   Conéctate a la base de datos postgres como administrador y ejecuta:

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

   

   Si la primera instrucción indica que otras sesiones están usando la base de datos, cierra esas sesiones y ejecuta ambas instrucciones de nuevo. Un pooler de conexiones puede mantener esas sesiones.

4. 4

   Implementa la versión anterior

   Sigue el elemento de Kubernetes de Volver a implementar la versión anterior. El primer comando también restablece el número de servidores. Si falla pero kubectl -n cma-server get pods muestra que los servidores anteriores están listos, consulta Si falla la comprobación de la clave.

5. 5

   Elimina la base de datos que apartaste

   Esa base de datos todavía contiene lo que los clientes escribieron después de la copia de seguridad. Cuando la versión anterior funcione, elimínala con DROP DATABASE <database>_upgraded;.

Si falla la comprobación de la clave

En el paso “Implementa la versión anterior”, el primer comando helm upgrade espera hasta que los servidores anteriores estén listos. Luego comprueba la clave con la que se conectan los sandboxes. Si el comando falla pero kubectl -n cma-server get pods muestra que los servidores anteriores están listos, falló esa comprobación.

Tus datos están restaurados y los servidores funcionan, pero los sandboxes todavía no pueden conectarse a ellos. Los sandboxes se conectan con una clave del Secret cma-environment en su propio namespace, cma. Esa clave es más reciente que tu copia de seguridad, por lo que la base de datos restaurada no la reconoce.

Para confirmar la causa, ejecuta el primer comando de nuevo. Mientras espera, abre una segunda terminal y establece $server también allí. Luego ejecuta kubectl -n cma-server logs job/$server-environment-default, con el nombre de tu entorno en lugar de default. Busca una línea que contenga Secret cma/cma-environment records key. Si el registro muestra otro error, corrige lo que indica.

Si el registro muestra esa línea, elimina el Secret con kubectl -n cma delete secret cma-environment y ejecuta el primer comando de nuevo. Este vuelve a crear el Secret, con una clave nueva. Luego ejecuta el segundo comando.

Restaurar la copia de seguridad en Docker Compose

1. 1

   Inicia solo la base de datos

   Ejecuta docker compose down en el directorio de Compose de la nueva versión. Luego ejecuta docker compose up -d --wait postgres en el directorio de Compose de la versión anterior. Permanece en ese directorio para los siguientes pasos.

2. 2

   Restaura la copia de seguridad en una base de datos nueva

   Desde el directorio de Compose de la versión anterior, ejecuta esto con las rutas de tu clave y de tu archivo de copia de seguridad:

   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'

   

   Funcionó si imprime DROP DATABASE y CREATE DATABASE, y ningún error.

   Deja $POSTGRES_USER y $POSTGRES_DB tal como están, aquí y en los siguientes pasos. El texto entre comillas simples se ejecuta dentro del contenedor postgres, que guarda en esas variables los nombres de su rol y de su base de datos.

   Si imprime un error, tu base de datos no ha cambiado, así que puedes ejecutar el comando completo de nuevo. Si no se puede restaurar la copia de seguridad, ejecuta docker compose up --build -d en el directorio de Compose de la nueva versión para volver a iniciar esa versión.

3. 3

   Cambia a la base de datos restaurada

   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

   Inicia la versión anterior

   Ejecuta docker compose up --build -d.

5. 5

   Elimina la base de datos que apartaste

   Esa base de datos todavía contiene lo que los clientes escribieron después de la copia de seguridad. Cuando la versión anterior funcione, elimínala:

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

   

Después de una restauración

Una restauración devuelve las claves de entorno al momento de la copia de seguridad:

• Una clave que revocaste después de la copia de seguridad: Vuelve a funcionar. Revócala de nuevo.
• Una clave que creaste después de la copia de seguridad: Ya no existe. Crea una clave nueva para los workers que la usaban.

Reemplazar una clave de entorno para tus propios workers contiene los comandos, que también funcionan en Docker Compose. Los sandboxes que inicia el stack de Docker Compose no requieren ninguna acción, porque el stack reemplaza su clave cuando se inicia.

Para listar las claves de un entorno, incluidas las revocadas, ejecuta list-keys de la siguiente manera:

• Usa la terminal que configuraste en Llamar a la API en un servidor autoalojado. No uses la terminal que ejecuta docker compose.
• En Kubernetes, primero ejecuta kubectl -n cma-server port-forward svc/$server 8400:8400 en otra terminal, con $server establecida también allí.
• Ejecuta el comando desde la raíz del archivo de la versión, una vez por cada entorno, con el ID de ese entorno.

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

Probar una copia de seguridad

Para comprobar que un volcado se restaura, ejecuta solo el paso “Restaura la copia de seguridad en una base de datos nueva”. Está en Restaurar la copia de seguridad en Kubernetes y en Restaurar la copia de seguridad en Docker Compose. Ese paso no cambia la base de datos en uso. Luego elimina la base de datos nueva. En Docker Compose, su nombre es el nombre de tu base de datos con _restored al final.

Ajustes y rutas que comprobar

Lee esta sección antes de ejecutar un comando de actualización.

Comprueba la sección web_tools de tu archivo de configuración. Si el archivo no tiene esa sección, o la sección no establece ninguna clave, las herramientas web_search y web_fetch quedan desactivadas después de la actualización. Un agente que usa el conjunto de herramientas predeterminado se ejecuta entonces sin ellas, sin ningún error. Un agente cuyo conjunto de herramientas activa cualquiera de las dos herramientas no puede iniciar una sesión. Para conservar las herramientas, consulta Las herramientas web necesitan una configuración del servidor.

En Kubernetes, comprueba que cada archivo de valores de sandbox, como cma-values.yaml, establezca egress.mode. Para mantener el acceso de tus sandboxes a internet pública, agrega mode: publicInternet debajo de egress. Si un archivo no establece ningún modo, el chart aplica su modo predeterminado, closed. El comando helm upgrade del chart de sandboxes se detiene entonces con un error como egress.mode is closed and egress.closed.hosts is empty y no cambia nada.

Comprueba sandbox.idleTimeout en los mismos archivos. Si un archivo no lo establece, el pod de una sesión desaparece unos 5 minutos después de que termina el turno del agente. Los procesos que el agente dejó en ejecución se detienen con el pod. De forma predeterminada, los archivos de /workspace se conservan. Para mantener el pod durante 30 minutos, agrega idleTimeout: 30m debajo de sandbox.

Busca inference.attribution en el archivo de configuración, y CMA_INFERENCE__ATTRIBUTION en el entorno del servidor. Elimina la línea si encuentras alguna. La versión a la que actualizas no tiene ese ajuste, y su servidor no se inicia si cualquiera de los dos está establecido.

Cuando la Claude API es tu proveedor de inferencia, cada llamada al modelo lleva, después de la actualización, los IDs de su sesión y del agente y el entorno de esa sesión. Consulta Qué envía el servidor a su proveedor de inferencia.

Kubernetes: los nombres de tus objetos

cma-server-values.yaml tiene que indicar qué nombres tiene tu instalación, en su ajuste earlierNames. Para encontrar el nombre del Deployment del servidor, ejecuta kubectl -n cma-server get deployment -l anthropic.com/role=server.

Si el archivo no tiene la línea, agrégala antes de actualizar y mantenla ahí en todas las actualizaciones posteriores. Sin ella, el comando helm upgrade del chart del servidor se detiene con un error que menciona earlierNames y no cambia nada.

Con earlierNames: true, los objetos del chart conservan sus nombres cma-onprem, y los servidores siguen encontrando los Secrets que creaste con esos nombres. Estas páginas usan los nombres de la columna central. Con earlierNames: true, usa en su lugar los nombres de la última columna:

Sin importar lo que indique earlierNames, el namespace se llama cma-server y la imagen del servidor se llama cma-server-image.

Cada archivo de valores de sandbox que establece egress.mode: gateway tiene que nombrar los dos Services del servidor, debajo de egress.gateway. Si un archivo no lo hace, agrega ambas líneas. Este ejemplo tiene los nombres para una instalación con earlierNames: true:

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

Docker Compose: la estructura del archivo de la versión y las rutas

Si la versión desde la que actualizas no tiene un directorio compose, su docker-compose.yml está en la raíz del archivo de la versión, junto a bin. En el nuevo archivo de la versión, ese archivo está un nivel más abajo, en compose.

En el paso “Repite tus otros cambios”, haz también estos cambios:

• Un archivo de Compose propio: Si el archivo de la versión anterior no tenía un directorio compose, tu archivo también pasa a estar un nivel más abajo. Una ruta como ./bin en él pasa a ser ../bin. Si el archivo nombra el servicio cma-onprem, cambia ese nombre a cma-server.
• Rutas bajo /etc/cma-onprem/ o /run/cma-onprem/: Cambia cada una para que comience con /etc/cma-server/ o /run/cma-server/. Busca en los .env y compose.config.yaml de la nueva versión, en un archivo de Compose propio y en cada línea volumes: que agregaste. En una línea volumes:, cambia solo la parte que va después de los primeros dos puntos, que es la ruta dentro del contenedor.