ArgoCD 安装与 Application 配置

核心问题：怎样在集群中安装 ArgoCD，并配置它持续同步 Git 仓库中的应用配置？

安装 ArgoCD

# 方式 1：官方 YAML（快速开始）
kubectl create namespace argocd
kubectl apply -n argocd -f \
https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# 方式 2：Helm（推荐，可以 values 定制）
helm repo add argo https://argoproj.github.io/argo-helm
helm upgrade --install argocd argo/argo-cd \
--namespace argocd \
--create-namespace \
--version "5.51.0" \
-f argocd-values.yaml \
--wait

# argocd-values.yaml（生产配置示例）
server:
replicas: 2
ingress:
enabled: true
ingressClassName: nginx
hostname: argocd.example.com
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
tls: true
repoServer:
replicas: 2
configs:
params:
server.insecure: false           # 强制 HTTPS
application.namespaces: "*"      # 允许在任意 Namespace 创建 App
rbac:
policy.default: role:readonly    # 默认只读
policy.csv: |
p, role:admin, applications, *, */*, allow
p, role:admin, clusters, *, *, allow
g, argocd-admins, role:admin
redis-ha:
enabled: true    # 高可用 Redis

初始化

# 获取初始密码
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d
# 本地访问 UI
kubectl port-forward svc/argocd-server -n argocd 8080:443
# 访问 https://localhost:8080，用户名 admin
# 安装 argocd CLI
brew install argocd           # macOS
# 或从 GitHub Releases 下载 Linux 版本
# CLI 登录
argocd login argocd.example.com \
--username admin \
--password <initial-password> \
--grpc-web

Application：核心资源

Application 是 ArgoCD 的核心 CRD，定义"从哪个 Git 仓库同步到哪个 K8s 集群的哪个 Namespace"：

# application.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-api-production
namespace: argocd              # Application 本身部署在 argocd 命名空间
finalizers:
- resources-finalizer.argocd.argoproj.io  # 删除 App 时级联删除集群资源
spec:
project: default               # ArgoCD Project（权限隔离单元）
# 源：从哪里拉取配置
source:
repoURL: https://github.com/myorg/infra-repo.git
targetRevision: main          # 分支、tag 或 commit hash
path: apps/api/overlays/production   # 仓库内路径（Kustomize 或 Helm）
# 目标：部署到哪个集群和命名空间
destination:
server: https://kubernetes.default.svc   # 本集群
namespace: production
# 同步策略
syncPolicy:
automated:
prune: true          # 删除 Git 中已不存在的资源
selfHeal: true       # 检测到漂移自动恢复
allowEmpty: false    # 不允许同步空配置（防误删）
syncOptions:
- CreateNamespace=true         # 自动创建目标 Namespace
- PrunePropagationPolicy=foreground
- ApplyOutOfSyncOnly=true      # 只 apply 有差异的资源
retry:
limit: 5              # 失败后重试次数
backoff:
duration: 5s
factor: 2
maxDuration: 3m

Helm 源配置

spec:
source:
repoURL: https://charts.bitnami.com/bitnami
chart: postgresql
targetRevision: "13.2.0"
helm:
releaseName: postgres-prod
valueFiles:
- values/prod.yaml
values: |
auth:
postgresPassword: "{{ .Values.db.password }}"
parameters:
- name: primary.replicaCount
value: "1"

AppProject：权限隔离

AppProject 控制应用能部署到哪些集群/命名空间，能拉取哪些仓库：

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-api
namespace: argocd
spec:
description: API 团队项目
# 允许的源仓库
sourceRepos:
- https://github.com/myorg/infra-repo.git
- https://charts.bitnami.com/bitnami
# 允许部署的目标
destinations:
- namespace: production
server: https://kubernetes.default.svc
- namespace: staging
server: https://kubernetes.default.svc
# 禁止使用集群级资源（Namespace、ClusterRole 等）
clusterResourceWhitelist:
- group: ""
kind: Namespace    # 只允许创建 Namespace
# RBAC
roles:
- name: developer
description: 开发者：只读 + 同步权限
policies:
- p, proj:team-api:developer, applications, get, team-api/*, allow
- p, proj:team-api:developer, applications, sync, team-api/*, allow
groups:
- github-org:team-api-developers

连接私有 Git 仓库

# SSH 密钥方式
argocd repo add git@github.com:myorg/infra-repo.git \
--ssh-private-key-path ~/.ssh/id_rsa_argocd \
--name infra-repo
# HTTPS + Token 方式
argocd repo add https://github.com/myorg/infra-repo.git \
--username oauth2 \
--password ghp_xxxxxxxxxxxx
# 通过 Secret 方式（Infrastructure as Code）
kubectl create secret generic argocd-github-creds \
-n argocd \
--from-literal=url=https://github.com/myorg/infra-repo.git \
--from-literal=username=oauth2 \
--from-literal=password=ghp_xxxxxxxxxxxx
kubectl label secret argocd-github-creds \
argocd.argoproj.io/secret-type=repository \
-n argocd

argocd CLI 常用命令

# 查看所有应用
argocd app list
# 查看应用状态
argocd app get my-api-production
# 手动触发同步
argocd app sync my-api-production
# 等待同步完成（CI 中使用）
argocd app wait my-api-production --health --timeout 300
# 回滚（切换到指定 Git 版本）
argocd app rollback my-api-production <HISTORY_ID>
# 查看同步历史
argocd app history my-api-production
# 强制刷新（重新从 Git 拉取，清除缓存）
argocd app get my-api-production --refresh

在 CI 中触发 ArgoCD 同步

# .github/workflows/deploy.yml
- name: 更新 infra-repo 中的镜像 tag
run: |
cd infra-repo
# 使用 kustomize 更新 image tag
cd apps/api/overlays/production
kustomize edit set image myorg/api=myorg/api:${{ github.sha }}
git add .
git commit -m "ci: deploy api ${{ github.sha }} to production"
git push
- name: 等待 ArgoCD 同步完成
env:
ARGOCD_SERVER: argocd.example.com
ARGOCD_AUTH_TOKEN: ${{ secrets.ARGOCD_TOKEN }}
run: |
argocd app wait my-api-production \
--health \
--timeout 300 \
--server $ARGOCD_SERVER \
--auth-token $ARGOCD_AUTH_TOKEN \
--grpc-web

常见错误

下一节：多集群 GitOps 策略