部署并管理已启用 Azure Arc 的 Kubernetes 群集扩展

项目
02/26/2024

你可以在已启用 Arc 的 Kubernetes 群集中创建扩展实例，设置必需和可选的参数，包括与更新和配置相关的选项。你还可以查看、列出、更新和删除扩展实例。

在开始之前，请阅读启用了 Arc 的 Kubernetes 群集扩展的概念概述，并查看当前可用扩展的列表。

先决条件

最新版本的 Azure CLI。
最新版本的 connectedk8s 和 k8s-extension Azure CLI 扩展。运行以下命令安装这些扩展：
```
az extension add --name connectedk8s
az extension add --name k8s-extension
```
如果已安装 connectedk8s 和 k8s-extension 扩展，请确保使用以下命令将其更新到最新版本：
```
az extension update --name connectedk8s
az extension update --name k8s-extension
```
一个现有的已启用 Azure Arc 的 Kubernetes 连接群集，其中至少包含一个操作系统和体系结构类型为 linux/amd64 的节点。如果部署 Flux (GitOps)，则可以在没有 linux/amd64 节点的情况下使用基于 ARM64 的群集。
- 如果你尚未连接群集，请使用我们的快速入门。
- 将代理升级到最新版本。

注意

在从 Azure 预配的 AKS 混合群集上安装 Azure Arc 扩展目前为预览版，支持 Azure Key Vault 机密提供程序和 Flux （GitOps）扩展。

创建扩展实例

若要创建新的扩展实例，请使用 k8s-extension create 并传递必需参数的值。

此示例在已启用 Azure Arc 的 Kubernetes 群集上创建 Azure Key Vault 机密提供程序扩展实例：

az k8s-extension create --name akvsecretsprovider  --extension-type Microsoft.AzureKeyVaultSecretsProvider --scope cluster --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters

输出：

{
  "aksAssignedIdentity": null,
  "autoUpgradeMinorVersion": true,
  "configurationProtectedSettings": {},
  "configurationSettings": {},
  "customLocationSettings": null,
  "errorInfo": null,
  "extensionType": "microsoft.azurekeyvaultsecretsprovider",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/demo/providers/Microsoft.Kubernetes/connectedClusters/chenyeaks/providers/Microsoft.KubernetesConfiguration/extensions/akvsecretsprovider",
  "identity": {
    "principalId": "3f9c9566-1d32-4861-9f36-9739bf853420",
    "tenantId": null,
    "type": "SystemAssigned"
  },
  "installedVersion": null,
  "name": "akvsecretsprovider",
  "packageUri": null,
  "provisioningState": "Succeeded",
  "releaseTrain": "Stable",
  "resourceGroup": "demo",
  "scope": {
    "cluster": {
      "releaseNamespace": "kube-system"
    },
    "namespace": null
  },
  "statuses": [],
  "systemData": {
    "createdAt": "2023-09-13T02:34:19.549739+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2023-09-13T02:34:19.549739+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
  },
  "type": "Microsoft.KubernetesConfiguration/extensions",
  "version": "1.4.2"
}

必需的参数

使用 az k8s-extension create 创建扩展实例时，以下参数是必需的。

参数名称	说明
`--name`	扩展实例的名称
`--extension-type`	要在群集上安装的扩展类型。例如：Microsoft.AzureMonitor.Containers、microsoft.azuredefender.kubernetes
`--scope`	扩展的安装范围：`cluster` 或 `namespace`
`--cluster-name`	必须在其上创建扩展实例的已启用 Azure Arc 的 Kubernetes 资源的名称
`--resource-group`	包含已启用 Azure Arc 的 Kubernetes 资源的资源组
`--cluster-type`	必须要在其上创建扩展实例的群集类型。对于大多数方案，请使用与已启用 Azure Arc 的 Kubernetes 群集对应的 `connectedClusters`。

可选参数

根据方案的需要，使用这些可选参数中的一个或多个，以及必需的参数。

注意

可以通过将 auto-upgrade-minor-version 设置为 true，将扩展实例自动升级到最新的次要版本和修补程序版本，或者，也可以改用 --version 参数手动设置扩展实例的版本。建议启用次要版本和修补程序版本自动升级，以便始终获得最新的安全修补程序和功能。

由于主要版本升级可能包括中断性变更，因此不支持自动升级扩展实例的新主要版本。可以选择何时手动将扩展程序实例升级到新的主要版本。

参数名称	说明
`--auto-upgrade-minor-version`	用于确定是否自动升级扩展次要版本的布尔属性。默认设置为 `true`。如果此参数设置为 `true`，则你不能设置 `version` 参数，因为版本将动态更新。如果设置为 `false`，则扩展不会自动升级，甚至包括其修补程序版本。
`--version`	要安装的扩展版本（要将扩展实例固定到的特定版本）。如果 `auto-upgrade-minor-version` 设置为 `true`，则不得提供此参数。
`--configuration-settings`	可传入到扩展以控制其功能的设置。需在参数名称的后面以空格分隔的 `key=value` 对形式传入这些设置。如果在命令中使用此参数，则不能在同一命令中使用 `--configuration-settings-file`。
`--configuration-settings-file`	包含 `key=value` 对的 JSON 文件的路径，该文件用于将配置设置传入扩展。如果在命令中使用此参数，则不能在同一命令中使用 `--configuration-settings`。
`--configuration-protected-settings`	无法使用 `GET` API 调用或 `az k8s-extension show` 命令检索的设置。通常用于传入敏感设置。需在参数名称的后面以空格分隔的 `key=value` 对形式传入这些设置。如果在命令中使用此参数，则不能在同一命令中使用 `--configuration-protected-settings-file`。
`--configuration-protected-settings-file`	包含 `key=value` 对的 JSON 文件的路径，该文件用于将敏感设置传入扩展。如果在命令中使用此参数，则不能在同一命令中使用 `--configuration-protected-settings`。
`--release-namespace`	此参数指示要在其中创建版本的命名空间。仅当 `scope` 设置为 `cluster` 时才相关。
`--release-train`	扩展作者可以在不同的版本序列（例如 `Stable`、`Preview` 等）中发布版本。如果未显式设置此参数，则默认将使用 `Stable`。
`--target-namespace`	指示要在其中创建版本的命名空间。为此扩展实例创建的系统帐户的权限将限于此命名空间。仅当 `scope` 设置为 `namespace` 时才相关。

显示扩展详细信息

若要查看当前安装的扩展实例的详细信息，请使用 k8s-extension show 并传入必需参数的值。

az k8s-extension show --name akvsecretsprovider --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters

输出：

{
  "aksAssignedIdentity": null,
  "autoUpgradeMinorVersion": true,
  "configurationProtectedSettings": {},
  "configurationSettings": {},
  "customLocationSettings": null,
  "errorInfo": null,
  "extensionType": "microsoft.azurekeyvaultsecretsprovider",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/demo/providers/Microsoft.Kubernetes/connectedClusters/chenyeaks/providers/Microsoft.KubernetesConfiguration/extensions/akvsecretsprovider",
  "identity": {
    "principalId": "3f9c9566-1d32-4861-9f36-9739bf853420",
    "tenantId": null,
    "type": "SystemAssigned"
  },
  "installedVersion": null,
  "name": "akvsecretsprovider",
  "packageUri": null,
  "provisioningState": "Succeeded",
  "releaseTrain": "Stable",
  "resourceGroup": "demo",
  "scope": {
    "cluster": {
      "releaseNamespace": "kube-system"
    },
    "namespace": null
  },
  "statuses": [],
  "systemData": {
    "createdAt": "2023-09-13T02:34:19.549739+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2023-09-13T02:34:19.549739+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
  },
  "type": "Microsoft.KubernetesConfiguration/extensions",
  "version": "1.4.2"
}

列出群集上安装的所有扩展

若要查看群集上安装的所有扩展的列表，请使用 k8s-extension list 并传入必需参数的值。

az k8s-extension list --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters

输出：

[
  {
    "aksAssignedIdentity": null,
    "autoUpgradeMinorVersion": true,
    "configurationProtectedSettings": {},
    "configurationSettings": {},
    "customLocationSettings": null,
    "errorInfo": null,
    "extensionType": "microsoft.azurekeyvaultsecretsprovider",
    "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/demo/providers/Microsoft.Kubernetes/connectedClusters/chenyeaks/providers/Microsoft.KubernetesConfiguration/extensions/akvsecretsprovider",
    "identity": {
      "principalId": "3f9c9566-1d32-4861-9f36-9739bf853420",
      "tenantId": null,
      "type": "SystemAssigned"
    },
    "installedVersion": null,
    "name": "akvsecretsprovider",
    "packageUri": null,
    "provisioningState": "Succeeded",
    "releaseTrain": "Stable",
    "resourceGroup": "demo",
    "scope": {
      "cluster": {
        "releaseNamespace": "kube-system"
      },
      "namespace": null
    },
    "statuses": [],
    "systemData": {
      "createdAt": "2023-09-13T02:34:19.549739+00:00",
      "createdBy": null,
      "createdByType": null,
      "lastModifiedAt": "2023-09-13T02:34:19.549739+00:00",
      "lastModifiedBy": null,
      "lastModifiedByType": null
    },
    "type": "Microsoft.KubernetesConfiguration/extensions",
    "version": "1.4.2"
  }
]

更新除扩展实例

注意

参阅特定扩展类型的文档，以了解 --configuration-settings 和 --configuration-protected-settings 中可更新的特定设置。对于 --configuration-protected-settings，应提供所有设置，即使只更新一个设置。如果省略其中的任何一个设置，则会将这些设置视为已过时并将其删除。

若要更新现有的扩展实例，请使用 k8s-extension update 并传入必需参数和可选参数的值。必需参数和可选参数与用于创建扩展实例的参数略有不同。

此示例将 Azure 机器学习扩展实例的 auto-upgrade-minor-version 设置更新为 true：

az k8s-extension update --name akvsecretsprovider --cluster-resource-provider Microsoft.AzureKeyvaultSecretsProvider --cluster-name <clusterName> --resource-group <resourceGroupName> --auto-upgrade-minor-version false --cluster-type connectedClusters

要更新的必需参数

参数名称	说明
`--name`	扩展实例的名称
`--cluster-name`	必须在其中创建扩展实例的群集的名称
`--resource-group`	包含群集的资源组
`--cluster-type`	必须要在其上创建扩展实例的群集类型。对于已启用 Azure Arc 的 Kubernetes 群集，请使用 `connectedClusters`。对于 AKS 群集，请使用 `managedClusters`。

要更新的可选参数

参数名称	说明
`--auto-upgrade-minor-version`	用于指定是否自动升级扩展次要版本的布尔属性。默认设置为 `true`。如果此参数设置为 true，则你不能设置 `version` 参数，因为版本将动态更新。如果设置为 `false`，则扩展不会自动升级，甚至包括其修补程序版本。
`--version`	要安装的扩展版本（要将扩展实例固定到的特定版本）。如果 auto-upgrade-minor-version 设置为 `true`，则不可提供此参数。
`--configuration-settings`	可传入到扩展以控制其功能的设置。需在参数名称的后面以空格分隔的 `key=value` 对形式传入这些设置。如果在命令中使用此参数，则不能在同一命令中使用 `--configuration-settings-file`。只需要提供需要更新的设置。提供的设置将替换为指定的值。
`--configuration-settings-file`	包含 `key=value` 对的 JSON 文件的路径，该文件用于将配置设置传入扩展。如果在命令中使用此参数，则不能在同一命令中使用 `--configuration-settings`。
`--configuration-protected-settings`	无法使用 `GET` API 调用或 `az k8s-extension show` 命令检索的设置。通常用于传入敏感设置。需在参数名称的后面以空格分隔的 `key=value` 对形式传入这些设置。如果在命令中使用此参数，则不能在同一命令中使用 `--configuration-protected-settings-file`。更新某个受保护设置时，应指定所有受保护设置。如果省略其中的任何一个设置，则会将这些设置视为已过时并将其删除。
`--configuration-protected-settings-file`	包含 `key=value` 对的 JSON 文件的路径，该文件用于将敏感设置传入扩展。如果在命令中使用此参数，则不能在同一命令中使用 `--configuration-protected-settings`。
`--scope`	扩展的安装范围 - `cluster` 或 `namespace`。
`--release-train`	扩展作者可以在不同的版本序列（例如 `Stable`、`Preview` 等）中发布版本。如果未显式设置此参数，则默认将使用 `Stable`。

升级扩展实例

如前所述，如果将 auto-upgrade-minor-version 设置为 true，则在发布新的次要版本时，扩展将自动升级。在大多数情况下，我们建议启用自动升级。将 auto-upgrade-minor-version 设置为 false 后，如果你需要更新的版本，必须手动升级扩展。

此外，需要手动升级才能获得扩展的新主要实例。你可以选择升级时间，以避免主要版本升级导致任何意外的中断性变更。

若要手动升级扩展实例，请使用 k8s-extension update，并设置 version 参数以指定版本。

此示例将 Azure Key Vault 机密提供程序实例更新为 x.y.z 版：

az k8s-extension update --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters --name akvsecretsprovider --version x.y.z

删除扩展实例

若要删除群集上的扩展实例，请使用 k8s-extension delete 并传入必需参数的值：

az k8s-extension delete --name akvsecretsprovider --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters

注意

代表此扩展的 Azure 资源将会立即删除。仅当 Kubernetes 群集上运行的代理已建立网络连接，并且可以再次访问 Azure 服务以获取所需状态时，才会删除群集上与此扩展关联的 Helm 版本。

重要

使用从 Azure 预配的 AKS 混合群集时，必须添加 --yes 以删除命令。在从 Azure 预配的 AKS 混合群集上安装 Azure Arc 扩展目前为预览版。

从 Azure 预配的 AKS 混合群集（预览版）

可以将扩展部署到从 Azure 预配的 AKS 混合群集。但是，为了成功完成部署，需要记住几个关键的区别：

--cluster-type 参数的值必须是 provisionedClusters。
必须将 --cluster-resource-provider microsoft.hybridcontainerservice 添加到命令中。

删除扩展实例时，必须将 --yes 添加到命令中：

az k8s-extension delete --name azuremonitor-containers --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type provisionedClusters --cluster-resource-provider microsoft.hybridcontainerservice --yes

此外，必须使用最新版本的 Azure CLI k8s-extension 模块（版本 >= 1.3.3）。使用以下命令添加或更新到最新版本：

# add if you do not have this installed
az extension add --name k8s-extension

# update if you do have the module installed
az extension update --name k8s-extension

重要

在从 Azure 预配的 AKS 混合群集上安装 Azure Arc 扩展的功能目前为预览版。

后续步骤

查看 az k8s-extension CLI 参考以获得完整的命令和参数列表。
详细了解扩展在已启用 Arc 的 Kubernetes 群集上的工作原理。
查看当前可用于已启用 Azure Arc 的 Kubernetes 的群集扩展。

通过

部署并管理已启用 Azure Arc 的 Kubernetes 群集扩展

先决条件

创建扩展实例

必需的参数

可选参数

显示扩展详细信息

列出群集上安装的所有扩展

更新除扩展实例

要更新的必需参数

要更新的可选参数

升级扩展实例

删除扩展实例

从 Azure 预配的 AKS 混合群集（预览版）

后续步骤

其他资源