教學課程：使用 GitOps 搭配 ArgoCD 部署應用程式

本教學課程說明如何在 Kubernetes 叢集中使用 GitOps。在 Azure Arc 已啟用的 Kubernetes 叢集或 Azure Kubernetes Service （AKS）叢集內，ArgoCD 的 GitOps 作為叢集擴充功能被啟用。搭配 GitOps，可讓您使用 Git 存放庫做為叢集設定和應用程式部署的事實來源。

這很重要

GitOps with ArgoCD 目前為預覽狀態。如需適用於 Beta、預覽版或尚未發行至正式運作的 Azure 功能的法律條款，請參閱 Microsoft 適用於 azure 預覽版的補充使用規定。若要在生產環境中使用 GitOps 擴充功能並獲得支援，請嘗試使用 Flux 的 GitOps 擴充功能。

小提示

雖然本教學課程中的來源是 Git 存放庫，但 ArgoCD 支援其他常見的檔案來源，例如 Helm 和 Open Container Initiative （OCI）存放庫。

先決條件

若要使用 GitOps 部署應用程式，您需要已啟用 Azure Arc 的 Kubernetes 叢集或 AKS 叢集：

已啟用 Azure Arc 的 Kubernetes 叢集

已啟用 Azure Arc 的 Kubernetes 已連線叢集已啟動並執行。

瞭解如何將 Kubernetes 叢集連線至 Azure Arc。如果您需要透過輸出 Proxy 進行連線，請確定您使用 Proxy 設定來安裝 Arc 代理程式。
Microsoft.Kubernetes/connectedClusters 資源類型的讀取和寫入權限。

Azure Kubernetes Service 叢集

MSI 型 AKS 叢集已啟動並執行。

這很重要

AKS 叢集必須使用受控服務識別（MSI），而非服務主體名稱（SPN）建立，此延伸模組才能運作。針對使用 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。如果您使用 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

版本和區域支援

目前，所有支援 Azure Arc 的 Kubernetes 的區域都支援 GitOps。 AKS 所支援的區域子集目前支援 GitOps。 GitOps 服務會定期新增支援的區域。

網路需求

GitOps 代理程式需要連接埠 22 (SSH) 或連接埠 443 (HTTPS) 上存放庫來源的輸出 TCP 才能運作。代理程式也需要存取下列輸出 URL:

端點 (DNS)	說明
`https://management.azure.com`	代理程式與 Kubernetes 設定服務通訊的必要項目。
`https://<region>.dp.kubernetesconfiguration.azure.com`	代理程式的資料平面端點，用來推送狀態以及擷取設定資訊。取決於 `<region>` (先前提及的支援區域)。
`https://login.microsoftonline.com`	必須擷取和更新 Azure Resource Manager 憑證。
`https://mcr.microsoft.com`	需要下載控制器的容器映像。

啟用 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 安裝支援高可用性（HA）模式的多租戶，並支援工作負載身份。

這很重要

HA 模式是預設組態，需要叢集中的三個節點才能安裝。下列命令會新增 --config deployWithHighAvailability=false ，以在單一節點上安裝擴充功能。

此命令會建立最簡單的設定，以將 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 deployWithHighAvailability=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> 運作。

使用工作負載身分識別建立 GitOps （ArgoCD）擴充功能

建議用於生產環境的替代安裝方法是工作負載身分識別。此方法可讓您使用 Microsoft Entra ID 身分識別向 Azure 資源進行驗證，而不需要管理 Git 存放庫中的秘密或認證。此安裝使用在 3.0.0-rc2 或更新版本的 ArgoCD 中啟用的工作負載身份驗證功能。

這很重要

HA 模式是預設組態，需要叢集中的三個節點才能安裝。新增 --config deployWithHighAvailability=false 以在單一節點上安裝擴充功能。

若要透過工作負載身分識別建立擴充功能，請先將此 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.microsoftonline.com/<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: {
      'workloadIdentity.enable': 'true'
      'workloadIdentity.clientId': workloadIdentityClientId
      'workloadIdentity.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 是想要用於工作負載身分識別之受控識別的用戶端標識碼。 ssoWorkloadIdentityClientId 用於 ArgoCD UI 的驗證，而 workloadIdentityClientId 則用於 ArgoCD 元件的工作負載身分識別。如需有關 ssoWorkloadIdentityClientId 的一般設定和其他資訊，請造訪 Microsoft Entra ID 應用程式註冊使用 OIDC 的驗證。

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 群組標識碼。您可以在 Azure 平台的 Microsoft Entra ID > 群組 >your-group-name> 屬性 底下找到 Microsoft Entra 群組 ID。您可以使用 Microsoft Entra 使用者識別碼，而不是 Microsoft Entra 群組識別符。 Microsoft Entra 使用者標識符可在 Azure 入口網站中，於 [Microsoft Entra ID > Users >your-user-name> 屬性] 底下找到。

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

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

取得 AKS 叢集或已啟用 Arc 的 Kubernetes 叢集的 OIDC 簽發者 URL。
建立受控識別，並記下其用戶端標識碼和租用戶標識碼。

為您的 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

請務必為您想要 source-controller 或image-reflector 控制器提取的資源提供適當的工作負載身分識別權限。例如，如果使用 Azure Container Registry，請確定 Container Registry Repository Reader 已套用 [ 已啟用 ABAC 的登錄] 或 AcrPull [適用於非 ABAC 登錄]。

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

若要使用私人 ACR 登錄或 ACR 存放庫，請遵循官方 ArgoCD 檔中的指示，連線到私人 ACR 登錄。 卷標 Pod、建立同盟身分識別憑證，以及新增批註至服務帳戶的步驟已由擴充功能完成，且可以略過。

進入 ArgoCD 使用者介面

如果 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 "config-maps.argocd-cm.data.url='https://<public-ip-for-argocd-ui>/auth/callback'”

為了避免設定被覆寫，請務必透過擴充功能來更新 ArgoCD configmap。套用 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 的 Cluster API 提供程序 (CAPZ) 或 Crossplane 來部署 OSS ArgoCD。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-06

共用方式為

教學課程：使用 GitOps 搭配 ArgoCD 部署應用程式

先決條件

已啟用 Azure Arc 的 Kubernetes 叢集

Azure Kubernetes Service 叢集

常見於這兩種叢集類型

版本和區域支援

網路需求

啟用 CLI 延伸模組

建立 GitOps （ArgoCD） 延伸模組 （簡單安裝）

使用工作負載身分識別建立 GitOps （ArgoCD） 擴充功能

參數

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

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

進入 ArgoCD 使用者介面

部署ArgoCD應用程式

更新延伸模組設定

刪除延伸模組

後續步驟

意見反應

其他資源

建立 GitOps （ArgoCD）延伸模組（簡單安裝）

使用工作負載身分識別建立 GitOps （ArgoCD）擴充功能