リファレンス

このページでは、スクリプトで使用可能な引数について説明し、スクリプトがプロジェクトと GKE クラスタに加える変更について詳しく説明します。

オプション

-p|--project_id CLUSTER_PROJECT_ID
クラスタが作成されたプロジェクト ID。
-n|--cluster_name CLUSTER_NAME
クラスタの名前。
-l|--cluster_location CLUSTER_LOCATION
クラスタが作成されたゾーン（シングルゾーン クラスタの場合）またはリージョン（リージョン クラスタの場合）のいずれか。
-m|--mode {install|migrate|upgrade}

--mode install は、Istio からの新規インストール、アップグレード、移行に使用できます。アップグレードや移行に --mode install を使用すると、クラスタ上のコントロール プレーンのバージョンに関係なく、install_asm によってアップグレードや移行が可能になります。migrate フラグと upgrade フラグを指定すると、以前のマイナー バージョンまたは以前のパッチ バージョンからのアップグレードまたは移行のみが許可されます。

アップグレードまたは移行に --mode install を使用する場合は、クラスタで現在有効になっているものと同じ認証局（CA）を指定してください。CA を変更すると、ダウンタイムが発生します。--upgrade フラグを使用すると、CA を変更できなくなります。これにより、意図しないダウンタイムを回避できます。

Istio から移行する場合は、CA を変更して、Anthos Service Mesh 認証局（Mesh CA）を有効にできます。Mesh CA への移行のダウンタイムをスケジューリングできない場合でも、Mesh CA への移行パスがありますが、追加の手順が必要です。詳細については、Mesh CA への移行をご覧ください。

-c|--ca {mesh_ca|citadel}

新しいインストールに、Mesh CA を使用したい場合は、スクリプトのデフォルトが Mesh CA のため、このオプションを含める必要はありません。アップグレードの場合、スクリプトにより CA の変更が許されないため、このオプションを含める必要はありません。移行の場合は、citadel か mesh_ca を指定します。移行のダウンタイムをスケジューリングできる場合は、mesh_ca を使用することをおすすめします。使用する CA についての詳細は、認証局の選択をご覧ください。Istio CA を使用するときに指定する必要がある他のオプションについては、Istio CA カスタム証明書のオプションをご覧ください。

--co|--custom_overlay YAML_FILE

IstioOperator カスタム リソース（CR）YAML ファイルの名前。デフォルトで有効になっていない機能を有効にします。スクリプトが YAML ファイルの場所を特定できる必要があるため、スクリプトと同じディレクトリにファイルを置くか、相対パスを指定します。複数のファイルを追加するには、--co|--custom_overlay とファイル名を指定します。例: --co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml

-o|--option OPTION_FILE

オプション機能を有効にする IstioOperator CR を含む anthos-service-mesh パッケージの YAML ファイル名。こうしたファイルのいずれかを含める場合は、最初に anthos-service-mesh パッケージをダウンロードする必要はありません。また、.yaml 拡張子は指定しないでください。いずれかのファイルを変更する必要がある場合は、anthos-service-mesh パッケージをダウンロードして変更を加え、--custom_overlay オプションを使用します。複数のファイルを追加するには、-o|--option とファイル名を指定します（例: -o option_file1 -o option_file2 -o option_file3）。

-D|--output_dir DIR_PATH

指定されていない場合、このスクリプトは、Anthos Service Mesh のインストールに必要なファイルや構成をダウンロードする一時ディレクトリを作成します。代わりにディレクトリへの相対パスを指定するには、--output-dir フラグを指定します。完了すると、指定したディレクトリには asm サブディレクトリと istio-1.11.8-asm.4 サブディレクトリが含まれます。asm ディレクトリには、インストールの構成が含まれます。istio-1.11.8-asm.4 ディレクトリには、istioctl、サンプル、マニフェストが含まれるインストール ファイルの抽出コンテンツが含まれます。--output-dir を指定して、ディレクトリに必要なファイルがすでに含まれている場合、スクリプトは再度ダウンロードを行わず、これらのファイルを使用します。

-r|--revision_name REVISION NAME>

リビジョン ラベルは、コントロール プレーンで設定されている Key-Value ペアです。リビジョン ラベルキーは常に istio.io/rev になります。デフォルトでは、スクリプトは Anthos Service Mesh のバージョンに基づいてリビジョン ラベルの値を設定します（例: asm-1118-4）。デフォルト値をオーバーライドして独自の値を指定する場合は、このオプションを指定します。REVISION NAME 引数は DNS-1035 のラベルにします。ラベルには小文字の英数字または - を使用し、ラベルの先頭は英字に、ラベルの最後は英数字にする必要があります（例: my-name'、abc-123）。検証に使用される正規表現は '[a-z]([-a-z0-9]*[a-z0-9])?') です。

-s|--service_account ACCOUNT

Anthos Service Mesh のインストールに使用されるサービス アカウントの名前。指定しない場合は、現在の gcloud 構成にある有効なユーザー アカウントが使用されます。有効なユーザー アカウントを変更する必要がある場合は、gcloud auth login を実行します。

-k|--key_file FILE_PATH

サービス アカウントの鍵ファイル。サービス アカウントを使用していない場合は、このオプションを省略します。

Citadel カスタム証明書のオプション

--ca citadel を指定してカスタム CA を使用する場合は、次のオプションを指定します。

  • --ca_cert FILE_PATH: 中間証明書
  • --ca_key FILE_PATH: 中間証明書の鍵
  • --root_cert FILE_PATH: ルート証明書
  • --cert_chain FILE_PATH: 証明書チェーン

詳細については、既存の CA 証明書への接続をご覧ください。

イネーブルメント フラグ

--enable で始まるフラグによって、スクリプトは必要な Google API を有効にし、必要な Identity and Access Management（IAM）権限を設定して、クラスタを更新します。必要に応じて、スクリプトを実行する前に、プロジェクトとクラスタを自分で更新することもできます。詳細については、マルチ プロジェクト インストール ガイドのプロジェクトの設定とクラスタの設定セクションをご覧ください。これらのフラグはすべて --only_validate と互換性がなく、この場合はスクリプトでエラーが発生して終了します。

-e|--enable_all
以下で説明する個々の有効化の操作をすべてスクリプトで実行できるようにします。
--enable_cluster_roles
スクリプトを実行している GCP ユーザーまたはサービス アカウントをクラスタの cluster-admin ロールにバインドできるようにします。このスクリプトは、gcloud config get core/account コマンドからユーザー アカウントを特定します。ユーザー アカウントを使用してスクリプトをローカルで実行する場合は、必ず gcloud auth login コマンドを呼び出してからスクリプトを実行してください。ユーザー アカウントを変更する必要がある場合は、gcloud config set core/account GCP_EMAIL_ADDRESS コマンドを実行します。ここで、GCP_EMAIL_ADDRESS は、Google Cloud へのログインに使用するアカウントです。
--enable_cluster_labels
スクリプトで、必要なクラスタラベルを設定できるようにします。
--enable_gcp_components

スクリプトで、次の必要な Google Cloud マネージド サービスとコンポーネントを有効にできるようにします。

--enable_gcp_apis

スクリプトで、すべての必要な Google API を有効にできるようにします。

--enable_gcp_iam_roles

スクリプトで、必要な IAM 権限を設定できるようにします。

--enable_registration

スクリプトでクラスタが所属するプロジェクトにそのクラスタを登録できるようにします。このフラグを指定しない場合は、クラスタの登録の手順に沿ってクラスタを手動で登録してください。他のイネーブルメント フラグとは異なり、--enable_registration は、クラスタ登録を必要とするオプション（--option vm や --option hub-meshca など）を指定した場合に --enable_all にのみ含まれます。こうしたオプションを指定しない場合、このフラグは個別に指定する必要があります。

その他のフラグ

--dry_run
コマンドを出力しますが、実行しません。
--only_validate
検証を実行しますが、プロジェクトやクラスタは更新しません。また、Anthos Service Mesh はインストールしません。このフラグはイネーブルメント フラグと互換性がありません。任意のイネーブルメント フラグとともに --only_validate を指定すると、スクリプトはエラーで終了します。
--print_config
Anthos Service Mesh をインストールする代わりに、コンパイル済みのすべての YAML を標準出力（stdout）に出力します。通常は stdout に出力される場合でも、他のすべての出力が標準エラー（stderr）に書き込まれます。このフラグを指定すると、すべての検証と設定がスキップされます。
--disable_canonical_service
デフォルトでは、このスクリプトは Canonical Service コントローラをクラスタにデプロイします。スクリプトでコントローラをデプロイしない場合は、--disable_canonical_service を指定します。詳細については、Canonical Service コントローラの有効化と無効化をご覧ください。
-h|--help
オプション、フラグ、終了を説明するヘルプ メッセージを表示します。
-v|--verbose
スクリプトが実行されると、次に実行されるコマンドが出力されます。--verbose フラグを指定すると、実行後にコマンドが出力されます。
--version
install_asm のバージョンを出力して終了します。このコマンドでバージョンが出力されない場合は、install_asm_1.11 の最新バージョンをダウンロードします。

スクリプトについて

スクリプトは、安全な Cloud Source Repositories のロケーションからダウンロードしますが、GitHub からも入手できます。ダウンロードする前にソースコードを見ておくと、スクリプトの処理内容を確認できます。このスクリプトは、プロジェクトとクラスタが Anthos Service Mesh 要件を満たしていることを検証し、プロジェクトとクラスタの構成に手動で行うすべての手順を自動化します。その後、istioctl install コマンドを使用して Anthos Service Mesh をインストールします。

Anthos Service Mesh 1.11.8 では、release-1.11 ブランチで install_asm スクリプトのバージョンを使用します。バージョニングとリリースのプロセスについては、バージョニング / リリースをご覧ください。

検証

validate_dependencies() {
  validate_node_pool
  validate_k8s
  validate_expected_control_plane

  if [[ "${MODE}" = "migrate" ]]; then
    validate_istio_version
  elif [[ "${MODE}" = "upgrade" ]]; then
    validate_asm_version
    validate_ca_consistency
  fi
}

install_asm スクリプトは次のことを確認します。

  • パラメータ値として入力したプロジェクト ID、クラスタ名、クラスタのロケーションが有効であること。
  • クラスタが最低限必要なマシンタイプとノード数を満たしていること。

プロジェクトの設定

必要なロール

--enable_all フラグまたは --enable_gcp_iam_roles フラグを含めると、スクリプトにより必要な IAM 権限が設定されます。

required_iam_roles() {
  # meshconfig.admin - required for init, stackdriver, UI elements, etc.
  # servicemanagement.admin/serviceusage.serviceUsageAdmin - enables APIs
  if can_modify_gcp_components || \
     can_modify_cluster_labels || \
     can_modify_cluster_roles; then
    echo roles/container.admin
  fi
  if can_modify_gcp_components; then
    echo roles/meshconfig.admin
  fi
  if can_modify_gcp_apis; then
    echo roles/servicemanagement.admin
    echo roles/serviceusage.serviceUsageAdmin
  fi
  if can_modify_gcp_iam_roles; then
    echo roles/resourcemanager.projectIamAdmin
  fi
  if is_sa; then
    echo roles/iam.serviceAccountAdmin
  fi
  if can_register_cluster; then
    echo roles/gkehub.admin
  fi
  if [[ "${CA}" = "gcp_cas" ]]; then
    echo roles/privateca.admin
  fi
  if [[ "${_CI_I_AM_A_TEST_ROBOT}" -eq 1 ]]; then
    echo roles/compute.admin
    echo roles/iam.serviceAccountKeyAdmin
  fi
}

必要な Google API

--enable_all または --enable_apis フラグを含めると、スクリプトにより必要な API が有効になります。

required_apis() {
    cat << EOF
container.googleapis.com
monitoring.googleapis.com
logging.googleapis.com
cloudtrace.googleapis.com
meshtelemetry.googleapis.com
meshconfig.googleapis.com
iamcredentials.googleapis.com
gkeconnect.googleapis.com
gkehub.googleapis.com
cloudresourcemanager.googleapis.com
stackdriver.googleapis.com
EOF
  case "${CA}" in
   mesh_ca)
     echo meshca.googleapis.com
     ;;
   gcp_cas)
     echo privateca.googleapis.com
     ;;
    *);;
  esac

  if [[ "${_CI_I_AM_A_TEST_ROBOT}" -eq 1 ]]; then
    echo compute.googleapis.com
  fi
}

クラスタの設定

--enable_all フラグ、またはよりきめ細かい下のイネーブルメント フラグのいずれかが含まれると、スクリプトによりクラスタで次の更新が行われます。

クラスタの更新 フラグ
Workload Identity を有効にすると、GKE アプリケーションが Google Cloud サービスに安全にアクセスできるようになります。 --enable_gcp_components
GKE で Cloud Monitoring と Cloud Logging を有効にします。 --enable_gcp_components
クラスタで mesh_id ラベルを設定します。これは、Google Cloud コンソールの Anthos Service Mesh ページに指標を表示するために必要です。 --enable_cluster_labels
asmv=asm-1118-4 のようなラベルを設定し、スクリプトによってクラスタが変更されていることを示します。 --enable_cluster_labels
スクリプトを実行している GCP ユーザーまたはサービス アカウントを、クラスタの cluster-admin ロールにバインドします。 --enable_cluster_roles

次のステップ