教程：将 GitOps 与 ArgoCD 配合使用部署应用程序

2025-04-30

本教程介绍如何在 Kubernetes 群集中使用 GitOps。在 Azure Arc 启用的 Kubernetes 集群或 Azure Kubernetes 服务（AKS）集群中，GitOps 已通过 ArgoCD 作为集群扩展启用。借助 GitOps，可将 Git 存储库用作群集配置和应用程序部署的事实来源。

重要

使用 ArgoCD 的 GitOps 目前以预览版提供。有关适用于 Beta 版、预览版或尚未正式发布的 Azure 功能的法律条款，请参阅适用于 Microsoft azure 预览版的补充使用条款。要支持生产环境的 GitOps 扩展，请尝试使用 Flux 的 GitOps 扩展。

小窍门

虽然本教程中的源是 Git 存储库，但 ArgoCD 支持其他通用文件源，例如 Helm 和 Open Container Initiative （OCI）存储库。

先决条件

若要使用 GitOps 部署应用程序，需要已启用 Azure Arc 的 Kubernetes 群集或 AKS 群集：

已启用 Azure Arc 的 Kubernetes 群集

已启动且正在运行的已启用 Azure Arc 的 Kubernetes 连接群集。

了解如何将 Kubernetes 群集连接到 Azure Arc。如果需要通过出站代理进行连接，请确保使用代理设置安装 Arc 代理。
对 Microsoft.Kubernetes/connectedClusters 资源类型的读写权限。

Azure Kubernetes 服务群集

一个已启动并运行的基于 MSI 的 AKS 群集。

重要

需要使用托管服务标识（MSI），而不是服务主体名称（SPN）创建 AKS 群集，以便此扩展正常工作。对于使用 az aks create 创建的新 AKS 群集，群集默认基于 MSI。若要将基于 SPN 的群集转换为 MSI，请运行 az aks update -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-managed-identity。有关详细信息，请参阅在 AKS 中使用托管标识。
对 Microsoft.ContainerService/managedClusters 资源类型的读写权限。

对这两种群集类型通用

对这些资源类型的读取和写入权限：
- Microsoft.KubernetesConfiguration/extensions
Azure CLI 2.15 或更高版本。安装 Azure CLI 或使用以下命令更新到最新版本：
```
az version
az upgrade
```
Kubernetes 命令行客户端 kubectl。如果使用 Azure Cloud Shell，则已安装 kubectl。

在本地使用 kubectl 命令安装 az aks install-cli：
```
az aks install-cli
```

注册以下 Azure 资源提供程序：

az provider register --namespace Microsoft.Kubernetes
az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.KubernetesConfiguration

注册是一个异步过程，在 10 分钟内应会完成。可以使用以下命令来监视注册过程：

az provider show -n Microsoft.KubernetesConfiguration -o table

Namespace                          RegistrationPolicy    RegistrationState
---------------------------------  --------------------  -------------------
Microsoft.KubernetesConfiguration  RegistrationRequired  Registered

版本和区域支持

目前，已启用 Azure Arc 的 Kubernetes 支持的所有区域都支持 GitOps。目前，AKS 所支持的一部分区域支持 GitOps。 GitOps 服务会定期添加新的受支持区域。

网络要求

GitOps 代理必须通过出站（出口）TCP 连接到端口 22 (SSH) 或端口 443 (HTTPS) 上的存储库源才能正常运行。代理还需要对以下出站 URL 的访问权限：

端点 (DNS)	DESCRIPTION
`https://management.azure.com`	所需条件是代理能够与 Kubernetes 配置服务通信。
`https://<region>.dp.kubernetesconfiguration.azure.com`	代理的数据平面终结点，用于推送状态和提取配置信息。取决于 `<region>`（前面提到的受支持区域）。
`https://login.microsoftonline.com`	必须获取和更新 Azure 资源管理器的令牌。
`https://mcr.microsoft.com`	需要用于为控制器拉取容器映像。

启用 CLI 扩展

安装最新的 k8s-configuration 和 k8s-extension CLI 扩展包：

az extension add -n k8s-configuration
az extension add -n k8s-extension

将这些包更新到最新版本：

az extension update -n k8s-configuration
az extension update -n k8s-extension

若要查看已安装的 Azure CLI 扩展列表及其版本，请使用以下命令：

az extension list -o table

Experimental   ExtensionType   Name                   Path                                                       Preview   Version
-------------  --------------  -----------------      -----------------------------------------------------      --------  --------
False          whl             connectedk8s           C:\Users\somename\.azure\cliextensions\connectedk8s         False     1.10.7
False          whl             k8s-configuration      C:\Users\somename\.azure\cliextensions\k8s-configuration    False     2.2.0
False          whl             k8s-extension          C:\Users\somename\.azure\cliextensions\k8s-extension        False     1.6.4

创建 GitOps （ArgoCD）扩展（简单安装）

GitOps ArgoCD 安装支持高可用性模式下的多租户，并支持工作负载标识。

重要

HA 模式是默认配置，需要群集中的三个节点才能安装。以下命令将添加 --config deployWithHighAvailability=false，以在单个节点上安装扩展。

此命令创建最简单的配置，将 ArgoCD 组件安装到具有群集范围的访问的新 argocd 命名空间。通过群集范围的访问，可以在群集的 ArgoCD 配置中列出的任何命名空间中检测 ArgoCD 应用定义。例如：namespace1,namespace2

az k8s-extension create --resource-group <resource-group> --cluster-name <cluster-name> \
--cluster-type managedClusters \
--name argocd \
--extension-type Microsoft.ArgoCD \
--auto-upgrade false \
--release-train preview \
--version 0.0.7-preview \
--config deployWithHightAvailability=false \
--config namespaceInstall=false \
–-config "config-maps.argocd-cmd-params-cm.data.application\.namespaces=namespace1,namespace2"

如果要限制 ArgoCD 对特定命名空间的访问，请同时使用 --config namespaceInstall=true 和 --target-namespace <namespace> 参数。此安装命令将创建一个新的<namespace>命名空间，并在<namespace>中安装 ArgoCD 组件。安装命令还允许在同一群集中安装多个 ArgoCD 实例。在该配置中，ArgoCD 应用程序定义仅在 <namespace> 命名空间中起作用。

使用工作负荷标识创建 GitOps （ArgoCD）扩展

建议用于生产用途的替代安装方法是工作负荷标识。此方法允许使用 Microsoft Entra ID 标识向 Azure 资源进行身份验证，而无需管理 Git 存储库中的机密或凭据。此安装利用在 3.0.0-rc2 或更高版本的 ArgoCD 中启用的工作负载身份验证。

重要

HA 模式是默认配置，需要群集中的三个节点才能安装。添加 --config deployWithHighAvailability=false 以在单个节点上安装扩展。

若要使用工作负载标识创建扩展，请先在此 Bicep 模板中将以下变量替换为自己的值：

var clusterName = '<aks-or-arc-cluster-name>'

var workloadIdentityClientId = 'replace-me##-##-###-###'
var ssoWorkloadIdentityClientId = 'replace-me##-##-###-###'

var url = 'https://<public-ip-for-argocd-ui>/auth/callback'
var oidcConfig = '''
name: Azure
issuer: https://login.microsoftonline.com/<your-tenant-id>/v2.0
clientID: <same-value-as-ssoWorkloadIdentityClientId-above>
azure:
  useWorkloadIdentity: true
requestedIDTokenClaims:
  groups:
    essential: true
requestedScopes:
  - openid
  - profile
  - email
'''

var defaultPolicy = 'role:readonly'
var policy = '''
p, role:org-admin, applications, *, */*, allow
p, role:org-admin, clusters, get, *, allow
p, role:org-admin, repositories, get, *, allow
p, role:org-admin, repositories, create, *, allow
p, role:org-admin, repositories, update, *, allow
p, role:org-admin, repositories, delete, *, allow
g, replace-me##-argocd-ui-Microsoft Entra-group-admin-id, role:org-admin
'''

resource cluster 'Microsoft.ContainerService/managedClusters@2024-10-01' existing = {
  name: clusterName
}

resource extension 'Microsoft.KubernetesConfiguration/extensions@2023-05-01' = {
  name: 'argocd'
  scope: cluster
  properties: {
    extensionType: 'Microsoft.ArgoCD'
    autoUpgradeMinorVersion: false
    releaseTrain: 'preview'
    version: '0.0.7-preview'
    configurationSettings: {
      'workloadIdentity.enable': 'true'
      'workloadIdentity.clientId': workloadIdentityClientId
      'workloadIdentity.entraSSOClientId': ssoWorkloadIdentityClientId
      'config-maps.argocd-cm.data.oidc\\.config': oidcConfig
      'config-maps.argocd-cm.data.url': url
      'config-maps.argocd-rbac-cm.data.policy\\.default': defaultPolicy
      'config-maps.argocd-rbac-cm.data.policy\\.csv': policy
      'config-maps.argocd-cmd-params-cm.data.application\\.namespaces': 'default, argocd'
    }
  }
}

可以使用以下命令创建 Bicep 模板：

az deployment group create --resource-group <resource-group> --template-file <bicep-file>

参数

clusterName 是已启用 AKS 或 Arc 的 Kubernetes 群集的名称。

workloadIdentityClientId 和 ssoWorkloadIdentityClientId 是用于工作负载标识目的的托管标识的客户端 ID。用于 ArgoCD UI 的身份验证是 ssoWorkloadIdentityClientId，用于 ArgoCD 组件的工作负荷标识是 workloadIdentityClientId。有关 ssoWorkloadIdentityClientId 的常规设置和配置的更多信息，请访问使用 OIDC 的 Microsoft Entra ID 应用注册认证。

url 是 ArgoCD UI 的公共 IP。除非群集已有客户提供入口控制器，否则没有公共 IP 或域名。如果是这样，则需要在部署后将入口规则添加到 ArgoCD UI。

oidcConfig - 将 <your-tenant-id> 替换为 Microsoft Entra ID 的租户 ID。将 <same-value-as-ssoWorkloadIdentityClientId-above> 替换为与 ssoWorkloadIdentityClientId 相同的值。

policy 变量是 ArgoCD 的 argocd-rbac-cm configmap 设置。 g, replace-me##-argocd-ui-entra-group-admin-id 是 Microsoft Entra 组 ID，可授予管理员对 ArgoCD UI 的访问权限。 Microsoft Entra 组 ID 可在 Azure 门户中的 “Microsoft Entra ID > 组 >你的组名称> 属性”下找到。可以使用 Microsoft Entra 用户 ID，而不是 Microsoft Entra 组 ID。 Microsoft Entra 用户 ID 可在 Azure 门户中的 Microsoft Entra ID > 用户>你的用户名>属性下找到。

创建工作负载标识凭据

若要设置新的工作负荷标识凭据，请执行以下步骤：

检索 AKS 群集或已启用 Arc 的 Kubernetes 群集的 OIDC 颁发者 URL。
创建托管标识，并记下其客户端 ID 和租户 ID。

为已启用 Arc 的 AKS 群集或已启用 Arc 的 Kubernetes 群集建立联合标识凭据。例如：

# For source-controller
az identity federated-credential create --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --issuer "${OIDC_ISSUER}" --subject system:serviceaccount:"argocd":"source-controller" --audience api://AzureADTokenExchange

请务必为希望源控制器或图像发送程序控制器拉取的资源提供相应的工作负载标识权限。例如，如果使用 Azure 容器注册表，请确保 Container Registry Repository Reader 已应用（对于已启用 ABAC 的注册表）或 AcrPull （对于非 ABAC 注册表）。

使用工作负荷标识连接到专用 ACR 注册表或 ACR 存储库

若要利用专用 ACR 注册表或 ACR 存储库，请按照官方 ArgoCD 文档中的说明连接到专用 ACR 注册表。该指南中的标记 Pod、创建联合标识凭据和向服务帐户添加注释步骤已由扩展使用 Bicep 部署完成，可以跳过。

访问 ArgoCD UI

如果 AKS 群集没有现有的入口控制器，则可以使用 LoadBalancer 服务直接公开 ArgoCD UI。以下命令将在端口 80 和 443 上公开 ArgoCD UI。

kubectl -n argocd expose service argocd-server --type LoadBalancer --name argocd-server-lb --port 80 --target-port 8080

部署 ArgoCD 应用程序

安装 ArgoCD 扩展后，可以使用 ArgoCD UI 或 CLI 部署应用程序。以下示例只使用 kubectl apply 将 ArgoCD 应用程序中的 AKS 存储部署到 argocd 命名空间中的默认 ArgoCD 项目。

kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: aks-store-demo
  namespace: argocd
spec:
  project: default
  source:    
      repoURL: https://github.com/Azure-Samples/aks-store-demo.git
      targetRevision: HEAD
      path: kustomize/overlays/dev
  syncPolicy:
      automated: {}
  destination:
      namespace: argocd
      server: https://kubernetes.default.svc
EOF

AKS 商店演示应用程序已安装到 pets 命名空间中。按照这些说明查看应用程序网页。请务必使用 http 而不是 https 访问 IP 地址。

更新扩展配置

安装后，可以使用以下命令更新 ArgoCD 配置映射和其他扩展配置设置：

az k8s-extension update --resource-group <resource-group> --cluster-name <cluster-name> --cluster-type <cluster-type> --name Microsoft.ArgoCD –-config "config-maps.argocd-cm.data.url='https://<public-ip-for-argocd-ui>/auth/callback'”

通过扩展功能更新 ArgoCD 配置映射很重要，以确保设置不会被覆盖。应用 bicep 模板是替代 az cli 更新配置的一种方法。

删除扩展

使用以下命令删除扩展。

az k8s-extension delete -g <resource-group> -c <cluster-name> -n argocd -t managedClusters --yes

后续步骤

在 Azure/AKS 存储库上提交问题和功能请求，并确保在说明或标题中包含“ArgoCD”一词。
探索 AKS-Platform 工程代码示例，该示例实现了通过 Backstage 和 Azure 群集 API 提供程序 (CAPZ) 或 Crossplane 部署 OSS ArgoCD。

通过