nubenetes/jenkins-2026-gitops-config
GitHub: nubenetes/jenkins-2026-gitops-config
面向 GKE 平台的 GitOps 配置仓库，通过 ArgoCD 管理 JHipster 微服务部署、CNPG 高可用 Postgres、零信任网络策略和 OTel 可观测性的声明式目标状态。
Stars: 0 | Forks: 0
# jenkins-2026-gitops-config
## 目录
- [Golden Path IDP 基础设施](#golden-path-idp-infrastructure)
- [与 `jenkins-2026` 的关系](#relationship-to-jenkins-2026)
- [仓库布局](#repository-layout)
- [镜像标签如何更新](#how-image-tags-are-updated)
- [ArgoCD Applications](#argocd-applications)
- [`microservices` ApplicationSet](#microservices-applicationset)
- [独立 Applications](#standalone-applications)
- [Helm Chart: `helm/microservices`](#helm-chart-helmmicroservices)
- [关键 values schema](#key-values-schema)
- [环境](#environments)
- [Postgres (CNPG)](#postgres-cnpg)
- [NetworkPolicies (零信任)](#networkpolicies-zero-trust)
- [分支策略](#branch-strategy)
- [为什么只有 `main` 分支？](#why-only-the-main-branch)
- [`develop` 分支有意义吗？](#would-a-develop-branch-make-sense)
- [OTel 自动插桩](#otel-auto-instrumentation)
- [相关仓库](#related-repositories)
- [设置与 Fork 指南](#setup--forking-guide)
- [发布与版本策略](#release--versioning-strategy)
- [Git 历史与隐私](#git-history-and-privacy)
- [禁止手动编辑](#do-not-edit-manually)
## Golden Path IDP 基础设施
此仓库定义了 GKE 上现代化**内部开发者平台 (IDP)** 架构的 GitOps 状态。
### 解耦的核心组件
为顺应 2026 年云原生最佳实践，所有平台基础设施 manifest 都与 CI 构建执行解耦，并通过 GitOps 进行管理：
* **弹性节点自动配置 (NAP)**：GKE 原生 (GA) 节点自动配置，由主仓库 `infrastructure/compute-classes/` 下的自定义 `ComputeClass` 驱动，为临时构建 agent 自动创建 **Spot、缩放至零** 的节点池（这是 Google 支持的 Karpenter 等效方案——目前没有适用于 GCP 的生产级 Karpenter provider）。
* **GKE Gateway API 路由**：Jenkins 和 Headlamp 的安全 HTTPS 流量路由映射在 `infrastructure/gateway/` 下，使用原生 `Gateway`、`HTTPRoute` 和 `BackendTLSPolicy`（到 pod 的零信任 TLS）。
* **工作负载感知调度与安全**：为 Headlamp UI 用户映射 K8s v1.36 `PodGroup` (Gang scheduling) 和 `ConstrainedImpersonation` 策略。
## 与 `jenkins-2026` 的关系
```
+--------------------------------------------------------------------+
| nubenetes/jenkins-2026 (infra repo) |
| |
| scripts/ --- bootstrap cluster, install Jenkins/ArgoCD |
| jenkins/ --- JCasC, Job DSL, shared pipeline library |
| helm/ --- Helm charts for supporting services |
| argocd/ --- ApplicationSet/Application manifests |
| observability/ --- OTel collector, Grafana dashboards |
+------------------------+-------------------------------------------+
| scripts/08.5-argocd.sh registers
| THIS repo as ArgoCD source
v
+--------------------------------------------------------------------+
| nubenetes/jenkins-2026-gitops-config (this repo) |
| |
| argocd/ --- Application / AppSet manifests (deployed |
| FROM infra repo, stored here for clarity) |
| helm/microservices/--- Helm chart + env values files |
| values-stable.yaml<- active CI engine writes tags |
+--------------------------------------------------------------------+
```
| 操作 | 执行者 | 位置 |
|--------|------------|-------|
| 引导集群并安装 ArgoCD | `scripts/08.5-argocd.sh` | `jenkins-2026` |
| 在 ArgoCD 中注册此仓库 | `scripts/08.5-argocd.sh` | `jenkins-2026` |
| 构建并推送容器镜像 | 活跃的 CI 引擎 —— Jenkins (`MicroservicesPipeline`) **或** Tekton (`ci.engine=tekton`) | `jenkins-2026/vars/` 或 `jenkins-2026/tekton/` |
| **将镜像标签写入 values 文件** | 活跃的 CI 引擎 —— Jenkins (`vars/microservicesDeploy.groovy`) **或** Tekton (`gitops-update` task) | **此仓库** |
| 检测标签变更并部署到集群 | ArgoCD (自动 sync) | cluster |
| Grafana dashboard 推送 | `scripts/07-grafana-dashboards.sh` | `jenkins-2026` |
## 仓库布局
```
jenkins-2026-gitops-config/
├── argocd/
│ ├── microservices-appset.yaml # ApplicationSet: generates microservices-stable Application
│ ├── microservices-project.yaml # AppProject: scope for the microservices Application
│ ├── headlamp-app.yaml # Application: Headlamp Kubernetes UI
│ ├── pgadmin-app.yaml # Application: pgAdmin 4 Postgres UI
│ └── cnpg-app.yaml # Application: CloudNative-PG Operator (CNPG)
└── helm/
└── microservices/
├── Chart.yaml # Helm chart metadata
├── values.yaml # Base defaults / schema documentation
├── values-stable.yaml # Stable env (namespace: microservices, branch: main)
├── values-develop.yaml # Dormant develop-tier values (only used if a develop track is re-enabled)
└── templates/
├── deployment.yaml # Deployment per service in .Values.services
├── service.yaml # ClusterIP Service
├── ingress.yaml # Ingress (enabled per platform)
├── route.yaml # Gateway API HTTPRoute / OpenShift Route (per platform)
├── instrumentation.yaml # OTel Instrumentation CR (auto-instruments JVM services)
├── postgres.yaml # CNPG Cluster & Pooler CR per service
├── networkpolicies.yaml # Zero-trust: default-deny + gateway / microservice / postgres policies
├── logback-configmap.yaml # ECS-JSON structured-logging config
├── gateway-cache-patch.yaml # gateway Hazelcast cache config
├── limitrange.yaml # Default container resource limits
├── resourcequota.yaml # Namespace resource cap
└── _helpers.tpl # Shared template helpers
```
## 镜像标签如何更新
**活跃的 CI 引擎**——默认为 Jenkins，或当 infra 仓库中设置 `ci.engine=tekton` 时的 **Tekton**——在每次成功构建后更新此处的镜像标签。使用 Jenkins 时，它是 `microservicesDeploy.groovy` 共享库步骤；使用 Tekton 时，它是等效的 `gitops-update` task。两者都会 clone 此仓库，在 values 文件中提升标签，并推送到 `main`：
```
sequenceDiagram
autonumber
actor Jenkins as Active CI Pipeline (Jenkins or Tekton)
participant GitOps as jenkins-2026-gitops-config (Git)
participant ArgoCD as ArgoCD Server
participant Cluster as Kubernetes Cluster
Jenkins->>GitOps: 1. Clone GitOps repo
Jenkins->>GitOps: 2. Update tag in values-stable.yaml
Jenkins->>GitOps: 3. git commit & push tag
Jenkins->>ArgoCD: 4. Sync microservices-stable application
ArgoCD->>Cluster: Reconcile manifests to new image tag
Cluster-->>ArgoCD: Pods running & Healthy
ArgoCD-->>Jenkins: Sync finished & Healthy
```
更新后的 [`values-stable.yaml`](helm/microservices/values-stable.yaml)（或 [`values-develop.yaml`](helm/microservices/values-develop.yaml)）是 **CI 引擎在此仓库中唯一修改的文件**——无论引擎是 Jenkins 还是 Tekton 都一样。其他所有内容由人工或 infra 仓库中的 `scripts/08.5-argocd.sh` 管理。（Tekton 本身由 ArgoCD 从 **infra** 仓库的 `tekton/` + `argocd/tekton/` 进行 GitOps 管理，而不是这里——此仓库仅存放部署目标，这与 CI 引擎无关。参见 [`docs/403-TEKTON.md`](https://github.com/nubenetes/jenkins-2026/blob/main/docs/403-TEKTON.md).)
## ArgoCD Applications
所有四个 Applications 均由 infra 仓库中的 **`scripts/08.5-argocd.sh` 安装**。manifest 存放在这里，以便 ArgoCD 可以通过 `microservices` AppProject 对它们进行自我修复。
### `microservices` ApplicationSet
生成 stable application：
| 生成的 App | Namespace | Values 文件 | 分支 |
|---------------|-----------|-------------|--------|
| `microservices-stable` | `microservices` | [`values-stable.yaml`](helm/microservices/values-stable.yaml) | `main` |
它使用 `prune: true` + `selfHeal: true`。仅生成 **stable** application；develop 层级**默认禁用**（仅当在 infra 仓库中设置了 `microservices.developTrackEnabled` 时，AppSet 才会生成 `develop` 元素）。休眠的 [`values-develop.yaml`](helm/microservices/values-develop.yaml) 保留在 chart 中，以便在该 track 重新启用时使用——参见[分支策略](#branch-strategy)。
### 独立 Applications
| Application | 源 | 目标 Namespace | 备注 |
|-------------|--------|-----------------|-------|
| `headlamp` | `helm/headlamp/values.yaml` (infra 仓库) | `headlamp` | Kubernetes UI, Google OIDC |
| `pgadmin` | `helm/pgadmin/` (infra 仓库) | `pgadmin` | Postgres 管理 UI |
| `cnpg-operator` | `cloudnative-pg/cloudnative-pg` | `cnpg-system` | CNPG, ServerSideApply |
## Helm Chart: `helm/microservices`
单个 chart 渲染了 `values.services.*` 中定义的所有服务。每个服务条目指定其镜像标签和特定于服务的配置；chart 为每个服务生成一个 `Deployment`、`Service`、`Instrumentation` CR 和 `PostgresCluster` CR。
### 关键 values schema
```
global:
platform: gke # gke | eks | aks | openshift
namespace: microservices # overridden per-env by values-stable.yaml
env: stable # "stable" → deployment.environment OTel attribute
registry: ghcr.io/nubenetes/jenkins-2026-microservices
imagePullSecret: ghcr-credentials
otel:
collectorEndpoint: http://otel-collector-gateway.observability.svc.cluster.local:4317
services:
gateway:
type: java
image:
repository: gateway
tag: main # ← Jenkins writes a new SHA here on every build
port: 8080
healthPath: /management/health
resources:
requests: { cpu: 100m, memory: 256Mi }
limits: { cpu: 500m, memory: 512Mi }
env:
- name: SPRING_PROFILES_ACTIVE
value: prod,api-docs
```
### 环境
| 文件 | `env` | `namespace` | ArgoCD App |
|------|-------|-------------|-----------|
| [`values-stable.yaml`](helm/microservices/values-stable.yaml) | `stable` | `microservices` | `microservices-stable` |
`env` 值将成为已部署服务发出的每条 trace/metric/log 的 `deployment.environment` OTel 资源属性，从而支持在 Grafana dashboards 中进行环境过滤。
## Postgres (CNPG)
`.Values.services` 中的每个服务都会获得由 [`templates/postgres.yaml`](helm/microservices/templates/postgres.yaml) 模板化的 CNPG `Cluster` 和 `Pooler` CR（模板无条件遍历**每个**服务；特定于服务的 `postgres.storageSize` / `walStorageSize` 是仅有的可选配置项）。CloudNative-PG Operator（通过 `cnpg-operator` Application 安装）将这些 CR 协调为：
- 高可用的 **PostgreSQL 18.3** 数据库层——**3 个实例**，可用区反亲和性，动态主节点提升。镜像被明确**锁定** (`spec.imageName`，默认为 `ghcr.io/cloudnative-pg/postgresql:18.3-system-trixie`，可通过 `global.postgresImage` 覆盖)，因此数据库版本是可重现的；请谨慎提升版本
- 通过原生 PgBouncer pooler 部署管理的连接池
- 针对 Google Cloud Storage (GCS) 的自动化 Barman Object Store 备份
- 一个通过 `SPRING_DATASOURCE_URL` 或 `SPRING_R2DBC_URL` 注入到服务 pod 中的 secret `postgres--app`
总共配置了两个集群——stable 环境中的每个服务一个：
| Cluster | Namespace |
|---------|-----------|
| `postgres-gateway` | `microservices` |
| `postgres-jhipstersamplemicroservice` | `microservices` |
## NetworkPolicies (零信任)
[`templates/networkpolicies.yaml`](helm/microservices/templates/networkpolicies.yaml) 为 `microservices`
namespace 提供了默认拒绝姿态（由 infra 仓库中的 GKE **Dataplane V2 / Cilium-eBPF** 强制执行）。四个
策略：
| 策略 | 应用于 | 关键 ingress | 关键 egress |
|---|---|---|---|
| `default-deny` | 所有 pod | 无 | 仅 CoreDNS (`kube-system:53`) |
| `gateway-policy` | `gateway` pod | 来自 Gateway/LB 的 **8080** | jhipster **8081**，其 Postgres **5432**，OTLP `observability` **4317/4318** |
| `microservice-policy` | `jhipstersamplemicroservice` pod | 来自 `gateway` pod **以及** **`tekton-ci` + `jenkins`** namespaces 的 **8081**（以便 CI 冒烟测试可以访问 `/management/health`） | 其 Postgres **5432**，OTLP **4317/4318** |
| `postgres-policy` | `cnpg.io/cluster` pods | 来自 app pods、`pgadmin` ns、集群内部的 **5432** | CNPG replication + **443** |
8081 端口上的 CI-namespace ingress 让 Jenkins/Tekton 冒烟阶段能够在强制执行策略下访问
微服务（参见 [`jenkins-2026` docs/501](https://github.com/nubenetes/jenkins-2026/blob/main/docs/501-PLATFORM_OPERATIONS.md#networkpolicy-matrix)).
## 分支策略
GitOps 仓库使用 `main` 分支来设定 `microservices-stable` 部署的目标。活跃的 CI 引擎（Jenkins 或 Tekton）更新 `main` 上的 [`helm/microservices/values-stable.yaml`](helm/microservices/values-stable.yaml) 以提升新的镜像版本。`develop` 层级**默认禁用**（仅生成 `microservices-stable`）；其 [`values-develop.yaml`](helm/microservices/values-develop.yaml) 在 chart 中保持休眠状态，仅在 infra 仓库中设置 `microservices.developTrackEnabled` 时才会激活。
### 为什么只有 `main` 分支？
1. **单一环境目标**：在这个统一模型中，develop 层级默认禁用，仅保留一个活跃的目标 namespace (`microservices`)；可以重新启用 develop track（见下文）。
2. **简化提升**：Jenkins CI pipeline 直接将镜像标签写入 GitOps 仓库 `main` 分支的 [values-stable.yaml](helm/microservices/values-stable.yaml) 中。
### `develop` 分支有意义吗？
是的，但**前提是您要恢复多环境部署模型**（例如，dev/staging 与 stable namespaces）：
* **测试基础设施变更**：如果开发者需要在将 Helm chart 更新（例如，资源限制、新的环境变量或 sidecar 添加）提升到 stable (`main`) 之前，在沙箱 (`develop`) namespace 中进行测试，他们会先将更改推送到 GitOps 仓库的 `develop` 分支进行验证。
* **追踪并行代码轨**：如果上游仓库同时从 `develop` 分支（开发构建）和 `main` 分支（stable 发布）进行构建，Jenkins 会将开发标签提交到 GitOps `develop` 分支上的 [`values-develop.yaml`](helm/microservices/values-develop.yaml)（sync 到 dev namespace），并将 stable 标签提交到 GitOps `main` 分支上的 [values-stable.yaml](helm/microservices/values-stable.yaml)（sync 到 stable namespace）。
### `main` 分支保护 —— CI 可写（不要要求 pull request）
`main` 是**直接推送**的，因此 CI 的 *GitOps 更新*步骤可以无人值守地推送镜像标签提升。实际的 `main` 保护（GitHub -> Settings -> Branches）：
| 设置 | 值 | 原因 |
|---|---|---|
| 合并前要求 pull request | **off** | CI 直接将标签推送到 `main` (`git push origin main`)。Require-PR 会拒绝 PAT 推送（管理员 PAT **不会**绕过保护），并且**会卡住每一次部署**。 |
| 要求的 status checks | **无** | 镜像标签提升是机器生成的——没有任何东西可以作为限制条件。 |
| 包含管理员 | **off** | — |
| 允许强制推送 | **off** | `main` 上的历史记录受。 |
| 允许删除 | **off** | `main` 不能被删除。 |
- **允许 -> `main`：**直接推送（CI 的 PAT，或人工推送 chart/values 编辑）。
- **禁止 -> `main`：**强制推送，分支删除。
## OTel 自动插桩
[`templates/instrumentation.yaml`](helm/microservices/templates/instrumentation.yaml) 模板创建了一个 `Instrumentation` CR（由 OTel Operator 管理，通过 `scripts/03-observability.sh` 安装）。这会通过 mutating webhook 自动将 OTel Java agent 附加到每个 Spring Boot 服务 pod——无需更改应用程序代码或 Docker 镜像。
agent 配置如下：
- `OTEL_EXPORTER_OTLP_ENDPOINT` → 集群内的 OTel Collector gateway
- `OTEL_RESOURCE_ATTRIBUTES` → `service.name`, `service.namespace`, `deployment.environment`
- `OTEL_INSTRUMENTATION_LOGBACK_APPENDER_ENABLED=true` → 将 `trace_id` 注入到日志行中以进行 Loki 关联
## 相关仓库
| 仓库 | 角色 |
|-----------|------|
| [`nubenetes/jenkins-2026`](https://github.com/nubenetes/jenkins-2026) | **Infra 仓库** —— 集群引导，Jenkins，ArgoCD，Observability，共享 pipeline 库 |
| [`nubenetes/jenkins-2026-gitops-config`](https://github.com/nubenetes/jenkins-2026-gitops-config) | **此仓库** —— GitOps 状态：Helm chart，env values，ArgoCD manifests |
| [`nubenetes/jhipster-sample-app-gateway`](https://github.com/nubenetes/jhipster-sample-app-gateway) | **App 源码** —— JHipster **gateway** (Java / Spring Boot；它*提供* Angular SPA 服务，它本身不是 Angular 应用)，构建为 `gateway` 服务。上游 [`jhipster/jhipster-sample-app-gateway`](https://github.com/jhipster/jhipster-sample-app-gateway) 的 fork（该 fork 包含一个真实的 `develop` 分支，用于基于分支的晋升）。 |
| [`nubenetes/jhipster-sample-app-microservice`](https://github.com/nubenetes/jhipster-sample-app-microservice) | **App 源码** —— JHipster 后端**微服务**，构建为 `jhipstersamplemicroservice`。上游 [`jhipster/jhipster-sample-app-microservice`](https://github.com/jhipster/jhipster-sample-app-microservice) 的 fork。 |
## 设置与 Fork 指南
如果您正在为自己或您的组织设置此 PoC，您必须将此配置仓库与主要的[基础设施仓库](https://github.com/nubenetes/jenkins-2026)一起 fork。
1. **Fork 仓库**：将此仓库 (`jenkins-2026-gitops-config`) fork 到您的 GitHub 账户/组织。
2. **更新主 Infra 配置**：在您的 infra 仓库 fork (`jenkins-2026`) 中，更新 `config/config.yaml`，将 `jenkins.selfRepoUrl` 和 `microservices.git.org` 指向您自己的 fork。
3. **配置 Git 凭据**：确保您在 infra 仓库的 Actions 设置中设置了 `GIT_USERNAME` 和 `GIT_TOKEN` secrets，因为 Jenkins pipeline 会动态 clone 并将更新的镜像标签提交到此 GitOps 仓库。
## 发布与版本策略
此 GitOps 配置仓库的发布和标签与主要的[基础设施仓库](https://github.com/nubenetes/jenkins-2026)保持同步：
* **Git 标签**：基础设施栈的每次 stable 发布（例如 `v0.9.0`）都会在两个仓库中应用匹配的标签 `v0.9.0`。
* **发布流程**：
1. 在 `develop` 上测试基础设施修改和 Helm chart 配置。
2. 打开 Pull Request 将 `develop` 合并到 `main`。
3. 合并后，起草 GitHub Release 说明更改，并将标签推送到远程。
## Git 历史与隐私
## 禁止手动编辑
对于所有其他基础设施更改——Jenkins 配置、observability stack、ArgoCD 设置、Headlamp/pgAdmin 的 Helm charts——请在 [`nubenetes/jenkins-2026`](https://github.com/nubenetes/jenkins-2026) 中进行更改，并重新运行相关的脚本或 GitHub Actions workflow。
标签：ArgoCD, CNPG, GitOps, GKE, Helm, 内部开发者平台, 子域名突变, 测试用例, 用户代理