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

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

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

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

  了解如何将 Kubernetes 群集连接到 Azure Arc。如果需要通过出站代理进行连接，则确保使用代理设置安装 Arc 代理。

• 对 Microsoft.Kubernetes/connectedClusters 资源类型的读写权限。

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

  重要

  需要使用托管服务标识（MSI），而不是服务主体名称（SPN）创建 AKS 群集，以便此扩展正常工作。 对于使用 az aks create 创建的新 AKS 群集，群集默认基于 MSI。 若要将基于 SPN 的群集转换为 MSI，请运行 az aks update -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-managed-identity。

• 对 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
  

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

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

安装最新的 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 安装支持高可用性模式下的多租户，并支持工作负载标识。

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

az k8s-extension create --resource-group <resource-group> --cluster-names <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> 命名空间中起作用。

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

若要使用工作负载标识创建扩展，请先在此 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.chinacloudapi.cn/<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.Microsoft 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 > 用户>你的用户名>属性下找到。

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

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 system:serviceaccount:"argocd":"source-controller" --audience api://AzureADTokenExchange
   

4. 请务必为希望源控制器或图像发送程序控制器拉取的资源提供相应的工作负载标识权限。 例如，如果使用 Azure 容器注册表，则需要 AcrPull 权限。

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

如果 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 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。