GitOps环境搭建-最终部署方案

1. 方案概述

仓库地址:https://github.com/hua-ri/gitops-environment-setup

本方案用于统一管理多环境下的基础组件部署,基于以下技术栈实现:

方案核心目标:

当前最终方案采用的是:按环境拆分应用清单。

核心设计如下:


2. 组件清单

当前仓库已纳管的核心组件包括:

不同环境下,这些组件的启用状态、版本和参数可以分别控制。

例如:


3. 最终目录结构

.
├── chart/
├── deploy/
│   ├── kind.yaml
│   └── prod.yaml
├── apps/
│   ├── kind/
│   └── prod/
├── environments/
│   ├── kind.yaml
│   └── prod.yaml
├── values/
│   ├── kind/
│   └── prod/
├── kind-config.yaml
└── README.md

3.1 chart/

chart/ 是 bootstrap Helm Chart,只负责生成:

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

3.2 deploy/

deploy/ 是正式部署入口。

例如:

这里定义 bootstrap chart 的环境级参数,例如:

实际部署时,应该显式指定:

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

3.3 apps/<env>/

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

这里主要管理:

示例:

name: gitlab
enabled: "false"
repoURL: https://charts.gitlab.io
chart: gitlab
version: 8.8.1
destinationNamespace: gitlab
syncWave: "4"

这意味着:

3.4 environments/<env>.yaml

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

示例:

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

字段含义:

3.5 values/<env>/

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

这里通常放:

示例:

expose:
  type: ingress
  tls:
    enabled: false

这里不放:

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

3.6 kind-config.yaml

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


4. 工作原理

整个方案分为两个阶段。

4.1 第一阶段:渲染 bootstrap chart

执行:

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

这一阶段只会创建:

此时还没有直接把 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 整体架构图

flowchart TD
    A[从 Git 仓库 clone 项目] --> B[修改部署配置与环境数据]
    B --> C[提交并推送到远端仓库]
    C --> D[渲染并应用 bootstrap chart]
    D --> E[创建 AppProject]
    D --> F[创建 ApplicationSet]
    F --> G[ApplicationSet Controller 开始工作]
    G --> H[读取环境文件]
    G --> I[读取应用清单]
    I --> J[筛选启用的应用]
    H --> K[获得环境上下文]
    J --> L[获得应用定义]
    K --> M[生成 Application]
    L --> M
    M --> N[读取 Helm Chart Source]
    M --> O[读取 Values Git Source]
    O --> P[加载应用 values 文件]
    N --> Q[渲染业务资源清单]
    P --> Q
    Q --> R[同步到目标集群]

4.4 方案特点

这套方案的优势在于:

可以概括为:


5. 端到端部署实战

下面以当前 Github 仓库为基准,说明完整部署流程。

5.1 从 Github clone 仓库

当前仓库托管于 Github,操作前需要先 clone:

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

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

5.2 确认正式部署入口

当前正式部署入口为:

其中:

5.3 创建本地 kind 集群

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

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

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

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

切换 kubectl 上下文:

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

查看集群:

kubectl get nodes
kubectl get pods -A -owide

删除集群:

kind delete cluster --name huari-test

5.4 安装 Argo CD

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
helm upgrade --install argocd argo/argo-cd \
  --version 7.3.5 \
  --namespace argo \
  --create-namespace

访问 UI:

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

获取初始管理员密码:

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 内容时会失败。

示例:

apiVersion: v1
kind: Secret
metadata:
  name: repo-gitlab-values
  namespace: argo
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/hua-ri/gitops-environment-setup.git
  username: <gitlab-username-or-token-name>
  password: <gitlab-token-with-read_repository>

应用:

kubectl apply -f repo-gitlab-values.yaml

注意:

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

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

修改后必须提交并推送:

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

关键原则:

5.7 部署 kind 环境

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

5.8 验证 kind 环境

先检查 GitOps 控制面:

kubectl get appprojects -n argo
kubectl get applicationsets -n argo
kubectl get applications -n argo

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

kubectl get pods -n argo
kubectl get pods -n ingress-nginx
kubectl get pods -n harbor

说明:

5.9 部署 prod 示例

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

本质上这里切换的是:


6. 当前默认策略

6.1 kind

6.2 prod

6.3 kind 与 prod 差异一览

项目 kind prod
部署入口 deploy/kind.yaml deploy/prod.yaml
环境文件 environments/kind.yaml environments/prod.yaml
应用目录 apps/kind/ apps/prod/
values 目录 values/kind/ values/prod/
GitLab 默认状态 false true

7. 日常维护

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

如果某个环境不需要该应用,可以:

7.2 修改版本

直接修改对应环境的 app 文件,例如:

7.3 开关应用

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

7.4 调整应用参数

直接修改对应环境的 values 文件,例如:

7.5 新增环境

新增环境时,通常需要补齐 4 类文件:

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

8. 常见排查方法

8.1 查看 Argo CD 资源

kubectl get applications -n argo
kubectl get appprojects -n argo
kubectl get applicationsets -n argo

8.2 查看 Argo CD 组件状态

kubectl get pods -n argo
kubectl get svc -n argo

8.3 查看目标命名空间资源

kubectl get pods -n ingress-nginx
kubectl get pods -n harbor
kubectl get pods -n gitlab

8.4 查看应用详情与事件

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

8.5 查看控制器日志

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

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

这是最容易踩坑的一点。

建议分别从三层判断:

检查本地 Helm 渲染结果:

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

检查集群对象:

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

检查 GitLab 远端 main 分支:

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

判断逻辑:


9. 多集群说明


10. 总结

当前最终方案可以概括为三句话:

这套方案优先追求:

对于当前仓库来说,这已经是一套清晰、稳定、适合持续演进的最终部署方案。

Connected Pages
GitOps环境搭建-最终部署方案
  • 1. 方案概述
  • 2. 组件清单
  • 3. 最终目录结构
  • 3.1 chart/
  • 3.2 deploy/
  • 3.3 apps// 3.4 environments/.yaml 3.5 values//
  • 3.6 kind-config.yaml
  • 4. 工作原理
    1. 4.1 第一阶段:渲染 bootstrap chart
    2. 4.2 第二阶段:ApplicationSet 生成 Application
    3. 4.3 整体架构图
    4. 4.4 方案特点
  • 5. 端到端部署实战
    1. 5.1 从 Github clone 仓库
    2. 5.2 确认正式部署入口
    3. 5.3 创建本地 kind 集群
    4. 5.4 安装 Argo CD
    5. 5.5 配置 GitLab 仓库凭据
    6. 5.6 替换仓库地址并推送到 GitLab
    7. 5.7 部署 kind 环境
    8. 5.8 验证 kind 环境
    9. 5.9 部署 prod 示例
  • 6. 当前默认策略
    1. 6.1 kind
    2. 6.2 prod
    3. 6.3 kind 与 prod 差异一览
  • 7. 日常维护
    1. 7.1 新增应用
    2. 7.2 修改版本
    3. 7.3 开关应用
    4. 7.4 调整应用参数
    5. 7.5 新增环境
  • 8. 常见排查方法
    1. 8.1 查看 Argo CD 资源
    2. 8.2 查看 Argo CD 组件状态
    3. 8.3 查看目标命名空间资源
    4. 8.4 查看应用详情与事件
    5. 8.5 查看控制器日志
    6. 8.6 判断配置修改是否真的生效
  • 9. 多集群说明
  • 10. 总结