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.22。

改用 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 配置 Cloud Service Mesh 以实现代管式控制 GKE on Google Cloud 的 GKE 控制平面有关详情，请参阅 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 功能时，此标志是必需的。

Managed Cloud Service Mesh 不再支持--channel选项， CSM 版本说明中提及。 发布渠道取决于您的 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.22.5-asm.1 子目录。asm 目录包含安装的配置。istio-1.22.5-asm.1 目录包含安装文件的解压缩内容，其中包含 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-1225-1。如果您想替换默认值并指定自己的值，请添加此选项。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

默认情况下，asmcli 会将规范化服务控制器部署到您的集群。如果您不希望 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.22。