argocd-gitops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ArgoCD GitOps

Implement declarative continuous delivery for Kubernetes with ArgoCD.

使用ArgoCD为Kubernetes实现声明式持续交付。

When to Use This Skill

何时使用此技能

Use this skill when:

Implementing GitOps workflows for Kubernetes
Automating deployments from Git repositories
Managing multiple environments declaratively
Implementing progressive delivery strategies
Synchronizing cluster state with Git

在以下场景使用此技能：

为Kubernetes实现GitOps工作流
从Git仓库自动化部署
以声明式方式管理多环境
实现渐进式交付策略
同步集群状态与Git

Prerequisites

前提条件

Kubernetes cluster with ArgoCD installed
kubectl configured
Git repository for manifests
ArgoCD CLI (optional)

已安装ArgoCD的Kubernetes集群
已配置kubectl
用于存储清单的Git仓库
ArgoCD CLI（可选）

Installation

安装步骤

bash

undefined

bash

undefined

Create namespace

kubectl create namespace argocd

Install ArgoCD

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Get admin password

kubectl -n argocd get secret argocd-initial-admin-secret
-o jsonpath="{.data.password}" | base64 -d

Port forward to access UI

kubectl port-forward svc/argocd-server -n argocd 8080:443

Login with CLI

argocd login localhost:8080

undefined

argocd login localhost:8080

undefined

Application Definition

应用定义

Basic Application

基础应用

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/myapp-manifests.git
    targetRevision: main
    path: environments/production
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/myapp-manifests.git
    targetRevision: main
    path: environments/production
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Helm Application

Helm应用

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp-helm
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/myapp-chart.git
    targetRevision: main
    path: charts/myapp
    helm:
      valueFiles:
        - values.yaml
        - values-production.yaml
      parameters:
        - name: replicaCount
          value: "3"
        - name: image.tag
          value: "2.0.0"
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp-helm
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/myapp-chart.git
    targetRevision: main
    path: charts/myapp
    helm:
      valueFiles:
        - values.yaml
        - values-production.yaml
      parameters:
        - name: replicaCount
          value: "3"
        - name: image.tag
          value: "2.0.0"
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Kustomize Application

Kustomize应用

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp-kustomize
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/myapp-manifests.git
    targetRevision: main
    path: overlays/production
    kustomize:
      images:
        - myapp=myregistry/myapp:2.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp-kustomize
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/myapp-manifests.git
    targetRevision: main
    path: overlays/production
    kustomize:
      images:
        - myapp=myregistry/myapp:2.0.0
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp

Projects

项目

yaml

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: myproject
  namespace: argocd
spec:
  description: My Project
  sourceRepos:
    - https://github.com/org/*
  destinations:
    - namespace: myapp-*
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  namespaceResourceWhitelist:
    - group: '*'
      kind: '*'
  roles:
    - name: developer
      description: Developer role
      policies:
        - p, proj:myproject:developer, applications, get, myproject/*, allow
        - p, proj:myproject:developer, applications, sync, myproject/*, allow
      groups:
        - developers

yaml

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: myproject
  namespace: argocd
spec:
  description: My Project
  sourceRepos:
    - https://github.com/org/*
  destinations:
    - namespace: myapp-*
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  namespaceResourceWhitelist:
    - group: '*'
      kind: '*'
  roles:
    - name: developer
      description: Developer role
      policies:
        - p, proj:myproject:developer, applications, get, myproject/*, allow
        - p, proj:myproject:developer, applications, sync, myproject/*, allow
      groups:
        - developers

Application Sets

应用集合（Application Sets）

Git Generator

Git生成器

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-environments
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/org/myapp-manifests.git
        revision: main
        directories:
          - path: environments/*
  template:
    metadata:
      name: 'myapp-{{path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/myapp-manifests.git
        targetRevision: main
        path: '{{path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: 'myapp-{{path.basename}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-environments
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/org/myapp-manifests.git
        revision: main
        directories:
          - path: environments/*
  template:
    metadata:
      name: 'myapp-{{path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/myapp-manifests.git
        targetRevision: main
        path: '{{path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: 'myapp-{{path.basename}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

List Generator

列表生成器

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-clusters
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - cluster: production
            url: https://prod-cluster.example.com
          - cluster: staging
            url: https://staging-cluster.example.com
  template:
    metadata:
      name: 'myapp-{{cluster}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/myapp-manifests.git
        targetRevision: main
        path: 'environments/{{cluster}}'
      destination:
        server: '{{url}}'
        namespace: myapp

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-clusters
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - cluster: production
            url: https://prod-cluster.example.com
          - cluster: staging
            url: https://staging-cluster.example.com
  template:
    metadata:
      name: 'myapp-{{cluster}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/myapp-manifests.git
        targetRevision: main
        path: 'environments/{{cluster}}'
      destination:
        server: '{{url}}'
        namespace: myapp

Matrix Generator

矩阵生成器

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-matrix
  namespace: argocd
spec:
  generators:
    - matrix:
        generators:
          - git:
              repoURL: https://github.com/org/myapp-manifests.git
              revision: main
              directories:
                - path: apps/*
          - list:
              elements:
                - env: staging
                - env: production
  template:
    metadata:
      name: '{{path.basename}}-{{env}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/myapp-manifests.git
        targetRevision: main
        path: '{{path}}/overlays/{{env}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{path.basename}}-{{env}}'

yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-matrix
  namespace: argocd
spec:
  generators:
    - matrix:
        generators:
          - git:
              repoURL: https://github.com/org/myapp-manifests.git
              revision: main
              directories:
                - path: apps/*
          - list:
              elements:
                - env: staging
                - env: production
  template:
    metadata:
      name: '{{path.basename}}-{{env}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/org/myapp-manifests.git
        targetRevision: main
        path: '{{path}}/overlays/{{env}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{path.basename}}-{{env}}'

Sync Policies

同步策略

Automated Sync

自动同步

yaml

syncPolicy:
  automated:
    prune: true          # Delete resources not in Git
    selfHeal: true       # Revert manual changes
    allowEmpty: false    # Don't sync empty directories
  syncOptions:
    - CreateNamespace=true
    - PrunePropagationPolicy=foreground
    - PruneLast=true
  retry:
    limit: 5
    backoff:
      duration: 5s
      factor: 2
      maxDuration: 3m

yaml

syncPolicy:
  automated:
    prune: true          # Delete resources not in Git
    selfHeal: true       # Revert manual changes
    allowEmpty: false    # Don't sync empty directories
  syncOptions:
    - CreateNamespace=true
    - PrunePropagationPolicy=foreground
    - PruneLast=true
  retry:
    limit: 5
    backoff:
      duration: 5s
      factor: 2
      maxDuration: 3m

Sync Waves

同步波

yaml

undefined

yaml

undefined

In Kubernetes manifests

apiVersion: v1 kind: ConfigMap metadata: name: myconfig annotations: argocd.argoproj.io/sync-wave: "-1" # Sync first

apiVersion: apps/v1 kind: Deployment metadata: name: myapp annotations: argocd.argoproj.io/sync-wave: "0" # Sync second

undefined

apiVersion: v1 kind: ConfigMap metadata: name: myconfig annotations: argocd.argoproj.io/sync-wave: "-1" # Sync first

apiVersion: apps/v1 kind: Deployment metadata: name: myapp annotations: argocd.argoproj.io/sync-wave: "0" # Sync second

undefined

Sync Hooks

同步钩子

yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: myapp:latest
          command: ["./migrate.sh"]
      restartPolicy: Never

yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: myapp:latest
          command: ["./migrate.sh"]
      restartPolicy: Never

CLI Commands

CLI命令

bash

undefined

bash

undefined

List applications

argocd app list

Get application details

argocd app get myapp

Sync application

argocd app sync myapp

Force sync (ignore differences)

argocd app sync myapp --force

View diff

argocd app diff myapp

Rollback

argocd app rollback myapp

Delete application

argocd app delete myapp

View logs

argocd app logs myapp

Hard refresh (clear cache)

argocd app get myapp --hard-refresh

undefined

argocd app get myapp --hard-refresh

undefined

Repository Configuration

仓库配置

yaml

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  url: https://github.com/org/private-repo.git
  username: git
  password: ghp_xxxx
---

yaml

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  url: https://github.com/org/private-repo.git
  username: git
  password: ghp_xxxx
---

SSH key

apiVersion: v1 kind: Secret metadata: name: private-repo-ssh namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: url: git@github.com:org/private-repo.git sshPrivateKey: | -----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY-----

undefined

undefined

Notifications

通知配置

yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  service.slack: |
    token: $slack-token
  template.app-deployed: |
    message: Application {{.app.metadata.name}} is now {{.app.status.sync.status}}.
  trigger.on-deployed: |
    - when: app.status.operationState.phase in ['Succeeded']
      send: [app-deployed]

yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  service.slack: |
    token: $slack-token
  template.app-deployed: |
    message: Application {{.app.metadata.name}} is now {{.app.status.sync.status}}.
  trigger.on-deployed: |
    - when: app.status.operationState.phase in ['Succeeded']
      send: [app-deployed]

Common Issues

常见问题

Issue: Sync Fails with Diff

问题：同步因差异失败

Problem: Resources show differences but are correct Solution: Configure ignore differences

yaml

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas

问题：资源显示差异但实际配置正确 解决方案：配置忽略差异

yaml

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas

Issue: Repository Not Accessible

问题：仓库无法访问

Problem: ArgoCD cannot clone repository Solution: Check repository secret, verify URL and credentials

问题：ArgoCD无法克隆仓库 解决方案：检查仓库密钥，验证URL和凭据

Issue: Application Stuck OutOfSync

问题：应用一直处于OutOfSync状态

Problem: Application never becomes synced Solution: Check resource status, review events, verify manifests

问题：应用始终无法完成同步 解决方案：检查资源状态，查看事件日志，验证清单内容

Issue: Health Check Failing

问题：健康检查失败

Problem: Application shows degraded health Solution: Check custom health checks, verify probe configurations

问题：应用显示健康状态降级 解决方案：检查自定义健康检查配置，验证探针设置

Best Practices

最佳实践

Use ApplicationSets for multi-environment deployments
Implement sync waves for ordered deployments
Use projects to isolate applications
Configure notifications for deployment events
Implement proper RBAC with projects
Use health checks for deployment verification
Enable auto-pruning to remove deleted resources
Keep manifests in dedicated repositories

使用ApplicationSets进行多环境部署
实现同步波来控制部署顺序
使用项目隔离不同应用
为部署事件配置通知
通过项目实现适当的RBAC权限控制
使用健康检查验证部署状态
启用自动清理来移除已删除的资源
将清单存储在专用仓库中