教程：将 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 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
  

版本和区域支持

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 存储库中的机密或凭据。 此安装利用在 3.0.0-rc2 或更高版本的 Argo CD 中启用的工作负载标识身份验证。

若要使用工作负荷标识创建扩展，请先将此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-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': 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。 ssoWorkloadIdentityClientId 用于 Argo CD UI 的认证，workloadIdentityClientId 用于 Argo CD 组件的工作负载身份。 有关 ssoWorkloadIdentityClientId 的一般设置和配置的更多信息，请访问 使用 OIDC 的 Microsoft Entra ID 应用注册认证。

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

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

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 > 组>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 
   

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

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

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

访问 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

部署 Argo CD 应用程序

安装 Argo CD 扩展后，可以使用 Argo CD UI 或 CLI 部署应用程序。 以下示例简单地使用 kubectl apply 在 Argo CD 应用中将 AKS 存储部署到 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 商店演示应用程序已安装到 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。