セルフホスト型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の名前をシェル変数から読み取ります。コマンドを実行する各ターミナルで、次の2行を実行してください。1行目は名前を調べ、2行目はその名前を出力します。

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

2行目がcma-serverと出力した場合は、先に進んでください。別の名前が出力された場合は、アップグレードする前にオブジェクトの名前を読んでください。何も出力されない場合は、kubectlが正しいクラスターを指していることを確認し、2行を再度実行してください。

1. 1

   新しいイメージをビルドしてプッシュする

   新しいアーカイブを展開します。イメージをビルドしてプッシュするのとおりに、その3つのイメージを新しいバージョンでビルドしてプッシュします。エグレスゲートウェイを実行している場合は、そのイメージもビルドしてプッシュします。

   独自のサンドボックスイメージをビルドしている場合は、それも新しいバージョンで再ビルドしてプッシュします。そのDockerfileを新しいアーカイブのkubernetes/sandbox/Dockerfileと比較し、独自のイメージに必要なものを参照してください。

2. 2

   valuesファイルで新しいバージョンを設定する

   valuesファイルでimage.tagを設定している場合は、新しいバージョンに変更してください。

3. 3

   アップグレードで必要な場合は、すべてのサーバーを停止する

   この手順は次の場合にのみ行ってください。

   • 実行しているサーバーが、新しいリリースよりマイナーリリース2つ以上遅れている。
   • 最初の数字（メジャーバージョン）が上がる。
   • 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

   データベースをバックアップする

   マイナーアップグレードまたはメジャーアップグレードの前、またはサーバーを停止した場合に、これを行ってください。旧リリースが変更後のスキーマで動作できない場合、このバックアップが元に戻す唯一の手段です。

   データベースサーバーと同じメジャーバージョンのPostgreSQLのpg_dumpを使用してください。<role>と<database>には、cma-server-values.yamlのdatabase.urlのuserとdbnameの値を使用してください。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

   サーバーをアップグレードしてからサンドボックスをアップグレードする

   インストール時のvaluesファイルを使用して、新しいアーカイブの最上位ディレクトリから次のコマンドを実行します。

   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

   

   複数の環境を実行している場合は、各サンドボックスリリースについて、そのリリースの名前、名前空間、valuesファイルを指定して2番目のコマンドを実行してください。

   サーバーを停止した場合、1つ目のコマンドはスキーマを移行し、サーバー数を元に戻し、新しいサーバーの準備が整った時点で戻ります。

サーバーが実行中の場合、Helmは古いサーバーを停止する前に新しいサーバーを起動するため、準備が整ったサーバーの数が減ることはありません。マイナーアップグレードでは、1つ目のコマンドは古いサーバーがサービスを提供している間にスキーマを変更し、その後、古いサーバーを置き換えます。置き換え中のサーバー上で開いているイベントストリームは正常に終了するため、ストリームを追跡しているクライアントは再接続する必要があります。

コマンドが失敗した場合は、アップグレードが失敗した場合を参照してください。

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/"

   

   2行目は、.envとcompose.config.yamlも展開されたcomposeディレクトリにコピーします。古いスタックは両方の行の実行中も動作し続けます。いずれかの行がエラーを出力した場合は、原因を修正して両方の行を再実行してください。

3. 3

   その他の変更を繰り返す

   引き継がれるのは.envとcompose.config.yamlのみです。その他の変更は、新しいリリースのComposeディレクトリで再度行ってください。

   • 追加したファイル: コピーします。
   • 編集した同梱ファイル: 新しいリリースのコピーで同じ編集を行います。古いファイルで上書きしないでください。リリースでのそのファイルへの変更が元に戻ってしまいます。
   • エージェントアイデンティティ: agent-identityディレクトリをcp -aでコピーし（rootが所有している場合はsudoを使用）、docker-compose.ymlのvolumes:ブロックを再度編集します。
   • 独自の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

   

   1行目は、新しいリリースの.envが配置されている場合にのみ古いスタックを停止します。docker compose downはデータベースを保持します。-vを追加しないでください。データベースが削除されます。新しいスタックはデータベースを引き継ぎ、そのmigrateコンテナがサーバーの起動前にスキーマを更新します。

コマンドが失敗した場合は、アップグレードが失敗した場合を参照してください。

アップグレードが失敗した場合

ロールバックする前に、ログで原因を確認してください。

• Kubernetes: マイグレーションJobが失敗した場合、helm upgradeはJobが再試行する間数分待機し、その後失敗します。その待機中に、2つ目のターミナルで、Kubernetesでアップグレードするのとおりに$serverを設定してkubectl -n cma-server logs job/$server-migrateを実行してください。Jobが再試行を停止すると、Kubernetesはログを削除します。ログを見逃した場合は、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コマンドは、Kubernetesでアップグレードするの$server変数を使用します。ロールバックする前に、アップグレードが失敗した場合を確認してください。その後、アップグレードの種類に応じてロールバックします。

• パッチアップグレードの後: 旧リリースを再度デプロイするの手順に従ってください。両方のリリースは同じスキーマを使用します。
• マイナーアップグレードまたはメジャーアップグレードの後: 新リリースのアーカイブのCHANGELOG.mdを開いてください。戻す先のリリースより後に出たすべてのリリースのセクションを読んでください。
  • 旧リリースがマイグレーション済みのデータベースでは起動できないとセクションに記載されている場合は、バックアップを復元してください。
  • それ以外の場合は、旧リリースを再度デプロイしてください。それがcannot downgradeで失敗した場合は、バックアップを復元してください。

旧リリースを再度デプロイする

• Kubernetes: 旧アーカイブの最上位ディレクトリに移動します。Kubernetesでアップグレードするの2つのhelm upgradeコマンドを、そのリリースで使用していたvaluesファイルで実行してください。たとえば、アップグレードのためにearlierNamesを追加した場合は、それを削除します。2番目のコマンドは、最初のコマンドが成功した場合にのみ実行してください。
• Docker Compose: 新リリースの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でバックアップを復元する

データベースサーバーには、データベースの2つ目のコピーを置く容量が必要です。<role>と<database>には、cma-server-values.yamlのdatabase.urlのuserとdbnameの値を使用してください。

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で旧リリースのサーバーが準備完了と表示される場合は、その確認が失敗しています。

データは復元され、サーバーは動作していますが、サンドボックスはまだサーバーに接続できません。サンドボックスは、自身の名前空間cmaにあるcma-environment Secretのキーで接続します。そのキーはバックアップより新しいため、復元したデータベースはそのキーを認識しません。

原因を確認するには、最初のコマンドを再度実行します。待機している間に、2つ目のターミナルを開き、そこでも$serverを設定します。次に、defaultを環境の名前に置き換えてkubectl -n cma-server logs job/$server-environment-defaultを実行します。Secret cma/cma-environment records keyを含む行を探してください。ログに別のエラーが表示される場合は、そこに示されている問題を修正してください。

ログにその行が表示される場合は、kubectl -n cma delete secret cma-environmentでSecretを削除し、最初のコマンドを再度実行します。これにより、新しいキーでSecretが再作成されます。その後、2番目のコマンドを実行します。

Docker Composeでバックアップを復元する

1. 1

   データベースのみを起動する

   新リリースのComposeディレクトリでdocker compose downを実行します。次に、旧リリースのComposeディレクトリでdocker compose up -d --wait postgresを実行します。以降の手順では、そのディレクトリにとどまってください。

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コンテナ内で実行され、コンテナはこれらの変数にロールとデータベースの名前を保持しています。

   エラーが出力された場合、データベースは変更されていないため、コマンド全体を再度実行できます。バックアップを復元できない場合は、新リリースのComposeディレクトリでdocker compose up --build -dを実行して、そのリリースを再び起動してください。

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では、まず別のターミナルで、そこでも$serverを設定したうえでkubectl -n cma-server port-forward svc/$server 8400:8400を実行してください。
• アーカイブの最上位ディレクトリから、環境ごとに1回、その環境の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セクションを確認してください。ファイルにこのセクションがない場合、またはセクションでキーが1つも設定されていない場合、アップグレード後はweb_searchツールとweb_fetchツールがオフになります。その場合、デフォルトのツールセットを使用するエージェントはエラーを出さずにこれらのツールなしで実行されます。ツールセットでいずれかのツールを有効にしているエージェントはセッションを開始できません。ツールを維持するには、Webツールにはサーバー設定が必要を参照してください。

Kubernetesでは、各サンドボックスのvaluesファイル（cma-values.yamlなど）でegress.modeが設定されていることを確認してください。サンドボックスからパブリックインターネットへのアクセスを維持するには、egressの下にmode: publicInternetを追加します。ファイルでモードが設定されていない場合、チャートはデフォルトのモードであるclosedを適用します。その場合、サンドボックスチャートのhelm upgradeコマンドはegress.mode is closed and egress.closed.hosts is emptyなどのエラーで停止し、何も変更しません。

同じファイルでsandbox.idleTimeoutを確認してください。ファイルで設定されていない場合、セッションのPodはエージェントのターンが終了してから約5分後に削除されます。エージェントが実行したままにしたプロセスは、Podとともに停止します。デフォルトでは、/workspace内のファイルは保持されます。Podを30分間保持するには、sandboxの下にidleTimeout: 30mを追加します。

設定ファイルにinference.attributionがないか、またサーバーの環境にCMA_INFERENCE__ATTRIBUTIONがないかを確認してください。見つかった場合はその行を削除します。アップグレード先のリリースにはこの設定がなく、どちらかが設定されているとサーバーは起動しません。

Claude APIが推論プロバイダーである場合、アップグレード後は、各モデル呼び出しにそのセッションのID、およびそのセッションのエージェントと環境の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を設定する各サンドボックスのvaluesファイルでは、egress.gatewayの下にサーバーの2つのServiceの名前を指定する必要があります。ファイルで指定されていない場合は、両方の行を追加してください。この例には、earlierNames: trueのインストールでの名前が含まれています。

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

Docker Compose：アーカイブのレイアウトとパス

アップグレード元のリリースにcomposeディレクトリがない場合、そのdocker-compose.ymlはアーカイブの最上位、binの隣にあります。新しいアーカイブでは、そのファイルは1階層深いcomposeにあります。

「その他の変更を繰り返す」の手順で、次の変更も行ってください。

• 独自のComposeファイル: 古いアーカイブにcomposeディレクトリがなかった場合、ファイルも1階層深くなります。ファイル内の./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:行では、最初のコロンより後の部分（コンテナ内のパス）のみを変更してください。