教學：使用 Argo CD 的 GitOps 部署應用程式

本教學說明如何在 Azure Arc 啟用的 Kubernetes 叢集或 Azure Kubernetes Service（AKS）叢集中使用 Argo CD 的 GitOps 。 GitOps with Argo CD 是作為 叢集擴充功能 啟用，讓你能使用 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 建立 AKS 叢集，而不是用服務主體名稱（SPN），才能讓這個擴充功能正常運作。

  • 對於使用 az aks create 建立的新 AKS 叢集，叢集預設採用 MSI。
  • 若要將 SPN 型叢集轉換成 MSI，請執行 az aks update -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-managed-identity。
  • 如需詳細資訊，請參閱 在 AKS 中使用受控識別。

• Microsoft.ContainerService/managedClusters 資源類型的讀取和寫入權限。

兩種叢集類型皆適用

要安裝 Argo CD 擴充功能，你需要 Kubernetes 擴充套件貢獻 者角色。 部署 Argo CD 後，你可以定義 Argo CD 的 RBAC 政策、設定命名空間，並建立管理 Argo CD 行為的應用程式專案。 你也可以給自己 Argo CD 管理員權限。 透過使用 Argo CD 管理員權限，你可以在叢集上任何已設定的命名空間部署和管理應用程式。 實務上，管理員存取所提供的功能實際上等同於叢集管理員的權限。

• 資源類型的讀寫權限： 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
  

• 雖然本教學的原始碼為 Git 倉庫，Argo CD 支援其他常見的檔案來源，如 Helm 與 Open Container Initiative（OCI）倉庫。

版本和區域支援

GitOps 目前在公開區域中獲得支援。

網路需求

GitOps 代理程式需要能夠透過連接埠 22（SSH）或連接埠 443（HTTPS），對儲存庫來源端發起 TCP 輸出（egress）連線，才能運作。 代理人還需要存取以下出站網址：

啟用 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）模式下的多重租戶，並支援工作負載識別。

HA 模式是預設配置，安裝需要叢集中的四個節點。 下列指令會新增 --config "redis-ha.enabled=false"，以在單一節點上安裝此擴充功能。

此指令建立最簡單的組態，將 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> 命名空間，並將 Argo CD 元件安裝於 <namespace>. Argo CD 應用程式定義在此配置中僅在命名空間中運作 <namespace> 。

如需更多設定選項，如資源限制，請參見 values.yaml。 在設定擴充功能時，請在 Azure CLI 指令中使用這些設定。

使用工作負載身分建立 GitOps (Argo CD) 擴充功能

建議用於生產環境的替代安裝方法是 工作負載身分識別。 此方法使用 Microsoft Entra ID 身份來驗證 Azure 資源，因此你不需要管理 Git 儲存庫中的秘密或憑證。 此安裝使用了 Argo CD 3.0.0-rc2 或更新版本 OSS 中啟用的工作負載身份驗證。

HA 模式是預設配置，安裝需要叢集中的四個節點。 用 'redis-ha.enabled': false 來安裝擴充功能在單一節點上。

若要透過工作負載身分識別建立擴充功能，請先將此 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.microsoftonline.com/<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>

如需更多設定選項，如資源限制，請參見 values.yaml。 在設定擴充功能時，請在 Bicep 範本中使用這些設定。

參數

clusterName 是 AKS 或已啟用 Arc 的 Kubernetes 叢集名稱。

workloadIdentityClientId是 Argo CD 元件用於工作負載身分識別的使用者指派受控識別用戶端識別碼。

ssoApplicationClientId是 Microsoft Entra 應用程式註冊的應用程式 (用戶端) 識別碼，用於對 Argo CD UI 的 OIDC SSO 驗證。 欲了解更多關於一般設定與設定ssoApplicationClientId的資訊，請參閱 Microsoft Entra ID 應用程式註冊認證，使用 OIDC 進行驗證。

url 是 Argo CD UI 的公開 IP。 除非叢集已經有客戶提供的入口控制器，否則不會有公用IP或網域名稱。 如果是這樣，部署後你需要在 Argo CD UI 中新增 Ingress 規則。 入口功能需要應用程式 路由附加元件 ，且僅支援 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 介面的權限。 你可以在 Azure 入口網站的 Microsoft Entra ID 群組 >> 屬性中找到 Microsoft Entra >群組 ID。 您可以使用 Microsoft Entra 使用者識別碼，而不是 Microsoft Entra 群組識別符。 你可以在 Azure 入口網站的 Microsoft Entra ID 用戶 >> 屬性中找到 Microsoft Entra > 使用者 ID。

建立工作負載身分識別認證

若要設定新的工作負載身分識別認證，請遵循下列步驟：

1. 擷取 AKS 叢集或啟用 Arc 的 Kubernetes 叢集的 OIDC 簽發者 URL。

2. 建立 受控識別 ，並記下其用戶端標識碼和租用戶標識碼。

3. 為您的 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或映像反映器控制器或argocd-repo-server提取的資源，指派工作負載身分識別的正確權限。 例如，如果您使用 Azure Container Registry，請確保已套用 （適用於 AcrPull）或 Container Registry Repository Reader（適用於未啟用 ABAC 的登錄）。

使用工作負載身分識別連線到私人 ACR 登錄或 ACR 存放庫

若要使用私人 ACR 登錄檔或 ACR 儲存庫，請依官方 Argo CD 文件中的指示 連接私人 ACR 登錄檔。 該指南中的為 Pod 加上標籤、建立同盟身分識別認證以及為 Service Account 新增註解等步驟，已由擴充功能透過 Bicep 部署完成，因此可略過。

從 Argo CD OSS 遷移到受管理的 Argo CD 擴充套件

請使用以下步驟，從自管理的 Argo CD 安裝遷移到 Azure 管理的 Argo CD 擴充功能。

遷移路徑

請使用以下序列以避免控制器衝突並降低遷移風險。

1. 檢視您目前的Argo CD配置與庫存：

   • 應用程式
   • 應用程式集
   • 應用程式專案
   • 儲存庫憑證與範本（repocreds）
   • 叢集密鑰

2. 將自我管理的 Argo CD 控制器縮放到零副本，以防止雙控制器行為。

3. 在叢集上安裝 Argo CD 擴充功能，使用與你現有部署相符的設定。

4. 「任何命名空間中的應用程式」功能允許 Argo CD 管理位於核心命名空間之外的資源。 如果你的叢集已經使用這個設定，你不需要把資源移到新的命名空間。 你只需要設定新的擴充功能來監控現有應用程式的命名空間。

   案例 A：如果您已經使用任何命名空間中的應用程式功能：

   1. 將所有 Application、ApplicationSet 和 AppProject 資源留在目前的命名空間中。
   2. 設定新的受管理擴充功能，透過擴充套件的設定監控這些外部命名空間。

   情況 B：如果你將資源移到新的擴充命名空間：

   • 如有需要，將應用程式、應用集與應用程式專案遷移至副名空間。

5. 將儲存庫憑證、叢集秘密和 repocreds 遷移到擴充名稱空間。

6. 驗證應用程式是否同步並達到預期的健康狀態。

7. 完成驗證後，移除舊的自行管理的 Argo CD 部署。

受管理擴充功能使用相同的 Argo CD API 和自訂資源定義（CRD），因此你可以以最小改動重用大多數現有清單。

目前的限制

• 不支援直接對 Argo CD ConfigMaps 進行更新。
• 使用擴充功能組態 API 和設定來套用 Argo CD 組態變更。

使用 Azure Managed Prometheus 和 Azure 受控 Grafana 設定監視

你可以將 Argo CD 的度量發佈到 Azure Managed Prometheus，並在 Azure 受控 Grafana 中視覺化。

1. 為你的叢集啟用 Azure Managed Prometheus。 請參閱 為 Azure Kubernetes Service (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 dashboard 14584 匯入 Azure 受控 Grafana 實例。

4. 如果面板顯示無資料，請更新面板查詢以考慮 Azure Managed Prometheus 的工作命名。

5. 在控制器遙測面板 (記憶體使用量、CPU 使用量、Goroutines) 中，變更：

   • 從 job="argocd-metrics"
   • 至 job=~"argocd.*-metrics"

6. 在 repo-server 面板（已用記憶體、Goroutines）中，將下列內容變更為：

   • 從 job="argocd-repo-server"
   • 至 job="argocd-repo-server-metrics"

7. 儲存儀表板並驗證指標的匯入。

在 Azure 入口網站中啟用 Argo CD

你可以在 Azure 入口網站啟用 Argo CD，查看應用程式狀態和同步狀態，並進入 Argo CD 的介面。 要在 Azure 入口網站啟用 Argo CD，請遵循以下步驟：

1. 前往 Azure 入口網站中的您的叢集。

2. 從服務功能表中的 [ 設定] 底下，選取 [GitOps]。

3. 選擇啟用 Argo CD（預覽）。

4. 在 [基本] 區段中：

   1. 設定 Argo CD 執行的命名空間。 預設的命名空間為 argocd。
   2. 如有需要，啟用 Redis 高可用性（HA）。 此選項需要叢集中至少有四個節點。
   3. 可選擇性地新增任何需要觀察的命名空間。
   4. 僅限 AKS 叢集，可選擇啟用單一登入（SSO），讓使用者能使用 Microsoft Entra ID 登入，指定應用程式及一個或多個群組以存取 Argo CD 介面。
   5. 如果需要，啟用 workload identity，讓 Argo CD 能安全存取 Azure 服務，且不儲存秘密。 要做到這點，請選擇啟用工作負載身份（Enable Workload Identity）框，並指定一個管理身份和一個 Azure Container Registry，從中拉取應用程式清單或容器產物。

   

5. 選取 下一步 以繼續。

6. 對於啟用 應用程式路由外掛的 AKS 叢集， Ingress 標籤可以讓你建立一個 Ingress 資源來路由流量到服務。 如果需要，選擇 啟用 Ingress ，並輸入你的 Ingress 名稱、憑證細節和網域名稱。 選取 下一步 以繼續。

7. 在 檢視 + 部署 區塊，檢視你的設定，然後選擇 部署 以啟用叢集上的 Argo CD。

存取Argo CD介面

如果 AKS 叢集沒有現有的入口控制器，你可以直接透過 LoadBalancer 服務暴露 Argo CD 介面。 以下指令會顯示 Argo CD 在 80 和 443 埠的介面。

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

要從 Azure 入口網站存取 Argo CD 的介面，請前往你的叢集。 在服務功能表的設定下，選取 GitOps。 接著，選擇顯示的 Argo CD 介面連結。

部署 Argo CD 應用程式

安裝 Argo CD 擴充功能後，你可以使用 Argo CD 介面或 CLI 來部署應用程式。 以下範例使用 kubectl apply，在 argocd 命名空間中將 AKS Store 部署到 Argo CD 應用程式的預設 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 平台工程程式碼範例，該範例部署 OSS Argo CD，並整合了 Backstage 以及適用於 Azure 的 Cluster API Provider (CAPZ) 或 Crossplane。