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

本教程介绍如何在 Kubernetes 群集中使用 GitOps。 在 Azure Arc 启用的 Kubernetes 集群或 Azure Kubernetes Service (AKS) 集群中，GitOps 已通过 ArgoCD 作为 集群扩展 启用。 借助 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 Service 群集

• 一个已启动并运行的基于 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
  

版本和区域支持

在所有Azure Arc支持的启用Kubernetes的区域, 目前都支持GitOps。 目前，AKS 所支持的一部分区域支持 GitOps。 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 （ArgoCD） 扩展 （简单安装）

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

此命令创建最简单的配置，将 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 \
--release-train preview \
--config "redis-ha.enabled=false" \
--config "configs.params.application\.namespaces=namespace1,namespace2"

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

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

建议用于生产用途的替代安装方法是 工作负荷标识。 此方法允许你使用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>/'
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'
    releaseTrain: 'preview'
    configurationSettings: {
      'redis-ha.enabled': 'true'
      'azure.workloadIdentity.enabled': 'true'
      'azure.workloadIdentity.clientId': workloadIdentityClientId
      'azure.workloadIdentity.entraSSOClientId': ssoWorkloadIdentityClientId
      '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 和 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 是授予管理员权限访问 ArgoCD UI 的 Microsoft Entra 组 ID。 Azure 门户中的 Microsoft Entra 组 ID 位于 Microsoft Entra ID > 组>your-group-name> 属性下。 可以使用 Microsoft Entra 用户 ID 而不是 Microsoft Entra 组 ID。 Microsoft Entra 用户 ID 位于 Azure 门户中的 Microsoft Entra ID 用户 your-user-name 属性 下。

创建工作负载标识凭据

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

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 Container Registry，请确保已应用Container Registry Repository Reader（适用于 ABAC 启用的注册表）或AcrPull（适用于非 ABAC 注册表）。

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

若要利用专用 ACR 注册表或 ACR 存储库，请按照官方 ArgoCD 文档中的说明 连接到专用 ACR 注册表。 标记 Pods、创建联合身份凭证 和 向服务帐户添加注释步骤已经由 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 "configs.cm.url='https://<public-ip-for-argocd-ui>/auth/callback'"

通过扩展更新 ArgoCD 的 ConfigMap，以确保设置不会被覆盖。 应用Bicep模板是使用Azure CLI更新配置的另一种方法。

删除扩展

使用以下命令删除扩展。

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

后续步骤

• Azure/AKS 存储库上的文件问题和功能请求，并确保在说明或标题中包含“ArgoCD”一词。
• 探索 AKS-Platform 工程代码示例，该示例使用 Backstage 和 Cluster API Provider for Azure（CAPZ）或 Crossplane 来部署 OSS ArgoCD。