asmcli リファレンス
概要
asmcli
は、Cloud Service Mesh のインストールまたはアップグレードに使用できる Google 提供のツールです。asmcli
を使用すると、プロジェクトとクラスタは次のように構成されます。
- Google Cloud プロジェクトに対して必要な Identity and Access Management(IAM)権限を付与します。
- Google Cloud プロジェクトで必要な Google API を有効にします。
- メッシュを識別するラベルをクラスタに設定します。
- サービス アカウントを作成し、サイドカー プロキシなどのデータプレーン コンポーネントがプロジェクトのデータとリソースに安全にアクセスできるようにします。
- クラスタを登録します(まだ登録されていない場合)。
asmcli
でプロジェクトとクラスタを構成する場合は、--enable_all
フラグのみを指定します。asmcli
のオプションとフラグの詳細については、asmcli
リファレンスをご覧ください。
asmcli
が、プロジェクトとクラスタの情報を使用して YAML ファイルを構成します。これらの構成ファイルは、Cloud Service Mesh コントロール プレーンのインストールで必要になります。
Cloud Service Mesh と Istio を初めて使用する場合は、対応プラットフォームに進んでください。次のセクションでは、既存の Cloud Service Mesh を 1.23にアップグレードする方法について説明します。
asmcli
への移行
asmcli
は、istioctl install
と install_asm
の代わりに使用されます。Cloud Service Mesh 1.11 では以前のツールを引き続き使用できますが、それらのツールは非推奨となり、Cloud Service Mesh 1.12 以降ではサポートされなくなります。asmcli
を使用するようにツールとスクリプトを更新してください。
すべてのクラスタは、フリートに登録されている必要があります。詳しくは、フリートの要件をご覧ください。
install_asm
からの移行
install_asm
と asmcli
はよく似ていているように見えるかもしれませんが、次の点が大きく異なります。
新規インストールとアップグレードには
asmcli install
を使用します。これには、install_asm
のような--mode
オプションはありません。asmcli install
を実行すると、クラスタに既存のコントロール プレーンが存在するかどうかが確認されます。既存のコントロール プレーンがない場合、asmcli
は Cloud Service Mesh をインストールします。クラスタに既存のコントロール プレーン(Cloud Service Mesh コントロール プレーンまたはオープンソースの Istio コントロール プレーン)がある場合:既存のコントロール プレーンのリビジョン ラベルが、新しいコントロール プレーンのリビジョン ラベルと一致しない場合、
asmcli
はカナリア アップグレードを実行します。コントロール プレーンのリビジョン ラベルが一致している場合、
asmcli
はインプレース アップグレードを実行します。
asmcli
のオプションとフラグのほとんどはinstall_asm
と同じように機能します。
istioctl install
からの移行
istioctl install
に慣れていて、-f
コマンドライン引数で IstioOperator
YAML ファイルを渡してコントロール プレーンを構成している場合は、--custom_overlay
オプションを使用してファイルを asmcli
に渡すことができます。Cloud Service Mesh のドキュメントでは、これらのファイルをオーバーレイ ファイルと呼んでいます。
対応プラットフォーム
対応プラットフォームでの Cloud Service Mesh のインストールは、asmcli
によって構成またはアップグレードできます。
ただし、すべての機能が Google Cloud 以外のプラットフォームで利用できるわけではありません。詳細については、クラスタ内コントロール プレーンでサポートされている機能をご覧ください。
asmcli
リファレンス
このセクションでは、asmcli
で使用可能な引数について説明します。
オプション
クラスタの特定。クラスタを特定するには、次のオプションがあります。
GKE のみ
-p|--project_id CLUSTER_PROJECT_ID
- クラスタが作成されたプロジェクト ID。
-n|--cluster_name CLUSTER_NAME
- クラスタの名前。
-l|--cluster_location CLUSTER_LOCATION
- クラスタが作成されたゾーン(シングルゾーン クラスタの場合)またはリージョン(リージョン クラスタの場合)のいずれか。
すべてのプラットフォーム
--kubeconfig KUBECONFIG_FILE
kubeconfig ファイルのフルパス。環境変数 $PWD
はここでは機能しません。
--ctx|--context KUBE_CONTEXT
使用する kubeconfig コンテキスト。指定しない場合、asmcli
でデフォルトのコンテキストが使用されます。
-c|--ca {mesh_ca|gcp_cas|citadel}
相互 TLS 証明書の管理に使用する認証局(CA)。Cloud Service Mesh 認証局(Cloud Service Mesh 認証局)を使用するには
mesh_ca
を指定し、Certificate Authority Service を使用するにはgcp_cas
を指定し、Istio CA を使用するにはcitadel
を指定します。マネージド Cloud Service Mesh は Istio CA をサポートしていません。詳しくは以下をご覧ください。--channel CLOUD_SERVICE_MESH_CHANNEL
--channel
を使用して特定の Cloud Service Mesh リリース チャンネルを指定すると、そのリリース チャンネルに関連付けられているコントロール プレーン リビジョンがプロビジョニングされます。たとえば--channel rapid
、--channel regular
、--channel stable
のように指定します。このフラグは、GKE Autopilot クラスタで特定の Cloud Service Mesh の機能を構成する場合に必要になります。
CSM リリースノートで説明されているように、マネージド Cloud Service Mesh では --channel
オプションがサポートされなくなりました。リリース チャンネルは、GKE クラスタのリリース チャンネルに基づいて決定されます。詳細については、Managed Cloud Service Mesh のリリース チャンネルをご覧ください。
--co|--custom_overlay OVERLAY_FILE
--custom_overly
を、IstioOperator
カスタム リソースを含む YAML ファイル(オーバーレイ ファイルと呼ばれます)の名前とともに使用して、クラスタ内コントロール プレーンを構成します。オーバーレイ ファイルを指定すると、デフォルトで有効になっていない機能を有効にすることができます。マネージド Cloud Service Mesh はIstioOperator
API をサポートしていないため、--custom_overlay
を使用してマネージド コントロール プレーンを構成することはできません。asmcli
はオーバーレイ ファイルを特定できる必要があるため、asmcli
と同じディレクトリに存在するか、相対パスを指定できる必要があります。複数のファイルを追加するには、--co|--custom_overlay
とファイル名を指定します。例:--co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml
--hub-registration-extra-flags HUB_REGISTRATION_EXTRA_FLAGS
- 接続された Amazon EKS クラスタを使用する場合、まだ登録されていない場合は
--hub-registration-extra-flags
を使用してクラスタをフリートに登録します。 -k|--key_file FILE_PATH
- サービス アカウントの鍵ファイル。サービス アカウントを使用していない場合は、このオプションを省略します。
--network_id NETWORK_ID
--network_id
を使用して、istio-system
Namespace に適用されるtopology.istio.io/network
ラベルを設定します。GKE の場合、--network_id
はデフォルトでクラスタのネットワーク名になります。その他の環境では、default
が使用されます。-o|--option OVERLAY_FILE
asmcli
がanthos-service-mesh
リポジトリからダウンロードし、オプション機能を有効にするオーバーレイ ファイルの名前(.yaml
拡張子なし)。--option
を使用するには、インターネット接続が必要です。--option
オプションと--custom_overlay
オプションは似ていますが、動作がわずかに異なります。オーバーレイ ファイルの設定を変更する必要がある場合は、
--custom_overlay
を使用します。--option
を使用して、オーバーレイ ファイルを変更する必要がない機能を有効にします。たとえば、サービスの監査ポリシーを構成します。
複数のファイルを追加するには、
-o|--option
とファイル名を指定します。例:-o option_file1 -o option_file2 -o option_file3
-D|--output_dir DIR_PATH
指定されていない場合、
asmcli
は、Cloud Service Mesh のインストールに必要なファイルや構成をダウンロードする一時ディレクトリを作成します。代わりにディレクトリへの相対パスを指定するには、--output-dir
フラグを指定します。完了すると、指定したディレクトリにはasm
サブディレクトリとistio-1.23.3-asm.1
サブディレクトリが含まれます。asm
ディレクトリには、インストールの構成が含まれます。istio-1.23.3-asm.1
ディレクトリには、istioctl
、サンプル、マニフェストが含まれるインストール ファイルの抽出コンテンツが含まれます。--output-dir
を指定して、ディレクトリに必要なファイルがすでに含まれている場合、asmcli
は再度ダウンロードを行わず、これらのファイルを使用します。--platform PLATFORM {gcp|multicloud}
Kubernetes クラスタのプラットフォームまたはプロバイダ。デフォルトは
gcp
です(GKE クラスタの場合)。他のすべてのプラットフォームでは、multicloud
を使用します。-r|--revision_name REVISION NAME
リビジョン ラベルは、コントロール プレーンで設定されている Key-Value ペアです。リビジョン ラベルキーは常に
istio.io/rev
になります。デフォルトでは、asmcli
は Cloud Service Mesh のバージョンに基づいてリビジョン ラベルの値を設定します(例:asm-1233-2
)。デフォルト値をオーバーライドして独自の値を指定する場合は、このオプションを指定します。REVISION NAME
引数は、DNS-1035 ラベルである必要があります。名前は次の条件を満たす必要があります。- 最大文字数は 63 文字とする
- 小文字の英数字またはハイフン(-)のみを使用する
- 先頭が英字である
- 末尾が英数字である
検証に使用される正規表現は '[a-z]([-a-z0-9]*[a-z0-9])?'
です。
-s|--service_account ACCOUNT
- Cloud Service Mesh のインストールに使用されるサービス アカウントの名前。指定しない場合は、現在の
gcloud
構成にある有効なユーザー アカウントが使用されます。有効なユーザー アカウントを変更する必要がある場合は、gcloud auth login を実行します。
Istio CA カスタム証明書のオプション
--ca citadel
を指定してカスタム CA を使用する場合は、次のオプションを指定します。
--ca_cert FILE_PATH
: 中間証明書--ca_key FILE_PATH
: 中間証明書の鍵--root_cert FILE_PATH
: ルート証明書--cert_chain FILE_PATH
: 証明書チェーン
詳細については、既存の CA 証明書を組み込むをご覧ください。
イネーブルメント フラグ
--enable
で始まるフラグによって、asmcli
は必要な Google API を有効にし、必要な Identity and Access Management(IAM)権限を設定して、クラスタを更新します。必要に応じて、asmcli
を実行する前に、プロジェクトとクラスタを自分で更新できます。すべてのイネーブルメント フラグに asmcli validate
と互換性があるわけではありません。asmcli validate
を有効にするときにイネーブルメント フラグを指定した場合、コマンドはエラーで終了します。
-e|--enable_all
- 以下で説明する個々の有効化の操作をすべて
asmcli
で実行できるようにします。 --enable_cluster_roles
asmcli
で、asmcli
を実行している Google Cloud ユーザーまたはサービス アカウントをクラスタのcluster-admin
ロールにバインドできるようにします。asmcli
は、gcloud config get core/account
コマンドからユーザー アカウントを特定します。ユーザー アカウントを使用してasmcli
をローカルで実行する場合は、必ずgcloud auth login
コマンドを呼び出してからasmcli
を実行してください。ユーザー アカウントを変更する必要がある場合は、gcloud config set core/account GCP_EMAIL_ADDRESS
コマンドを実行します。ここで、GCP_EMAIL_ADDRESS は、Google Cloud へのログインに使用するアカウントです。--enable_cluster_labels
asmcli
で、必要なクラスタラベルを設定できるようにします。--enable_gcp_components
asmcli
で、次の必要な Google Cloud マネージド サービスとコンポーネントを有効にできるようにします。Workload Identity。GKE アプリケーションが Google Cloud サービスに安全にアクセスできるようになります。
--enable_gcp_apis
asmcli
で、すべての必要な Google API を有効にできるようにします。--enable_gcp_iam_roles
asmcli
で、必要な IAM 権限を設定できるようにします。--enable_meshconfig_init
スクリプトがユーザーに代わって meshconfig エンドポイントを初期化できるようにします。
--enable_gcp_components
と--managed
によって暗黙的に指定されます。--enable_namespace_creation
asmcli
がルートのistio-system
名前空間を作成できるようにします。--enable_registration
asmcli
でクラスタが所属するプロジェクトにそのクラスタを登録できるようにします。このフラグを指定しない場合は、クラスタの登録の手順に沿ってクラスタを手動で登録してください。他のイネーブルメント フラグとは異なり、--enable_registration
は、クラスタ登録を必要とするオプション(--option hub-meshca
など)を指定した場合に--enable_all
にのみ含まれます。こうしたオプションを指定しない場合、このフラグは個別に指定する必要があります。
その他のフラグ
--dry_run
- コマンドを出力しますが、実行しません。
--fleet_id
- フリートのホスト プロジェクト ID を使用して、フリートにクラスタを登録します。Google Cloud 以外のクラスタでは、このフラグは必須です。Google Cloud クラスタの場合、指定がないとデフォルトでクラスタのプロジェクト ID が設定されます。インストール前に
--fleet_id
とともにasmcli install
を実行することも、--enable-registration
フラグと--fleet-id
フラグを渡してインストールの一環として実行することもできます。この設定は、構成後に変更することはできません。 --managed
- 非推奨クラスタ内にインストールするのではなく、リモートのマネージド コントロール プレーンをプロビジョニングします。
--offline
- 出力ディレクトリに事前にダウンロードされたパッケージを使用して、オフライン インストールを実行します。ディレクトリが指定されていない場合、または必要なファイルが含まれていない場合は、スクリプトがエラーで終了します。
--only_enable
- 指定した手順で現在のユーザーまたはクラスタを設定しますが、何もインストールされません。
--only_validate
- 検証を実行しますが、プロジェクトやクラスタは更新しません。また、Cloud Service Mesh はインストールしません。このフラグはイネーブルメント フラグと互換性がありません。任意のイネーブルメント フラグとともに
--only_validate
を指定すると、asmcli
はエラーで終了します。 --print_config
- Cloud Service Mesh をインストールする代わりに、コンパイル済みのすべての YAML を標準出力(stdout)に出力します。通常は stdout に出力される場合でも、他のすべての出力が標準エラー(stderr)に書き込まれます。このフラグを指定すると、
asmcli
ですべての検証と設定がスキップされます。 --disable_canonical_service
- デフォルトでは、
asmcli
は Canonical Service コントローラをクラスタにデプロイします。asmcli
でコントローラをデプロイしない場合は、--disable_canonical_service
を指定します。詳細については、Canonical Service コントローラの有効化と無効化をご覧ください。 -h|--help
- オプション、フラグ、終了を説明するヘルプ メッセージを表示します。
--use_managed_cni
- マネージド CNI を使用します。このフラグが渡されない場合、
asmcli
は静的 CNI マニフェストを適用します。 --use_vpcsc
- 組織でプロジェクトに VPC Service Controls を適用している場合は、
--use_vpcsc
フラグを使用してマネージド Cloud Service Mesh を構成する必要があります。そうしないと、セキュリティ コントロールが失敗します。 -v|--verbose
asmcli
を実行すると、次に実行するコマンドが出力されます。--verbose
フラグを指定すると、asmcli
によって実行後にコマンドが出力されます。--version
asmcli
のバージョンを出力して終了します。最新のバージョンがない場合は、最新バージョンのasmcli_1.23
をダウンロードできます。