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

项目
11/26/2024

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

在开始之前，请阅读启用了 Azure 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`	在其上创建扩展实例的群集类型。对于大多数应用场景，请使用 `connectedClusters`，它是已启用 Azure Arc 的 Kubernetes 群集的群集类型。

可选参数

可以将这些可选参数中的一个或多个与您的应用场景所需的参数一起使用。

注意

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

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

参数名称	说明
`--auto-upgrade-minor-version`	用于设置是否自动升级扩展次要版本的布尔属性。默认设置为 `true`。如果此参数设置为 `true`，则不能设置 `version` 参数，因为版本将动态更新。如果此参数设置为 `false`，则扩展不会自动升级，甚至包括其修补程序版本。
`--version`	要安装的扩展版本（要将扩展实例固定到的特定版本）。如果 `auto-upgrade-minor-version` 设置为 `true`，则无法设置 `version` 参数。
`--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`	JSON 文件的路径，该文件包含用于将配置设置传入到扩展的 `key=value` 对。如果在命令中使用此参数，则不能在同一命令中使用 `--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 版本。

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

通过

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

先决条件

创建扩展实例

必需的参数

可选参数

显示扩展详细信息

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

更新扩展实例

要更新的必需参数

要更新的可选参数

升级扩展实例

删除扩展实例

相关内容

其他资源