darkmatter-gitops-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Darkmatter gitops conventions

Darkmatter GitOps 规范

darkmatter/gitops

is the single source of truth for the k3s cluster: ArgoCD app-of-apps, Helm values, KSOPS secrets, network policies, cloudflared routes. A change is real only when it's committed here — everything else is drift.

darkmatter/gitops

是 k3s 集群的单一事实来源：包含 ArgoCD app-of-apps 配置、Helm values、KSOPS 密钥、网络策略、cloudflared 路由。只有提交到本仓库的变更才是真实生效的——其他一切都属于配置漂移。

The prime rule

核心原则

Never mutate the cluster imperatively. No

kubectl apply/edit/patch

, no

helm upgrade

, no imperative restarts. If a live object disagrees with the repo, the repo wins and the object is the bug.

Reload a deployment: bump its pod-template config-rev annotation in the manifest and commit — not
```
kubectl rollout restart
```
.
Force ArgoCD to reconcile now: set the
```
arc.darkmatter.io/reconcile-at: "<current UTC timestamp>"
```
annotation in the manifest.
Roll back:
```
git revert
```
the offending commit and push. ArgoCD converges. Never "fix forward" live.

绝对不要以命令式方式修改集群。禁止使用

kubectl apply/edit/patch

，禁止

helm upgrade

，禁止命令式重启。如果运行中的对象与仓库内容不一致，以仓库为准，该运行对象是需要修正的问题。

重新加载部署：在清单中更新其 pod-template 的 config-rev 注解并提交——不要使用
```
kubectl rollout restart
```
。
强制 ArgoCD 立即同步：在清单中添加
```
arc.darkmatter.io/reconcile-at: "<当前UTC时间戳>"
```
注解。
回滚：对问题提交执行
```
git revert
```
并推送，ArgoCD 会自动收敛状态。绝对不要在运行环境中“向前修复”。

Validate before every commit

每次提交前必须验证

Run all three; CI runs them and a red main is worse than a slow commit:

bash

kubeconform -strict -ignore-missing-schemas -summary <changed manifests>
yq eval '.' <changed file> > /dev/null        # syntax parse
git diff --check                              # whitespace damage

For ArgoCD

apps/*.yaml

whose Helm values live in a block scalar, validate the embedded YAML too:

bash

yq eval '.spec.sources[0].helm.values | from_yaml' apps/<app>.yaml > /dev/null

Assertion scripts must not paper over failures: no

|| true

; use

set +e

plus explicit

PIPESTATUS[0]

capture when a pipeline's exit code matters.

请运行以下三项检查；CI 也会执行这些检查，主分支 CI 失败可比提交慢一点严重多了：

bash

kubeconform -strict -ignore-missing-schemas -summary <changed manifests>
yq eval '.' <changed file> > /dev/null        # syntax parse
git diff --check                              # whitespace damage

对于 Helm values 存放在块标量中的 ArgoCD

apps/*.yaml

文件，还需要验证内嵌的 YAML：

bash

yq eval '.spec.sources[0].helm.values | from_yaml' apps/<app>.yaml > /dev/null

断言脚本不能掩盖失败：不要使用

|| true

；当管道的退出码很重要时，使用

set +e

并显式捕获

PIPESTATUS[0]

。

Images

镜像

Pin by full-commit tag (

sha-<40-hex>

) or digest — never

latest

, never a branch tag. Bumping an image = a one-line diff that names the commit it ships in the message. ArgoCD picks it up on sync (~3 min); a changed sandbox/pod spec hash churns dependent warm pools automatically.

必须使用完整提交标签（

sha-<40位十六进制>

）或镜像摘要进行固定——禁止使用

latest

，禁止使用分支标签。升级镜像仅需一行代码的 diff，提交信息中需说明其对应的代码提交。ArgoCD 会在同步时拉取更新（约3分钟）；sandbox/pod 规格哈希的变更会自动触发关联预热池的更新。

Secrets (KSOPS/SOPS)

密钥（KSOPS/SOPS）

Secrets live encrypted in-repo as JSON (
```
*.sops.json
```
), rendered by KSOPS. See ADR-0011. Do not add new
```
*.sops.yaml
```
/
```
.env.sops
```
. Convert existing YAML SOPS files when touched. Kubernetes Secret JSON is valid for the API.
Editing: decrypt to a
```
0600
```
temp file, edit, re-encrypt, then verify structurally (
```
jq empty
```
on the decrypted form) and by diffing key NAMES only — never print values. Clean up the temp file. Plain non-secret manifests stay YAML; keep using
```
yq
```
for those.
Reference secrets by name everywhere else; an inline secret value in any manifest or log is an incident.
Agent/runtime secrets follow the hardened flow (Centaur vault + console PUTs), not git — this repo carries infra secrets only.

密钥以加密 JSON（
```
*.sops.json
```
）形式存放在仓库中，由 KSOPS 渲染。参见 ADR-0011。请勿新增
```
*.sops.yaml
```
/
```
.env.sops
```
格式的文件，修改现有 YAML 格式 SOPS 文件时请转换为 JSON 格式。Kubernetes Secret 的 JSON 格式对 API 是有效的。
编辑方式：解密到权限为
```
0600
```
的临时文件，编辑后重新加密，然后进行结构验证（解密后执行
```
jq empty
```
）并仅对比密钥名称——绝对不要打印密钥值。使用后清理临时文件。非密钥的普通清单保持 YAML 格式，继续使用
```
yq
```
处理即可。
其他所有位置都通过名称引用密钥；任何清单或日志中出现明文密钥值都属于安全事件。
Agent/运行时密钥遵循强化流程（Centaur vault + console PUT），不通过 git 管理——本仓库仅存放基础设施密钥。

ArgoCD expectations

ArgoCD 注意事项

Sync cadence ~3 min; check the app in ArgoCD rather than re-pushing.
Stale sync retries: remove the
```
/operation
```
field from the Application and hard-refresh.
Critical resources that must survive pruning carry
```
IgnoreExtraneous
```
/
```
Prune=false
```
annotations — respect existing ones when editing nearby.

同步周期约3分钟；请在 ArgoCD 中查看应用状态，不要重复推送变更。
同步卡顿时：移除 Application 资源的
```
/operation
```
字段并执行硬刷新。
必须在修剪操作中保留的关键资源带有
```
IgnoreExtraneous
```
/
```
Prune=false
```
注解——编辑附近资源时请遵守现有注解配置。

Tasks

任务管理

Track follow-ups in beads (

bd create

), not TODO comments. Reproducibility is the bar: the cluster must be rebuildable from this repo alone.

后续工作请在 beads 中跟踪（

bd create

），不要写 TODO 注释。可复现性是最低要求：集群必须能够仅通过本仓库完成重建。