mcpField
D
darkmatter-gitops-conventions

darkmatter-gitops-conventions

github.com/darkmatter云与 DevOps0297 次安装5 天前更新
代码仓库

关于 darkmatter-gitops-conventions

为通过 `darkmatter/gitops` 仓库管理 Darkmatter k3s 集群定义 GitOps 规则，强调以提交和可复现的更改为准，通过 ArgoCD 协调，并加密保存仓库内密钥。

主要功能

  1. 01以 Git 作为集群事实来源
  2. 02通过 ArgoCD 清单管理更改
  3. 03提交前验证清单
  4. 04按提交或摘要固定容器镜像
  5. 05使用 SOPS 加密保存基础设施密钥
  6. 06在 beads 中跟踪后续事项

适用场景

  1. 01通过已提交的清单更新 k3s 集群
  2. 02使用 git revert 回滚集群更改
  3. 03提交前检查清单语法和模式
  4. 04安全编辑加密的基础设施密钥

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/darkmatter/skills --skill darkmatter-gitops-conventions

安装后在 Claude Code 中输入/darkmatter-gitops-conventions确认已加载。

详细介绍

Darkmatter gitops 约定

darkmatter/gitops 是 k3s 集群的唯一真实来源：ArgoCD 应用集合、Helm 值、KSOPS 密钥、网络策略、cloudflared 路由。 只有提交到这里的更改才算数——其他一切都是配置漂移。

首要规则

绝不以命令式方式修改集群。不要使用 kubectl apply/edit/patch、helm upgrade，也不要命令式地重启。如果线上对象与仓库不一致，以仓库为准，对象才是有问题的一方。

  • 重新加载部署：在清单中更新其 pod-template config-rev 注解并提交，而不是运行 kubectl rollout restart。
  • 立即强制 ArgoCD 协调：在清单中设置 arc.darkmatter.io/reconcile-at: "<current UTC timestamp>" 注解。
  • 回滚：git revert 有问题的提交并推送。ArgoCD 会自动收敛。绝不要在线上“向前修复”。

每次提交前都要验证

运行以下三项；CI 也会运行它们，主分支变红比提交慢更糟：

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

对于 Helm 值位于块标量中的 ArgoCD apps/*.yaml，也要验证其中嵌入的 YAML：

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

断言脚本不得掩盖失败：不要使用 || true；当管道的退出代码很重要时，使用 set +e 并显式捕获 PIPESTATUS[0]。

镜像

使用完整提交标签（sha-<40-hex>）或摘要固定镜像版本——绝不使用 latest，也绝不使用分支标签。升级镜像时，应只产生一行差异，并在消息中注明所部署的提交。ArgoCD 会在同步时应用更改（约 3 分钟）；沙箱或 Pod 规格哈希变化会自动触发相关预热池更新。

密钥（KSOPS/SOPS）

  • 密钥以加密的 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 PUTs），不放入 git——本仓库只存放基础设施密钥。

ArgoCD 预期行为

  • 同步周期约为 3 分钟；请在 ArgoCD 中检查应用，而不是再次推送。
  • 同步重试过期时：从 Application 中移除 /operation 字段并执行硬刷新。
  • 必须在修剪时保留的关键资源带有 IgnoreExtraneous / Prune=false 注解——编辑附近内容时应保留现有注解。

任务

在 beads 中跟踪后续事项（bd create），不要写 TODO 注释。可复现性是衡量标准：必须能够仅凭本仓库重建集群。

评论

支持 Markdown