3.1 chart/#

chart/ 是 bootstrap Helm Chart，只负责生成：

• AppProject
• ApplicationSet

这里的 chart/values.yaml 仅作为 Chart 默认值与字段结构定义使用，不作为正式部署入口。

3.2 deploy/#

deploy/ 是正式部署入口。

例如：

• deploy/kind.yaml
• deploy/prod.yaml

这里定义 bootstrap chart 的环境级参数，例如：

• generatorRepo.url
• generatorRepo.revision
• project.name
• appSet.name
• environment.file
• appSet.appsFile

实际部署时，应该显式指定：

1
helm template gitops-bootstrap chart -f deploy/kind.yaml

3.3 apps/<env>/#

apps/<env>/ 用于定义某个环境下的应用清单和应用元数据。

这里主要管理：

• enabled
• version
• syncWave
• destinationNamespace
• repoURL
• chart

示例：

1
name: gitlab
2
enabled: "false"
3
repoURL: https://charts.gitlab.io
4
chart: gitlab
5
version: 8.8.1
6
destinationNamespace: gitlab
7
syncWave: "4"

这意味着：

• 在 kind 环境中，gitlab 默认不部署
• 如果需要启用，直接把 enabled 改成 "true"

3.4 environments/<env>.yaml#

环境文件定义公共环境信息。

示例：

1
env: kind
2
valuesRepoURL: https://github.com/hua-ri/gitops-environment-setup.git
3
valuesRevision: main
4
valuesDir: kind
5
clusterServer: https://kubernetes.default.svc

字段含义：

• env：环境名，用于生成 Application 名称
• valuesRepoURL：values 所在 Git 仓库地址
• valuesRevision：values 仓库分支或标签
• valuesDir：values 子目录，例如 kind 或 prod
• clusterServer：Argo CD 目标集群地址

3.5 values/<env>/#

values/<env>/<app>-values.yaml 用于保存子 chart 自身参数。

这里通常放：

• 副本数
• ingress
• TLS
• 资源限制
• Helm Chart 业务参数

示例：

1
expose:
2
  type: ingress
3
  tls:
4
    enabled: false

这里不放：

• enabled
• version
• syncWave

这些字段属于应用元数据，应该维护在 apps/<env>/ 中。

3.6 kind-config.yaml#

用于创建本地 kind 集群，是本地验证完整 GitOps 链路的入口配置文件。

4.1 第一阶段：渲染 bootstrap chart#

执行：

1
helm template gitops-bootstrap chart -f deploy/kind.yaml | kubectl apply -f -

这一阶段只会创建：

• AppProject
• ApplicationSet

此时还没有直接把 Harbor、Ingress Nginx、Argo Workflows 等业务组件展开成 Kubernetes manifests。

4.2 第二阶段：ApplicationSet 生成 Application#

当 ApplicationSet 创建成功后，ApplicationSet Controller 会继续执行：

1. 读取 environment.file
2. 读取 appSet.appsFile
3. 过滤 enabled == true 的应用
4. 根据环境上下文和应用清单生成最终的 Application
5. 每个 Application 再去拉取：
   • Helm Chart Source
   • Values Git Source
6. 最终由 Argo CD 完成 Helm 渲染和同步

4.3 整体架构图#

4.4 方案特点#

这套方案的优势在于：

• 环境差异直接落在 apps/<env>/ 和 values/<env>/
• deploy/ 作为正式部署入口，职责明确
• chart/ 只保留 Chart 本体，不混入正式环境配置
• 不需要额外 merge 层，维护成本低
• 心智模型简单，排障路径清晰

可以概括为：

• 想改应用开关、版本：改 apps/<env>/
• 想改应用参数：改 values/<env>/
• 想改目标集群：改 environments/<env>.yaml
• 想改 bootstrap 入口：改 deploy/<env>.yaml

5.1 从 Github clone 仓库#

当前仓库托管于 Github，操作前需要先 clone：

1
git clone https://github.com/hua-ri/gitops-environment-setup.git
2
cd gitops-environment-setup

如果仓库是私有仓库，需要使用有效的账号、Token 或 SSH 凭据。

5.2 确认正式部署入口#

当前正式部署入口为：

• deploy/kind.yaml
• deploy/prod.yaml

其中：

• deploy/kind.yaml 用于本地或测试环境
• deploy/prod.yaml 用于生产示例环境

5.3 创建本地 kind 集群#

本地验证时，可直接使用顶层 kind-config.yaml：

1
kind create cluster --config ./kind-config.yaml

如果需要指定名称或节点镜像，可使用：

1
sudo kind create cluster --config=kind-config.yaml --name huari-test --image kindest/node:v1.34.0 --retain

切换 kubectl 上下文：

1
sudo kubectl cluster-info --context kind-huari-test

查看集群：

1
kubectl get nodes
2
kubectl get pods -A -owide

删除集群：

1
kind delete cluster --name huari-test

5.4 安装 Argo CD#

1
helm repo add argo https://argoproj.github.io/argo-helm
2
helm repo update
3
helm upgrade --install argocd argo/argo-cd \
4
  --version 7.3.5 \
5
  --namespace argo \
6
  --create-namespace

访问 UI：

1
kubectl port-forward svc/argocd-server -n argo 8080:443 --address 0.0.0.0

获取初始管理员密码：

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

5.5 配置 GitLab 仓库凭据#

如果 GitLab 仓库是私有的，必须先在 Argo CD 中注册仓库凭据，否则 ApplicationSet 和 Application 在拉取 Git 内容时会失败。

示例：

1
apiVersion: v1
2
kind: Secret
3
metadata:
4
  name: repo-gitlab-values
5
  namespace: argo
6
  labels:
7
    argocd.argoproj.io/secret-type: repository
8
stringData:
9
  type: git
10
  url: https://github.com/hua-ri/gitops-environment-setup.git
11
  username: <gitlab-username-or-token-name>
12
  password: <gitlab-token-with-read_repository>

应用：

1
kubectl apply -f repo-gitlab-values.yaml

注意：

• YAML 第一行必须是 apiVersion
• 不要把真实 Token 提交到 Git 仓库
• 如果 Token 已经暴露，应立即在 GitLab 侧撤销并重新生成

5.6 替换仓库地址并推送到 GitLab#

正式部署前，需要确认以下文件中的仓库地址已经替换为真实 GitLab 地址：

• deploy/kind.yaml
• deploy/prod.yaml
• environments/kind.yaml
• environments/prod.yaml

修改后必须提交并推送：

1
git add deploy/*.yaml environments/*.yaml
2
git commit -m "fix: update gitlab repo url"
3
git push origin main

关键原则：

• Argo CD 最终读取的是 GitLab 远端仓库内容
• 不是你本地 clone 工作区里未提交的文件

5.7 部署 kind 环境#

1
helm template gitops-bootstrap chart \
2
  -f deploy/kind.yaml | kubectl apply -f -

5.8 验证 kind 环境#

先检查 GitOps 控制面：

1
kubectl get appprojects -n argo
2
kubectl get applicationsets -n argo
3
kubectl get applications -n argo

再检查关键业务命名空间：

1
kubectl get pods -n argo
2
kubectl get pods -n ingress-nginx
3
kubectl get pods -n harbor

说明：

• kind 默认关闭 gitlab
• 因此本地验证时看不到 gitlab 相关资源是正常的

5.9 部署 prod 示例#

1
helm template gitops-bootstrap chart \
2
  -f deploy/prod.yaml | kubectl apply -f -

本质上这里切换的是：

• environment.file=environments/prod.yaml
• appSet.appsFile=apps/prod/*.yaml

6.1 kind#

• 使用 deploy/kind.yaml
• 使用 apps/kind/*.yaml
• 使用 values/kind/
• 默认关闭 gitlab

6.2 prod#

• 使用 deploy/prod.yaml
• 使用 apps/prod/*.yaml
• 使用 values/prod/
• 默认保留示例应用开启

6.3 kind 与 prod 差异一览#

7.1 新增应用#

通常需要新增 4 个文件：

1. apps/kind/<app>.yaml
2. apps/prod/<app>.yaml
3. values/kind/<app>-values.yaml
4. values/prod/<app>-values.yaml

如果某个环境不需要该应用，可以：

• 不创建该环境下的 app 文件，或
• 创建后将 enabled 设为 "false"

7.2 修改版本#

直接修改对应环境的 app 文件，例如：

• apps/kind/harbor.yaml
• apps/prod/harbor.yaml

7.3 开关应用#

直接修改对应环境 app 文件里的 enabled。

7.4 调整应用参数#

直接修改对应环境的 values 文件，例如：

• values/kind/harbor-values.yaml
• values/prod/harbor-values.yaml

7.5 新增环境#

新增环境时，通常需要补齐 4 类文件：

1. deploy/<env>.yaml
2. environments/<env>.yaml
3. apps/<env>/*.yaml
4. values/<env>/*-values.yaml

8.1 查看 Argo CD 资源#

1
kubectl get applications -n argo
2
kubectl get appprojects -n argo
3
kubectl get applicationsets -n argo

8.2 查看 Argo CD 组件状态#

1
kubectl get pods -n argo
2
kubectl get svc -n argo

8.3 查看目标命名空间资源#

1
kubectl get pods -n ingress-nginx
2
kubectl get pods -n harbor
3
kubectl get pods -n gitlab

8.4 查看应用详情与事件#

1
kubectl describe application kind-harbor -n argo
2
kubectl describe application prod-harbor -n argo

8.5 查看控制器日志#

1
kubectl logs -n argo deploy/argocd-application-controller
2
kubectl logs -n argo deploy/argocd-server
3
kubectl logs -n argo deploy/argocd-applicationset-controller

8.6 判断配置修改是否真的生效#

这是最容易踩坑的一点。

建议分别从三层判断：

检查本地 Helm 渲染结果：

1
helm template gitops-bootstrap chart -f deploy/kind.yaml | grep -n 'gitlab.papegames.com'

检查集群对象：

1
kubectl get applicationsets,applications -n argo -o yaml | grep -n 'gitlab.papegames.com'

检查 GitLab 远端 main 分支：

1
git fetch origin
2
git show origin/main:deploy/kind.yaml | grep url
3
git show origin/main:environments/kind.yaml | grep valuesRepoURL

判断逻辑：

• 本地 Helm 输出正确，但集群对象还是旧值：说明旧对象未刷新
• 集群对象正确，但 Argo 仍报旧地址：需要检查是否仍有旧 Application
• 本地工作区正确，但 origin/main 还是旧值：说明还没有 push 到远端