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

本教程介绍如何在已启用 Azure Arc 的 Kubernetes 群集或 Azure Kubernetes 服务 （AKS） 群集中使用 GitOps 和 Argo CD 。 将包含 Argo CD 的 GitOps 作为 群集扩展 启用，使你能够将 Git 存储库用作群集配置和应用程序部署的真相来源。 Argo CD 还支持其他常见文件源，例如 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。

  在本地使用 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
  

版本和区域支持

GitOps 目前在公共区域受支持。

网络要求

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

启用 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 （Argo CD） 扩展 （简单安装）

GitOps Argo CD 安装支持高可用性 (HA) 模式下的多租户，并支持工作负荷标识。

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

az k8s-extension create --resource-group <resource-group> \
  --cluster-name <cluster-name> \
  --cluster-type managedClusters \
  --name argocd \
  --extension-type Microsoft.ArgoCD \
  --config "redis-ha.enabled=false" \
  --config "configs.params.application\.namespaces=namespace1,namespace2"

此安装命令将创建新的<namespace>命名空间，并在<namespace>中安装 Argo CD 组件。 在此配置中，Argo CD 应用程序定义仅在<namespace>命名空间内起作用。

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

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

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

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

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

var url = 'https://<public-ip-for-argocd-ui>/'
var oidcConfig = '''
name: Azure
issuer: https://login.chinacloudapi.cn/<your-tenant-id>/v2.0
clientID: <same-value-as-ssoApplicationClientId>
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-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'
    configurationSettings: {
      'redis-ha.enabled': 'true'
      'azure.workloadIdentity.enabled': 'true'
      'azure.workloadIdentity.clientId': workloadIdentityClientId
      'azure.workloadIdentity.entraSSOClientId': ssoApplicationClientId
      'configs.cm.oidc\\.config': oidcConfig
      'configs.cm.url': url
      'configs.rbac.policy\\.default': defaultPolicy
      'configs.rbac.policy\\.csv': policy
      'configs.params.application\\.namespaces': 'default, argocd'
   }
  }
}

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

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

参数

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

workloadIdentityClientId 是 Argo CD 组件用于工作负荷标识的用户分配托管标识的客户端 ID。

ssoApplicationClientId是用于对 Argo CD UI 进行 OIDC SSO 身份验证的Microsoft Entra应用注册的应用程序（客户端）ID。 有关 ssoApplicationClientId 的常规设置和配置的更多信息，请参阅 使用 OIDC 的 Microsoft Entra ID 应用注册身份验证。

url 是 Argo CD UI 的公共 IP。 除非群集已有客户提供入口控制器，否则没有公共 IP 或域名。 如果是这样，则需要在部署后将入口规则添加到 Argo CD UI。 入口功能需要 应用程序路由加载项 ，并且仅支持 AKS 群集。

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

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

创建工作负载标识凭据

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

1. 检索 AKS 群集 或 Arc 支持的 Kubernetes 群集 的 OIDC 发行者 URL。

2. 创建托管标识，并记下其客户端 ID 和租户 ID。

3. 为 已启用 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
   

4. 请务必为需要由 argocd、image-reflector 控制器或 argocd-repo-server 拉取的资源提供适当的工作负载身份权限。 例如，如果使用 Azure 容器注册表，请确保已应用以下任一项：Container Registry Repository Reader（用于已启用 ABAC 的注册表）或AcrPull（用于非 ABAC 注册表）。

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

若要利用专用 ACR 注册表或 ACR 存储库，请按照官方 Argo CD 文档中的说明 连接到专用 ACR 注册表。 标记 Pods、创建联合身份凭证 和 向服务帐户添加注释步骤已经由 Bicep 扩展程序完成，可以省略。

从 Argo CD OSS 迁移到托管 Argo CD 扩展

使用以下步骤从自管理 Argo CD 安装迁移到Azure托管的 Argo CD 扩展。

迁移路径

使用以下序列来避免控制器冲突并降低迁移风险。

1. 查看当前的 Argo CD 配置和清单：

   • Applications
   • ApplicationSets
   • AppProjects
   • 存储库凭据和模板 （repocreds）
   • 集群密钥

2. 将自管理的 Argo CD 控制器的副本数缩减为 0，以防止双控制器同时运行。

3. 使用与现有部署匹配的设置在群集上安装 Argo CD 扩展。

4. 任何命名空间功能中的应用程序都允许 Argo CD 管理位于其核心命名空间之外的资源。 如果群集已使用此设置，则无需将资源移到新命名空间。 只需配置新扩展即可监视现有应用程序的命名空间。

   案例 A：如果已在 任何命名空间功能中使用应用程序 ：

   1. 将所有 Application、ApplicationSet 和 AppProject 资源保留在其当前命名空间中。
   2. 配置新的托管扩展，以通过扩展的设置监视这些外部命名空间。

   案例 B：如果将资源移到新的扩展命名空间：

   • 根据需要将应用程序、ApplicationSet 和 AppProjects 迁移到扩展命名空间。

5. 将存储库凭据、集群密钥和仓库凭据配置迁移到扩展命名空间。

6. 验证应用程序是否同步并达到预期的正常状态。

7. 完成验证后，删除旧的自托管 Argo CD 部署。

托管扩展使用相同的 Argo CD API 和自定义资源定义（CRD），因此可以重复使用大多数现有清单，但更改最少。

当前限制

• 不支持对 Argo CD ConfigMap 进行直接更新。
• 使用扩展配置 API 和设置来应用 Argo CD 配置更改。

使用 Azure 托管 Prometheus 和 Azure 托管 Grafana 配置监控

可以将 Argo CD 指标发送到 Azure 托管 Prometheus，并在 Azure 托管 Grafana 中将这些指标可视化。

1. 为群集启用 Azure 托管 Prometheus。 请参阅为Azure Kubernetes 服务 (AKS)群集启用监视。

2. 更新扩展配置，以启用指标和 ServiceMonitors。

   var clusterName = '<aks-or-arc-cluster-name>'
   
   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'
       configurationSettings: {
         // Keep your existing settings and add these metrics flags.
         'controller.metrics.enabled': 'true'
         'controller.metrics.serviceMonitor.enabled': 'true'
         'server.metrics.enabled': 'true'
         'server.metrics.serviceMonitor.enabled': 'true'
         'repoServer.metrics.enabled': 'true'
         'repoServer.metrics.serviceMonitor.enabled': 'true'
         'applicationSet.metrics.enabled': 'true'
         'applicationSet.metrics.serviceMonitor.enabled': 'true'
         'apiVersionOverrides.monitoring': 'azmonitoring.coreos.com/v1'
       }
     }
   }
   

3. 将 Grafana 仪表板 14584 导入Azure 托管 Grafana实例。

4. 如果面板显示 “无数据”，请更新面板中的查询，以适配 Azure 托管 Prometheus 的作业命名。

5. 在控制器遥测面板中（内存使用情况、CPU 使用率、Goroutine），更改：

   • 来自 job="argocd-metrics"
   • 到 job=~"argocd.*-metrics"

6. 在存储库服务器面板（内存已用、Goroutines）中，更改：

   • 来自 job="argocd-repo-server"
   • 到 job="argocd-repo-server-metrics"

7. 保存仪表板并验证指标引入。

在 Azure 门户中启用 Argo CD

可以在 Azure 门户中启用 Argo CD，以查看应用程序状态和同步状态，以及访问 Argo CD UI。 若要在 Azure 门户中启用 Argo CD，请执行以下步骤：

1. 前往 Azure 门户中的群集。

2. 在服务菜单中的 “设置”下，选择 “GitOps”。

3. 选择“启用 Argo CD”（预览版）。

4. 在“基本信息”部分中：

   1. 设置运行 Argo CD 的命名空间。 默认情况下，命名空间为 argocd.
   2. 如果需要，请启用 Redis 高可用性（HA）。 此选项要求群集中至少有 4 个节点。
   3. （可选）添加要观察的任何其他命名空间。
   4. 仅适用于 AKS 群集，可选择启用单点登录（SSO），以便用户能够使用 Microsoft Entra ID 登录，并指定 应用程序 和一个或多个 组，以允许访问 Argo CD UI。
   5. 如果需要，请启用工作负荷标识，让 Argo CD 安全地访问Azure服务，而无需存储机密。 为此，请选中“启用工作负荷标识”复选框，并指定托管标识和用于拉取应用程序清单或容器构件的 Azure 容器注册表。

   

5. 选择“下一步”以继续。

6. 对于启用了 应用程序路由加载项的 AKS 群集， “入口 ”选项卡允许创建入口资源以将流量路由到服务。 如果需要，请选择“ 启用入口 ”并输入入口名称、证书详细信息和域名。 选择“下一步”以继续。

7. 在“ 查看 + 部署 ”部分中，查看设置，然后选择“ 部署 ”以在群集上启用 Argo CD。

访问 Argo CD UI

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

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

若要从 Azure 门户访问 Argo CD UI，请转到群集。 在服务菜单中的“设置”下，选择“GitOps”。 然后，选择显示为 Argo CD UI 的链接。

部署 Argo CD 应用程序

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

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 Store 示例应用程序安装在 argocd 命名空间中。 若要查看应用程序网页， 请按照这些说明操作。 请务必使用 http 而不是 https 来访问该 IP 地址。

更新扩展配置

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

az k8s-extension update --resource-group <resource-group> \
  --cluster-name <cluster-name> \
  --cluster-type <cluster-type> \
  --name argocd \
  --config "configs.cm.url='https://<public-ip-for-argocd-ui>/auth/callback'"

使用扩展来更新 Argo CD 配置映射，以防止设置被覆盖。 应用Bicep模板是使用Azure 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 Argo CD。