DevOps全链路实战 | 第 8 天：Argo CD 部署与 GitOps 配置仓库创建

第 8/18 天

引言：从”推式部署”到”拉式同步”的范式转变

在前七天的实战中，我们依次完成了 K8s 集群搭建、Harbor 私有镜像仓库部署、GitLab CE 自托管、GitLab Runner 配置、CI 流水线搭建以及 Harbor 镜像版本管理。至此，持续集成（CI） 侧的管道已经打通——代码提交后会自动触发 Kaniko 构建并推送到 Harbor。但一个完整的 DevOps 管道还需要 持续交付（CD） 这一环：如何把 Harbor 里的新镜像安全、可追溯、可回滚地发布到 K8s 集群？

传统的做法是在 CI 流水线末尾直接 kubectl apply 或调用 Helm 部署，这属于”推式（Push）部署”。它的痛点在于：部署状态分散在各个流水线日志里、谁在什么时候改了什么资源难以审计、回滚靠记忆和手工操作。GitOps 则把 Git 仓库作为基础设施和应用配置的”唯一事实来源”（Single Source of Truth），由集群内的控制器持续”拉取” Git 仓库的声明式配置并与集群实际状态对账，任何差异都会被自动纠正或告警。

今天我们要部署的 Argo CD，就是 CNCF 毕业项目中最主流的 GitOps 控制器之一。本篇将完成 Argo CD 的安装、CLI 配置、Web UI 访问，以及 GitOps 配置仓库的创建与首次应用同步，为后续 CI/CD 联动打好基础。

核心概念：Argo CD 与 GitOps 工作模型

什么是 GitOps

GitOps 由 Weaveworks 在 2017 年提出，其四大核心原则是：

声明式描述：整个系统的期望状态以声明式（YAML/Helm/Kustomize）描述，而非过程式脚本。
版本控制且变更审计：所有配置存储在 Git 仓库，每次变更都有 commit 记录，可追溯、可审查、可回滚。
自动拉取并应用：集群内的控制器主动拉取 Git 仓库的变更并应用到集群，而非外部 CI 系统推送。
持续对账与告警：控制器持续比较 Git 期望状态与集群实际状态（即 Drift Detection），出现偏差时自动纠正或发出告警。

Argo CD 架构简介

Argo CD 是一个专为 Kubernetes 设计的 GitOps 持续交付工具，其核心架构包括：

API Server：提供 gRPC/REST API，供 Web UI 和 CLI 交互。
Repository Server：内部服务，负责克隆 Git 仓库并缓存配置文件，生成渲染后的清单。
Application Controller：核心对账引擎，定期比较 Git 中的期望状态与集群中的实际状态，并触发 Sync 操作。
Redis：缓存服务，加速状态查询。
Dex（可选）：身份认证中间件，支持 SSO 集成。

GitOps 仓库的三种主流结构

结构	说明	适用场景
单仓库单环境	所有配置在一个仓库，按目录区分环境	小团队、单一集群
单仓库多环境	一个仓库内 `dev/`、`staging/`、`prod/` 分目录	中等规模，多环境
应用仓库 + 配置仓库分离	应用源码在 A 仓库，部署清单在 B 仓库	生产级，职责分离

本系列采用 应用仓库 + 配置仓库分离 模式，配置仓库即 GitOps 仓库。

实战步骤：Argo CD 部署与配置仓库创建

步骤一：创建 GitOps 配置仓库

在 GitLab 中新建一个名为 gitops-manifests 的仓库，作为 Argo CD 的配置来源。该仓库将存放所有应用的 K8s 声明式清单。

💻 代码示例

# 在 GitLab Web UI 创建空仓库 gitops-manifests 后，克隆到本地

git clone git@gitlab.stellardata.top:devops/gitops-manifests.git

cd gitops-manifests

# 创建目录结构，按环境 + 应用组织

mkdir -p apps/guestbook/dev

mkdir -p apps/guestbook/prod

mkdir -p projects

# 初始化 README

cat > README.md << 'EOF'

# GitOps 配置仓库

本仓库作为 Argo CD 的 Single Source of Truth，

存放所有应用的 Kubernetes 声明式清单。

## 目录结构

– apps/<app-name>/<env>/ 按应用和环境划分的部署清单

– projects/ Argo CD AppProject 定义

EOF

git add . && git commit -m "init: gitops-manifests 仓库初始化"

git push origin main

步骤二：准备示例应用清单

在配置仓库中放入一个简单的示例应用，用于验证 Argo CD 的同步能力：

💻 代码示例

# apps/guestbook/dev/deployment.yaml

apiVersion: apps/v1

kind: Deployment

metadata:

namespace: dev

labels:

app: guestboy

spec:

replicas: 2

selector:

matchLabels:

app: guestboy

template:

metadata:

labels:

app: guestboy

spec:

containers:

– name: guestboy

image: harbor.stellardata.top/library/guestboy:v1.0.0

ports:

– containerPort: 3000

resources:

requests:

cpu: 100m

memory: 128Mi

limits:

cpu: 250m

memory: 256Mi

—

apiVersion: v1

kind: Service

metadata:

namespace: dev

spec:

selector:

app: guestboy

ports:

– port: 80

targetPort: 3000

type: ClusterIP

💻 代码示例

# apps/guestbook/dev/namespace.yaml

apiVersion: v1

kind: Namespace

metadata:

labels:

managed-by: argocd

💻 代码示例

git add . && git commit -m "feat: 添加 guestboy dev 环境部署清单"

git push origin main

步骤三：安装 Argo CD

Argo CD 官方提供命名空间安装方式。我们将其部署到 argocd 命名空间：

💻 代码示例

# 创建命名空间

kubectl create namespace argocd

# 使用官方 Helm Chart 安装（推荐生产环境使用 Helm 管理配置）

helm repo add argo https://argoproj.github.io/argo-helm

helm repo update

helm install argocd argo/argo-cd

–namespace argocd

–version 7.7.0

–set server.service.type=NodePort

–set server.service.nodePortHttp=30080

–set configs.cm.application.instanceLabelKey=argocd.argoproj.io/instance

–set server.extensions.enabled=true

# 查看 Pod 状态，等待全部 Running

kubectl get pods -n argocd -w

# 输出示例：

# NAME READY STATUS RESTARTS AGE

# argocd-application-controller-0 1/1 Running 0 90s

# argocd-redis-xxxx 1/1 Running 0 90s

# argocd-repo-server-xxxx 1/1 Running 0 90s

# argocd-server-xxxx 1/1 Running 0 90s

安装完成后，获取初始管理员密码：

💻 代码示例

# Argo CD 1.9+ 使用 Secret 存储初始密码

kubectl -n argocd get secret argocd-initial-admin-secret

-o jsonpath="{.data.password}" | base64 -d ; echo

# 输出示例：AbCdEf123456

步骤四：安装 Argo CD CLI 并登录

💻 代码示例

# 下载 Argo CD CLI（Linux amd64）

curl -sSL -o /usr/local/bin/argocd

https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64

chmod +x /usr/local/bin/argocd

# 验证版本

argocd version

# 登录 Argo CD（admin / 上一步获取的密码）

argocd login localhost:30080

–username admin

–password AbCdEf123456

–insecure

# 出现 "admin logged in successfully" 即成功

# 修改默认密码（生产环境必须修改）

argocd account update-password

–current-password AbCdEf123456

–new-password 'YourStrong#Pass2026'

步骤五：通过 CLI 创建第一个 Argo CD Application

Argo CD Application 是核心 CRD，它定义了”从哪个 Git 仓库的哪个目录，同步到哪个集群命名空间”。

💻 代码示例

# argocd-guestboy-app.yaml

apiVersion: argoproj.io/v1alpha1

kind: Application

metadata:

namespace: argocd

finalizers:

– resources-finalizer.argocd.argoproj.io

spec:

project: default

source:

repoURL: git@gitlab.stellardata.top:devops/gitops-manifests.git

targetRevision: main

path: apps/guestboy/dev

destination:

server: https://kubernetes.default.svc

namespace: dev

syncPolicy:

automated:

prune: true # Git 中删除资源时自动从集群中删除

selfHeal: true # 检测到 Drift 时自动恢复到 Git 期望状态

syncOptions:

– CreateNamespace=true # 目标命名空间不存在时自动创建

💻 代码示例

# 应用 Application 资源

kubectl apply -f argocd-guestboy-app.yaml -n argocd

# 查看 Application 状态

argocd app get guestboy-dev

# 关键字段：

# Health Status: Healthy

# Sync Status: Synced

# 对应的 Deployment、Service 资源已在 dev 命名空间创建

# 查看集群实际资源

kubectl get all -n dev

步骤六：通过 Web UI 验证同步效果

Argo CD 的 Web UI 提供了直观的可视化拓扑，能清晰展示应用资源的层级关系和健康状态。

💻 代码示例

# 端口转发访问 Web UI（本地访问）

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

# 浏览器访问 https://localhost:8080

# 使用 admin 账号登录后可看到：

# 1. guestboy-dev 应用卡片

# 2. 资源拓扑树（Deployment → ReplicaSet → Pod）

# 3. Sync 状态为 Synced，Health 状态为 Healthy

在 Web UI 中点击 guestboy-dev，可以展开资源树查看每个资源的实时状态。绿色表示健康，黄色表示进行中，红色表示异常。这种可视化对排障极其友好——当某个 Pod 起不来时，UI 会直接标红并提示原因。

步骤七：验证 GitOps 自动对账能力

GitOps 的核心价值在于”声明即真相”。我们来测试 selfHeal 自动纠正能力：

💻 代码示例

# 手动修改集群中的副本数（模拟人工误操作）

kubectl scale deployment guestboy -n dev –replicas=5

# 几秒内 Argo CD 检测到 Drift，自动回滚到 Git 中声明的 replicas:2

kubectl get deployment guestboy -n dev -w

# 查看同步事件

argocd app sync-history guestboy-dev

在 syncPolicy.automated.selfHeal: true 配置下，任何对集群资源的”手动篡改”都会被自动纠正回 Git 仓库中的期望值。这就是 GitOps”Git 即真相”的威力。

常见问题

Q1：Argo CD 连接私有 GitLab 仓库报权限错误

Argo CD 默认使用 HTTPS 方式访问 Git 仓库。对于自托管 GitLab 私有仓库，需要配置 Repository Credential：

💻 代码示例

# 方式一：使用 Personal Access Token

argocd repo add https://gitlab.stellardata.top/devops/gitops-manifests.git

–username deploy-token

–password <your-gitlab-access-token>

–name gitops-repo

# 方式二：使用 SSH Key（生产推荐）

# 先创建 Secret 存放私钥

kubectl create secret generic gitlab-ssh-key

-n argocd

–from-file=sshPrivateKey=/root/.ssh/id_ed25519

# 然后通过 Argo CD CRD 配置仓库凭证（或通过 UI 添加）

配置完成后在 Web UI 的 Settings → Repositories 中能看到 Connected 状态。

Q2：Argo CD Sync 卡在 OutOfSync 不自动同步

最常见原因是缺少 syncPolicy.automated 配置，或 automated 下未启用 prune。检查 Application spec：

💻 代码示例

argocd app get guestboy-dev | grep -A5 "Sync Policy"

# 如果 Sync Policy 为 <none>，需添加 automated 配置

Q3：生产环境是否该开启 selfHeal

selfHeal: true 适合 dev/test 环境，能保证集群始终与 Git 一致。但在生产环境，如果运维人员需要紧急手工扩容以应对流量突发，selfHeal 会立刻回滚这个操作。生产环境通常设 selfHeal: false，仅在 Argo CD 中标记 Drift 并告警，由人工决策是否同步。

总结

本篇完成了 GitOps 范式的核心工具 Argo CD 的全流程部署：

概念层面：理解了 GitOps 的四大原则与 Push/CD 模式的区别，认识到 Git 作为 Single Source of Truth 的价值。
仓库层面：创建了 gitops-manifests 配置仓库，按应用 + 环境组织目录结构，并放入了示例应用清单。
部署层面：通过 Helm 在 argocd 命名空间安装 Argo CD，配置 NodePort 暴露 Web UI。
配置层面：安装 CLI、登录、修改密码、创建第一个 Application CRD。
验证层面：通过 CLI 和 Web UI 双重验证了应用的自动同步与 selfHeal 自动对账能力。

至此，我们的 DevOps 管道在 CD 侧具备了”Git 变更 → Argo CD 检测 → 自动同步到集群”的能力。但 Argo CD 目前还需要手动触发同步或依赖 automated 策略；真正的全链路闭环需要让 CI（GitLab 构建推镜像）与 CD（Argo CD 同步）形成联动——CI 完成后自动更新 GitOps 仓库中的镜像 Tag，从而触发 Argo CD 同步。这正是明天的核心主题。