AGS CLI for Extend

Last updated on October 29, 2026

注釈：本資料はAI技術を用いて翻訳されています。

概要

Extend の現行作業には AGS CLI を使います。Extend Helper CLI は非推奨です。そのページはサポート終了日を含む履歴リファレンスとして残しています。

インストールとサインインの手順は Install and sign in にあります。旧 CLI からのコマンド対応表は Migrate from extend-helper-cli にあります。

前提条件

1. Docker（Docker Desktop 4.30+ / Docker Engine v23.0+）

   • Linux の場合:

     1. Ubuntu リポジトリからインストールするには、sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2 を実行します。

     2. ユーザーを docker グループに追加します: sudo usermod -aG docker $USER。

     3. 変更を反映するため、ログアウトしてから再度ログインします。

   • Windows/macOS の場合:

     Docker Desktop のインストールについては、Docker のドキュメント（Windows または macOS）に従ってください。

     docker version
     
     ...
     Server: Docker Desktop
        Engine:
        Version:          24.0.5

2. AGS 環境へのアクセス。Base URL を控えておきます。

   • AGS Public Cloud の例: https://spaceshooter.prod.gamingservices.accelbyte.io

   • AGS Private Cloud の例: https://dev.customer.accelbyte.io

3. 次の権限を持つ機密 IAM クライアントを作成します。クライアントの作成方法は Manage access control for applications を参照してください。Client ID と Client Secret を控えておきます。

   • AGS Private Cloud の場合、次の権限を追加します:

     1. ADMIN:NAMESPACE:{namespace}:EXTEND:APP [CREATE, READ, UPDATE, DELETE]
     2. ADMIN:NAMESPACE:{namespace}:EXTEND:DEPLOYMENT [CREATE]
     3. ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
     4. ADMIN:NAMESPACE:{namespace}:EXTEND:SECRET [CREATE, READ, UPDATE]
     5. ADMIN:NAMESPACE:{namespace}:EXTEND:VARIABLE [CREATE, READ, UPDATE]
     6. ADMIN:NAMESPACE:{namespace}:EXTEND:IMAGE [READ]

   • AGS Public Cloud の場合、次の権限グループにチェックを入れます:

     1. Extend > App Management: Read, Create, Update, Delete
     2. Extend > Configuration Secret Management: Read, Create, Update
     3. Extend > Configuration Variable Management: Read, Create, Update
     4. Extend > Deployment Management: Create
     5. Extend > Extend app image repository access: Read
   警告

   AGS Public Cloud ユーザー向け: 上記の権限のみを持つ、AGS CLI 専用の OAuth クライアントを作成してください。権限が多すぎる OAuth クライアントを使うと、サーバーが "Request Header or Cookie Too Large" エラーで CLI の HTTP リクエストを拒否することがあります。

4. AGS CLI をインストールします。Install and sign in に従ってください。

セットアップ

AGS CLI は .env ファイルを読みません。環境変数で資格情報を設定するか、ags auth login に渡します。

ターミナルから次の値をエクスポートします（プレースホルダーを実際の資格情報に置き換えてください）:

export AGS_BASE_URL=<your_base_url>
export AGS_CLIENT_ID=<your_client_id>
export AGS_CLIENT_SECRET=<your_client_secret>

任意:

• AGS_ACCESS_TOKEN — クライアントシークレットの代わりに既存のベアラートークンを使う場合
• AGS_NAMESPACE — --namespace を省略したときのデフォルト名前空間

これらは Extend Helper CLI が使う AB_* 変数ではありません。

セッションごとに一度サインインします:

ags auth login

スクリプトや CI ジョブでは、機密 IAM クライアントでサインインします:

ags auth login --grant client-credentials --no-input

--namespace（-n）はグローバルフラグです。--yes（-y）は確認プロンプトをスキップします。Extend Helper CLI の --confirm は受け付けられません。

使い方

Extend サブコマンドの一覧を表示するには:

ags extend --help

Extend アプリの作成

create-app は JSON 本体を使います。シナリオは --scenario フラグではなく --json に入れます。

ags extend create-app --namespace <my-game-namespace> --app <my-extend-app> --json '{"scenario":"service-extension"}' --yes

利用可能な scenario の値:

• function-override
• service-extension
• event-handler

応答例

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appName": "<my-extend-app>",
  "appRepoArn": "",
  "appRepoUrl": "",
  "basePath": "xxx-xxxx-xxxx",
  "CPU": {
    "cpuLimit": 1550,
    "requestCPU": 1000
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "deletedAt": "",
  "deploymentCreatedAt": "",
  "deploymentId": "",
  "deploymentImageTag": "",
  "memory": {
    "memoryLimit": 3300,
    "requestMemory": 350
  },
  "message": "",
  "replica": {
    "maxReplica": 10,
    "minReplica": 1,
    "replicaLimit": 60
  },
  "scenario": "service-extension",
  "servicePublicURL": "https://xxxx.accelbyte.io/xxx-xxxx-xxxx",
  "serviceURL": "",
  "updatedAt": "2024-01-31T00:00:00.000Z"
}

イメージのアップロードまたはデプロイの準備が整うまで待つには、--wait と --wait-interval <seconds>（デフォルト: 10）、--wait-limit <seconds>（デフォルト: 600）を使います。

ags extend create-app --namespace <my-game-namespace> --app <my-extend-app> --json '{"scenario":"service-extension"}' --yes --wait

Extend アプリ情報の取得

1 つの Extend アプリの詳細を取得するには get-app-info を使います:

ags extend get-app-info --namespace <my-game-namespace> --app <my-extend-app>

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appName": "<my-extend-app>",
  "appRepoArn": "arn:aws:ecr:xxxxxxxxx:xxxxxxxxxxxx:xxxx/xxxx/xxxx/xxxx/xxxx/xxx-xxxx-xxxx/xxxx",
  "appRepoUrl": "xxxx.xxxx.xxxx.xxxxxxxxx.xxxx.xxxx/xxxx/xxxx/xxxx/xxxx/xxx-xxxx-xxxx/xxxx",
  "appStatus": "app-undeployed",
  "app_release_status": "U",
  "basePath": "xxx-xxxx-xxxx",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "scenario": "service-extension",
  "updatedAt": "2024-01-31T00:00:00.000Z"
}

get-app-info に --path フラグはありません。--format json を使い、必要なフィールドを読んでください:

ags extend get-app-info --namespace <my-game-namespace> --app <my-extend-app> --format json | jq -r .appName

ags extend get-app-info --namespace <my-game-namespace> --app <my-extend-app> --format json | jq -r .appRepoUrl

Extend アプリコンテナイメージをプッシュするための認証情報の取得

1 つの名前空間とアプリ向けに Docker を Extend アプリコンテナレジストリへサインインさせるには、docker-login を使います:

ags extend docker-login --namespace <my-game-namespace> --app <my-extend-app>

応答例

Login Succeeded

警告

認証情報はそのゲーム名前空間と Extend アプリにスコープされます。別の名前空間またはアプリでは、再度 docker-login を実行してください。

docker-login が失敗する場合は、Docker ログインが失敗する を参照してください。

Extend アプリコンテナイメージのプッシュ

image-upload はコンテナイメージをビルドし、タグ付けして、Extend アプリコンテナレジストリへプッシュします。

ags extend image-upload --namespace <my-game-namespace> --app <my-extend-app> \
    --image-tag v1.0.0 \
    --work-dir <path-to-directory-containing-service-dockerfile>

--app と --image-tag は必須です。任意フラグには --dockerfile、--platform、--work-dir、--retry-limit、--retry-interval、--retry-rate があります。

ビルド前にレジストリへ認証するには --login を渡します。別途 docker-login を実行する必要はありません:

ags extend image-upload --namespace <my-game-namespace> --app <my-extend-app> \
    --image-tag v1.0.0 \
    --work-dir <path-to-directory-containing-service-dockerfile> \
    --login

アップロードが失敗した場合は、--retry-limit（任意で --retry-interval と --retry-rate）で再試行します:

ags extend image-upload --namespace <my-game-namespace> --app <my-extend-app> \
    --image-tag v1.0.0 \
    --work-dir <path-to-directory-containing-service-dockerfile> \
    --retry-limit 3

Extend アプリの環境変数とシークレットの作成・更新

環境変数を作成または更新するには update-var を使います:

ags extend update-var --namespace <my-game-namespace> --app <my-extend-app> --key REQUEST_TIMEOUT --value 100

シークレットを作成または更新するには update-secret を使います:

ags extend update-secret --namespace <my-game-namespace> --app <my-extend-app> --key API_KEY --value <api-key>

--key がまだ存在しないときに変数またはシークレットを作成するには、--force を渡します:

ags extend update-var --namespace <my-game-namespace> --app <my-extend-app> --key REQUEST_TIMEOUT --value 100 --force

ags extend update-secret --namespace <my-game-namespace> --app <my-extend-app> --key API_KEY --value <api-key> --force

シェル履歴に値を残さないため、--value より --value-stdin を推奨します。

Extend アプリのコンテナイメージを一覧する

list-images で、1 つの Extend アプリのコンテナイメージを一覧します。IAM クライアントには ADMIN:NAMESPACE:{namespace}:EXTEND:IMAGE [READ] が必要です。

ags extend list-images --namespace <my-game-namespace> --app <my-extend-app>

--cached の既定値は true です。キャッシュを使わない場合は --cached false を渡します。

Extend アプリのデプロイ

deploy-app は JSON 本体を使います。イメージタグはこのコマンドの --image-tag フラグではなく --json に入れます。

ags extend deploy-app --namespace <my-game-namespace> --app <my-extend-app> --json '{"imageTag":"v1.0.0"}'

応答例

{
  "deploymentId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

デプロイ完了まで待つには --wait（任意で --wait-interval / --wait-limit）を追加します:

ags extend deploy-app --namespace <my-game-namespace> --app <my-extend-app> --json '{"imageTag":"v1.0.0"}' --wait

Extend アプリの開始と停止

ags extend start-app --namespace <my-game-namespace> --app <my-extend-app>

ags extend stop-app --namespace <my-game-namespace> --app <my-extend-app>

--wait と --wait-interval <seconds>（デフォルト: 10）、--wait-limit <seconds>（デフォルト: 600）を使えます:

ags extend start-app --namespace <my-game-namespace> --app <my-extend-app> --wait

ags extend stop-app --namespace <my-game-namespace> --app <my-extend-app> --wait

Extend アプリの削除

ags extend delete-app --namespace <my-game-namespace> --app <my-extend-app> --yes

アプリの現在のステータスに関係なく削除するには、--forced true を渡します（デフォルト: false）。

ags extend delete-app --namespace <my-game-namespace> --app <my-extend-app> --yes --forced true

削除完了まで待つには、--wait と --wait-interval、--wait-limit を使います:

ags extend delete-app --namespace <my-game-namespace> --app <my-extend-app> --yes --wait

Extend アプリログのストリーム

logs stream には AGS CLI 0.5.2 以降が必要です。--follow なしでは最近の行を表示して終了します。--follow ありでは Ctrl-C まで新しい行を表示し続けます。

ags extend logs stream --namespace <my-game-namespace> --app <my-extend-app>

ags extend logs stream --namespace <my-game-namespace> --app <my-extend-app> --follow

便利なフラグ:

• --tail-lines <n>（エイリアス --tail）— ポッドあたりの最近の行数（デフォルト: 100）
• --pods <count> — ストリームするポッド数（デフォルト: 1）
• --since-seconds <seconds> — この秒数より新しい行のみ
• --previous — 直前のコンテナインスタンス（再起動後のクラッシュテキスト）

ags extend logs stream --namespace <my-game-namespace> --app <my-extend-app> --tail-lines 200 --previous

Admin Portal のログカードと履歴ダウンロードについては、View Extend app logs を参照してください。

データベーストンネルを開く

database-tunnel には AGS CLI 0.5.3 以降が必要です。Ctrl-C まで、ローカル TCP ポートを Extend データベースリソースにバインドします。

ags extend database-tunnel --namespace <my-game-namespace> --resource-name <resource-name> --local-port <port>

リソース名と接続例については、Extend データベースガイドを参照してください:

• NoSQL
• SQL
• Key-value store

Extend アプリのリモートデバッグ

実行中のアプリでデバッグセッションを有効化、接続、または無効化するには remote-debug を使います。詳細な手順は Local debugging — with remote live traffic にあります。

ags extend remote-debug enable --namespace <my-game-namespace> --app <my-extend-app> --yes

ags extend remote-debug connect --namespace <my-game-namespace> --app <my-extend-app>

ags extend remote-debug disable --namespace <my-game-namespace> --app <my-extend-app> --yes

実行中のアプリを再起動する enable / disable の確認プロンプトをスキップするには、--yes を渡します。

スターターテンプレートのクローン

ags extend clone-template --template "<full-template-name>" --destination <dir>

clone-template に --scenario フラグはありません。--template には react のような短い名前ではなく、Extend App UI :: react :: JavaScript のような完全なテンプレート名を指定します。名前が一致しない場合、コマンドは利用可能なテンプレート名をすべて表示します。--template なしでは、シナリオ、テンプレート、言語の選択を求められます。

Extend App UI

ags extend app-ui create --namespace <my-game-namespace> --json '{"name":"<app-ui-name>"}'
ags extend app-ui setup-env --namespace <my-game-namespace> --name <app-ui-name>
ags extend app-ui upload --namespace <my-game-namespace> --name <app-ui-name>

app-ui create は name を JSON 本体で送ります。setup-env と upload は --name を取ります。

セキュリティアセスメントをリクエストする

security-assessment のコマンドは セキュリティアセスメントをリクエストする にあります。

トラブルシューティング

Docker ログインが失敗する

ags extend docker-login または ags extend image-upload --login が次のエラーを返します。

Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

Extend レジストリのトークンは、多くの Docker 資格情報ヘルパーが保存できるサイズを超えています。詳細は Docker の 資格情報ヘルパーの issue を参照してください。

ネイティブ Windows では資格情報ヘルパーを使わず、トークンを出力して自分で docker login に渡します。コマンドの全体は Windows での Docker ログイン を参照してください。

Linux または WSL2 では、Docker の設定から資格情報ヘルパーを削除します。

Linux

1. $HOME/.docker/config.json から "credsStore": "desktop.exe" を削除します。
2. ags extend docker-login を再度実行します。

Windows (WSL2)

1. Windows のファイルシステムで次を行います。

   • %USERPROFILE%\.docker\config.json から "credsStore": "desktop.exe" を削除します。
   • C:\Program Files\Docker\Docker\resources\bin にある次のファイルの名前を変更します。
     • docker-credential-desktop.exe を docker-credential-desktop.exe.old に変更
     • docker-credential-wincred.exe を docker-credential-wincred.exe.old に変更

2. WSL2 のファイルシステムで、$HOME/.docker/config.json から "credsStore": "desktop.exe" を削除します。

3. ags extend docker-login を再度実行します。

注記

この回避策は再度適用が必要になる場合があります。Docker Desktop は再起動時に config.json の "credsStore": "desktop" を復元することがあります。詳細は Docker の config.json の issue を参照してください。