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

可以在已启用Azure Arc的 Kubernetes 群集中使用扩展来启用Azure服务和方案。本文介绍如何创建扩展实例并设置必需和可选参数，包括更新和配置选项。还可以了解如何查看、列出、更新和删除扩展实例。

在开始之前，请阅读启用了 Azure Arc 的 Kubernetes 群集扩展的概述，并查看当前可用扩展的列表。本文中的步骤适用于任何扩展，但请查看要部署的特定扩展的文档以了解任何特定的配置设置或指南。

先决条件

最新版本的 Azure CLI。
最新版本的 connectedk8s 和 k8s-extension Azure CLI 扩展。若要安装或更新这些扩展的最新版本，请运行以下命令：
```
az extension add --upgrade --name connectedk8s
az extension add --upgrade --name k8s-extension
```
一个现有的已启用 Azure Arc 的 Kubernetes 连接群集，其中至少包含一个操作系统和体系结构类型为 linux/amd64 的节点。如果仅部署 Flux （GitOps）或 Microsoft Defender for Containers 扩展，则可以在不使用节点的情况下 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`。
`--cluster-name`	用于创建扩展实例的 Azure Arc 启用的 Kubernetes 资源名称。
`--resource-group`	包含已启用 Azure Arc 的 Kubernetes 资源的资源组。
`--cluster-type`	在其上创建扩展实例的群集类型。对于大多数应用场景，请使用 `connectedClusters`，它是已启用 Azure Arc 的 Kubernetes 群集的群集类型。

用于创建扩展的可选参数

将其中一个或多个可选参数与方案所需的参数一起使用。其中一些参数不能一起使用。查看每个参数的说明，并使用适用于你的方案的说明。

注意

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

因为主版本更新可以包括破坏性更改，因此在扩展程序实例的新主版本上没有自动更新支持。可以选择何时将扩展实例手动升级到新的主版本。

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

有关其他可选参数的信息，请参阅 az k8s-extension create 参考文档。

显示扩展详细信息

若要查看当前安装的扩展实例的详细信息，请使用 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 和 --config-protected-settings 设置的信息，请参阅特定扩展的文档。对于 --config-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` 对的形式传入这些设置。如果在命令中使用此参数，则在同一命令中不能使用`--config-settings-file`。仅提供需要更新的设置。提供的设置被替换为指定的值。
`--config-settings-file`	JSON 文件的路径，其中包含 `key=value` 用于将配置设置传递到扩展的对。如果在命令中使用此参数，则在同一命令中不能使用`--configuration-settings`。
`--config-protected-settings`	无法使用 `GET` API 调用或 `az k8s-extension show` 命令检索的设置。通常用于传入敏感设置。在参数名称后面以空格分隔 `key=value` 对的形式传入这些设置。如果在命令中使用此参数，则不能在同一命令中使用`--config-protected-settings-file`。更新受保护的设置时，请配置所有受保护的设置。如果省略任何设置，这些设置被视为已过时，并且会将其删除。
`--config-protected-settings-file`	JSON 文件的路径，其中包含 `key=value` 键值对，用于向扩展传递敏感设置。如果在命令中使用此参数，则在同一命令中不能使用`--config-protected-settings`。
`--scope`	扩展的安装范围（`cluster` 或 `namespace`）。大多数扩展都是群集范围的，因此仅当扩展是命名空间范围的时才需要此参数。
`--release-train`	如果扩展在不同的发布节奏（如`Stable`或`Preview`）中发布了版本。如果未显式设置此参数， `Stable` 则为默认值。

有关其他可选参数的信息，请参阅 az k8s-extension update 参考文档。

升级扩展实例

如前所述，如果将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 版本。

有关命令和参数的综合列表，请参阅 az k8s-extension CLI 参考。
了解扩展如何与启用 Azure Arc 的 Kubernetes 群集协作。
查看可用于已启用 Azure Arc 的 Kubernetes 的群集扩展。

Last updated on 2026-03-19

通过