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 のオプションとフラグのほとんどは 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.2-asm.2 サブディレクトリが含まれます。asm ディレクトリには、インストールの構成が含まれます。istio-1.23.2-asm.2 ディレクトリには、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-1232-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 マネージド サービスとコンポーネントを有効にできるようにします。

--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 をダウンロードできます。