asmcli 参考

注意：本指南仅支持使用 Istio API 的 Cloud Service Mesh，不支持 Google Cloud API。如需了解详情，请参阅 Cloud Service Mesh 概览。

概览

asmcli 是 Google 提供的一款工具，可用于安装或升级 Cloud Service Mesh。如果允许，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.27。

改用 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执行 Canary 版升级。

  • 如果控制层面修订版本标签相同，则 asmcli 将执行就地升级。

• 大多数asmcli选项和标志的行为与install_asm表现一致。

从 istioctl install 转换

如果您熟悉istioctl install（如果您通常会传递IstioOperator通过-f命令行参数来配置控制层面，那么您可以将文件传递给asmcli使用--custom_overlay选项。 在 Cloud Service Mesh 文档中，我们将这些文件称为叠加文件。

提醒：默认情况下，asmcli 不会随控制层面一起安装入站流量网关。对于生产部署，我们建议您单独安装网关。如需了解详情和最佳实践，请参阅安装和升级网关。我们在 anthos-service-mesh 代码库中提供了入站流量和出站流量网关的示例 Deployment、Service、ServiceAccount 和 Role 配置文件，帮助您快速上手使用。您可以按原样部署它们，也可以根据需要进行自定义。

支持的平台

已弃用：使用 asmcli 为 GKE on Google Cloud 的托管式控制平面配置 Cloud Service Mesh 的功能已弃用。如需了解详情，请参阅 Cloud Service Mesh 版本说明。如需为 GKE 配置托管式 Cloud Service Mesh，请按照此指南操作。

支持的平台列表中列出的 Cloud Service Mesh 安装可以使用 asmcli 进行配置或升级。

不过，并非所有功能都可在 Google Cloud外部的平台上使用。如需了解详情，请参阅集群内控制平面支持的功能。

asmcli 参考

本部分介绍了 asmcli 的可用参数。

注意：运行 ./asmcli -h -v 命令可查看可用标志和选项及其说明的完整列表。

选项

识别集群 您可以使用以下选项来识别集群：

仅针对 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 使用默认上下文。

警告：请仅使用来自可信来源的 kubeconfig 文件。使用特别设计的 kubeconfig 文件可能会导致恶意代码执行或文件泄露。如果必须使用不受信任的 kubeconfig 文件，请先仔细检查文件，就像使用 shell 脚本一样。

-c|--ca {mesh_ca|gcp_cas|citadel}

用于管理双向 TLS 证书的证书授权机构 (CA)。指定 mesh_ca 可使用 Cloud Service Mesh 证书授权机构（Cloud Service Mesh 证书授权机构），指定 gcp_cas 可使用 Certificate Authority Service，或者指定 citadel 可使用 Istio CA。托管式 Cloud Service Mesh 不支持 Istio CA。要了解更多信息，请参阅以下内容：

• 选择证书授权机构
• Istio CA 自定义证书选项
• 将 Cloud Service Mesh 配置为使用 CA Service

--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 集群发布渠道确定。如需了解详情，请参阅托管式 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 命名空间的 topology.istio.io/network 标签。对于 GKE，--network_id 默认为集群的网络名称。对于其他环境，系统将使用 default。

-o|--option OVERLAY_FILE

叠加文件的名称（不带 .yaml 扩展名），asmcli 从 anthos-service-mesh 代码库下载该文件以启用可选功能。您需要连接到互联网才能使用 --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.27.1-asm.5 子目录。asm 目录包含安装的配置。istio-1.27.1-asm.5 目录包含安装文件的解压缩内容，其中包含 istioctl、示例和清单。如果指定 --output-dir，并且目录已经包含必要的文件，则 asmcli 会使用这些文件，而不是重新下载。

--platform PLATFORM {gcp|multicloud}

Kubernetes 集群的平台或提供方。对于 GKE 集群，默认为 gcp。对于所有其他平台，则为 multicloud。

-r|--revision_name REVISION NAME

修订版本标签是在控制平面上设置的键值对。修订版本标签键始终为 istio.io/rev。默认情况下，asmcli 会根据 Cloud Service Mesh 版本设置修订版本标签的值，例如：asm-1271-5。如果您想替换默认值并指定自己的值，请添加此选项。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，请确保在运行 asmcli 之前调用 gcloud auth login 命令。如果您需要更改用户账号，请运行 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 服务。

• GKE 上的 Cloud Monitoring 和 Cloud Logging。

--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 将集群注册到集群所属项目。如果您未包含此标志，请按照注册集群中的步骤手动注册集群。请注意，与其他启用标志不同，当您指定需要集群注册的选项（例如 --option hub-meshca）时，--enable_registration 才会包含在 --enable_all 中。否则，您需要单独指定此标志。

其他标志

--dry_run

输出命令，但不执行这些命令。

--fleet_id

使用舰队的宿主项目 ID 将集群注册到舰队。此标志是非Google Cloud 集群所必需的。如果没有为Google Cloud 集群提供此标志，则默认为集群的项目 ID。您可以在安装之前将 asmcli install 与 --fleet_id 一起运行，也可以在安装过程中通过传递 --enable-registration 和 --fleet-id 标志来完成。此设置一经配置便无法更改。

--managed

已弃用。预配一个远程托管式控制平面，而不是安装一个集群内控制平面。

--offline

在输出目录中使用预先下载的软件包执行离线安装。如果未指定该目录或者该目录未包含所需文件，则脚本将退出并报错。

--only_enable

执行指定的步骤来设置当前用户/集群，但不安装任何内容。

--only_validate

运行验证，但不更新项目或集群，并且不安装 Cloud Service Mesh。此标志与启用标志不兼容。如果您使用任何启用标志指定 --only_validate，asmcli 会终止并显示错误。

--print_config

将所有已编译的 YAML 输出到标准输出 (stdout)，而不是安装 Cloud Service Mesh。所有其他输出都会写入标准错误 (stderr)，即使它通常会转到 stdout 也是如此。当您指定此标志时，asmcli 会跳过所有验证和设置。

--disable_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.27。