补充秘密投射、本地存储与集群 DNS 使用指南

README.md

@@ -15,6 +15,9 @@
 - [LiteLLM 网关](services/litellm-gateway.md)：模型 API 接入参数与请求示例。
 - [Tailscale](services/tailscale.md)：远程客户端、子网路由与 Service 入口。
 - [ps3netsrv](services/ps3netsrv.md) / [vlmcsd](services/vlmcsd.md)：客户端接入与故障入口。
+- [External Secrets](services/external-secrets.md)：应用秘密投射与更新流程。
+- [OpenEBS](services/openebs.md)：PVC 申请、绑定和数据回收边界。
+- [k3s DNS](services/k3s-dns.md)：Pod 解析、内部域分流与缓存规则。
 - [共享 PostgreSQL 使用指南](services/shared-postgresql.md)：应用接入、连接示例与共享实例维护边界。
 - [PostgreSQL Tenant Operator](services/postgresql-tenant-operator.md)：计划在共享 PostgreSQL 上提供的 DBaaS 中间层。
 - [Gitea Dynamic Runner](services/gitea-dynamic-runner.md)：原 microVM runner，现支持 Pod/VM 两种一次性执行环境。

documentation-backlog.md

@@ -18,15 +18,17 @@
 - [Tailscale](services/tailscale.md)：客户端接入、子网路由和 operator Service 的区别。
 - [ps3netsrv](services/ps3netsrv.md)、[vlmcsd](services/vlmcsd.md)：客户端使用与配置入口。
 
+- [External Secrets](services/external-secrets.md)、[OpenEBS](services/openebs.md)：应用秘密与 PVC 消费示例。
+- [k3s DNS](services/k3s-dns.md)：Pod 解析路径、配置意图与排障入口。
+
 以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。
 
 ## 后续使用说明
 
-1. k3s：补 CoreDNS 定制说明；目录缺少根 README。
+1. marker、openviking、smtp-relay 等：按服务总览逐步补齐消费示例。
-2. marker、openviking、smtp-relay、external-secrets、openebs 等：按服务总览逐步补齐消费示例。
 
 codex-proxy 已按维护者“应该是退役的”的说明移至归档范围，不再补新接入指南。
-本轮新增的四份使用指南已完成；其源码目录仍缺根 README，权威配置入口已在各页列出。
+LiteLLM、Tailscale、ps3netsrv、vlmcsd 与 k3s 的 wiki 指南已补；源码目录仍缺根 README，配置入口已在各页列出。
 
 ## 文档同步与来源链接
 

services/external-secrets.md

@@ -0,0 +1,85 @@
+---
+title: External Secrets 使用指南
+lifecycle: active
+evidence: documented
+last_reviewed: 2026-09-16
+last_verified: null
+---
+
+# External Secrets Operator
+
+ESO 将 [OpenBao](openbao.md) 中的秘密投射为 Kubernetes Secret，供应用消费。
+本页依据 homelab-infra 工作区 `platform/external-secrets/README.md`、
+`clustersecretstore.yaml`、`externalsecrets.yaml` 与 `kustomization.yaml` 整理，未查询现场。
+其中 `externalsecrets.yaml` 含未提交修改，不代表这些修改已部署。
+
+## 应用如何获得秘密
+
+现有 `ClusterSecretStore/openbao` 指向 `https://bao.ad.ddupan.top:8200` 的 KV v2 mount `kv`。
+ESO 使用 `external-secrets` namespace 中同名 ServiceAccount 的短期 JWT，
+通过 OpenBao 的 Kubernetes auth 与 `external-secrets` role 登录。
+这是已记录的认证方式，不能因 SPIFFE 是整体身份设计就宣称 ESO 已迁移到 SPIFFE。
+
+接入前由维护者确认应用 namespace、OpenBao 路径、字段、目标 Secret 名称和授权范围。
+先准备 OpenBao 中的真实值，再提交只含引用的 ExternalSecret；凭据本身不进 Git。
+共享 ClusterSecretStore 不意味着任意 namespace 都应有权引用所有秘密，新增引用需要审查来源与消费者权限。
+
+## 最小字段投射示例
+
+以下是待按应用替换的模板：`your-app` namespace 须已存在，
+OpenBao 的 `kv/k8s/your-app` 须已包含 `password` 字段且允许 ESO 读取。
+本轮仅展示模板，没有创建这些对象。
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: ExternalSecret
+metadata:
+  name: your-app-credentials
+  namespace: your-app
+spec:
+  refreshInterval: 1h
+  secretStoreRef:
+    name: openbao
+    kind: ClusterSecretStore
+  target:
+    name: your-app-credentials
+    creationPolicy: Owner
+  data:
+    - secretKey: password
+      remoteRef:
+        key: k8s/your-app
+        property: password
+```
+
+`remoteRef.key` 相对于 store 的 `kv` mount，不把 API 的 `data/` 层写进这个例子。
+字段映射语义见 [ESO Vault provider](https://external-secrets.io/latest/provider/hashicorp-vault/)；
+这里沿用现有 `vault` provider 配置，不因上游出现其他 provider 就修改认证实现。
+
+应用在同一 namespace 的容器配置中引用生成结果，例如：
+
+```yaml
+env:
+  - name: APP_PASSWORD
+    valueFrom:
+      secretKeyRef:
+        name: your-app-credentials
+        key: password
+```
+
+这是容器配置片段，需放入应用自己的 manifest，不能独立 apply。
+采用环境变量消费时，Secret 刷新不会更新已启动进程的环境变量，轮换须配合应用重启或既有滚动流程。
+
+## 同步与维护边界
+
+受权检查时，先查看 ExternalSecret 的同步状态与事件，再确认目标 Secret 的名称和键是否满足应用引用；
+不通过输出 Secret YAML 或解码真实值来证明接入成功。
+引用缺失先检查 namespace、路径和字段；认证失败检查 store 的 ServiceAccount、OpenBao role/policy 与 TLS。
+
+`creationPolicy: Owner` 使 ESO 管理目标 Secret 的所有权，删除 ExternalSecret 可能连带删除目标 Secret，
+不能将它当作无影响的临时配置。不要手工覆盖 ESO 生成的副本。
+
+源码 README 明确区分 Helm release 接管与 secret delivery 对象接管，当前目录 Kustomization
+只列 Helm 相关资源，没有列入 `clustersecretstore.yaml` 和 `externalsecrets.yaml`。
+新增引用先确定由哪个 GitOps/部署入口管理；把文件改好不等于 Flux 已经应用。
+部署和接管细节回到 `platform/external-secrets/README.md`。
+依赖包括 OpenBao、Kubernetes TokenReview、集群 DNS 与 ESO controller。

services/index.md

@@ -37,12 +37,12 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
 |---|---|---|---|---|---|
 | cert-manager | 签发与续期 TLS 证书 | `ClusterIssuer API` | 记录已接管 Flux | `platform/cert-manager/README.md` | 已有签发和验证说明 |
 | envoy-gateway | LAN HTTP 入口与认证集成 | `192.168.10.127:443` | 记录已接管 Flux | `platform/envoy-gateway/README.md` | 已有服务接入说明 |
-| external-secrets | OpenBao 到 Kubernetes 的秘密投射 | `Kubernetes API` | Helm 记录已接管；对象范围需区分 | `platform/external-secrets/README.md` | 补新增秘密引用的使用流程 |
+| [external-secrets](external-secrets.md) | OpenBao 到 Kubernetes 的秘密投射 | `Kubernetes API` | Helm 记录已接管；对象范围需区分 | `platform/external-secrets/README.md` | 已有字段投射示例与 ownership 边界 |
 | gitea-runner | 旧常驻 Gitea Actions runner | 纯 `self-hosted` | 维护者说明准备退役，尚未标为已退役 | `platform/gitea-runner/README.md`、维护者说明 | 新 workflow 改用 [动态 Pod/VM](gitea-dynamic-runner.md) 的明确 labels |
-| k3s | 集群 CoreDNS 定制 | `集群内 DNS` | 仅发现 DNS 配置 | `platform/k3s/Corefile.desired` | 缺组件 README |
+| [k3s DNS](k3s-dns.md) | 集群 CoreDNS 定制 | `集群内 DNS` | 仅发现 DNS 配置 | `platform/k3s/Corefile.desired` | 已有集群 DNS 使用与配置边界说明 |
 | [nats](nats.md) | 集群共享消息与 JetStream 队列 | `nats.ad.ddupan.top:4222` | 已部署；维护者说明目前唯一消费者为 Dynamic Runner | 维护者 2026-09-16 说明、`platform/nats/README.md` | runner 消息队列约定以独立项目文档为准 |
 | [observability / Grafana](grafana.md) | Grafana、指标、日志和追踪 | `grafana.ad.ddupan.top` | 记录已接管 Flux；9 月 16 日变更入口 | `platform/observability/README.md` | 已有看板、指标与日志查询指南 |
-| openebs | k3s 本地 ZFS 持久卷 | `localpv-zfs-ceph StorageClass` | 记录已接管 Flux | `platform/openebs/README.md` | 已有运维检查；补 PVC 使用边界 |
+| [openebs](openebs.md) | k3s 本地 ZFS 持久卷 | `localpv-zfs-ceph StorageClass` | 记录已接管 Flux | `platform/openebs/README.md` | 已有 PVC 示例、绑定与数据回收边界 |
 | [spire](spire.md) | 跨基础设施的统一机器身份入口 | `Workload API / spire-oidc.ad.ddupan.top` | #34 记录基础设施与最小 OpenBao PoC 已完成；后续集成进行中 | [#34](https://git.ddupan.top/panxiao81/homelab-infra/issues/34)、[RUNBOOK](https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/platform/spire/RUNBOOK.md) | 已有接入指南；动态任务以 ticket 为准 |
 
 ## 基础设施

services/k3s-dns.md

@@ -0,0 +1,64 @@
+---
+title: k3s 集群 DNS 使用说明
+lifecycle: unknown
+evidence: configuration
+last_reviewed: 2026-09-16
+last_verified: null
+---
+
+# k3s 集群 DNS
+
+本页说明 Pod 的 DNS 使用路径，依据 homelab-infra `platform/k3s/Corefile.desired` 与
+`coredns-custom.yaml`。这些文件是配置意图与历史故障处理记录，未现场确认是否与运行配置完全一致。
+LAN 主机通过 DHCP 使用 Blocky/路由器的现状见 [LAN DNS](lan-dns.md)，不能据此推导所有 Pod 的转发链。
+
+## 应用如何使用
+
+Pod 通常通过 Kubernetes DNS 解析 Service。跨 namespace 使用完整地址，例如
+`shared-postgresql-rw.shared-db.svc.cluster.local`；同 namespace 的短名称按 Pod DNS 搜索域处理。
+这类集群内部名称不是远程客户端的公共入口。
+
+集群内访问 Authelia 或 Gitea 时继续使用 `auth.ddupan.top`、`git.ddupan.top` 的原有 URL，
+避免把 OIDC issuer、证书名称或 Git remote 改成 IP 来绕过解析问题。
+
+受权排障时，可在已有且具备 `nslookup` 的应用容器中执行以下只读查询：
+
+```bash
+nslookup kubernetes.default.svc.cluster.local.
+nslookup dc1.ad.ddupan.top.
+nslookup auth.ddupan.top.
+nslookup git.ddupan.top.
+```
+
+末尾的点表示绝对域名，用于减少搜索域扩展对诊断的干扰。
+四个查询分别覆盖集群 Service、AD 域和两个分流入口；本轮没有执行，也没有为此创建调试 Pod。
+DNS 成功只证明解析路径，不证明应用认证和业务请求成功。
+
+## 文件中声明的分流
+
+| 名称范围 | 配置意图 |
+|---|---|
+| `cluster.local` 与集群反向记录 | CoreDNS Kubernetes 插件处理 |
+| `ad.ddupan.top` | 直接转发 Samba AD DNS `192.168.10.5` |
+| `auth.ddupan.top`、`git.ddupan.top` | A 记录返回 Envoy LAN 地址 `192.168.10.127`；AAAA 返回无数据 |
+| `lab.ddupan.top`、`tail7e769.ts.net` | 本地返回 NXDOMAIN，阻止历史搜索域排列请求继续转发 |
+| 其余请求 | 默认 Corefile 转发至 `/etc/resolv.conf` |
+
+最后一项的实际上游由运行环境的 resolver 文件决定。本轮没有读取现场文件，
+不能将源码注释中的历史路由器上游描述当成今天所有节点的 resolver 配置。
+对被本地拒绝的后缀新增用途前，应审查这一历史规则，而不是直接在外部 DNS 增加记录后假定 Pod 能解析。
+
+## 缓存和修改入口
+
+`Corefile.desired` 的默认 server block 配置 `cache 30` 与 `serve_stale 1h immediate`，
+允许在该规则覆盖范围内暂用过期缓存条目；其他独立 server block 不自动继承这条缓存规则。
+因此修改 DNS 记录后，缓存结果可能与权威记录暂时不同。
+语义见 [CoreDNS cache](https://coredns.io/plugins/cache/)。
+
+`coredns-custom.yaml` 声明 `kube-system/coredns-custom`，由 Corefile 的 custom import 使用。
+`Corefile.desired` 的文件名本身不证明它已由 Flux 管理或已经应用。
+变更前先确认该对象的管理入口，再审查影响范围；不要整份替换 CoreDNS 配置来修一个域名。
+
+故障定位先区分集群 Service 解析、AD 转发、固定分流、默认上游和客户端搜索域。
+依赖包括 CoreDNS、Kubernetes API、网络、Samba AD DNS 及默认上游；
+Authelia/Gitea 的业务可达性还依赖 Envoy 和各自后端。

services/openebs.md

@@ -0,0 +1,76 @@
+---
+title: OpenEBS PVC 使用指南
+lifecycle: active
+evidence: documented
+last_reviewed: 2026-09-16
+last_verified: null
+---
+
+# OpenEBS 本地持久存储
+
+应用通过 PVC 申请持久存储。homelab 使用的 StorageClass 为 `localpv-zfs-ceph`，
+provisioner 为 `zfs.csi.openebs.io`，底层来自宿主 `data/ceph` ZFS pool/dataset。
+名称中的 `ceph` 不代表它提供 Ceph 分布式存储能力。
+
+本页依据 homelab-infra `platform/openebs/README.md` 与 `storageclasses.yaml` 整理，
+未查询 PVC、宿主存储或现场容量。源码 README 的历史消费者列表包含已退役项目，
+当前服务归属以[服务总览](index.md)为准，不照抄为现役卷清单。
+
+## 为应用声明 PVC
+
+先确定容量、namespace、备份需求及应用调度约束。
+以下在应用已有 namespace 中申请 1 GiB，容量和名称需按实际用途替换：
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: your-app-data
+  namespace: your-app
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: localpv-zfs-ceph
+  resources:
+    requests:
+      storage: 1Gi
+```
+
+在应用 Pod spec 中引用该 PVC，容器再用 `volumeMounts` 挂载：
+
+```yaml
+volumes:
+  - name: data
+    persistentVolumeClaim:
+      claimName: your-app-data
+```
+
+```yaml
+volumeMounts:
+  - name: data
+    mountPath: /var/lib/your-app
+```
+
+后两段分别是 Pod 与容器配置片段，不是独立 Kubernetes 对象。
+应用与 PVC 必须位于同一 namespace；挂载路径及文件权限以应用要求为准。
+把声明纳入应用既有的 GitOps/部署入口，本轮未创建或挂载 PVC。
+
+## 等待绑定与节点约束
+
+StorageClass 配置 `WaitForFirstConsumer`，PVC 在没有可调度消费者时保持 Pending 不一定是故障。
+检查时结合消费 Pod 的调度事件、StorageClass、节点与存储池容量，不能通过删除重建业务 PVC 试错。
+此为节点本地存储，数据可用性依赖对应宿主；应用不能假设跨节点重调度后自动获得同一份数据。
+绑定与回收语义参见 [Kubernetes StorageClass 文档](https://kubernetes.io/docs/concepts/storage/storage-classes/)。
+
+## 扩容、删除与恢复
+
+配置允许卷扩容，但扩容需要按 CSI、文件系统和应用要求确认结果；不要将其理解为支持任意缩容。
+默认 `reclaimPolicy: Delete`：删除 PVC 可能触发其 PV 与底层数据删除，
+实际处理还应检查该 PV 自身的回收策略。应用退役前需明确数据保留或删除决定。
+
+本地持久卷不是独立备份，也不自动提供多副本高可用。
+为数据库等应用选择备份和恢复方式时，需考虑应用一致性及宿主故障，而不只看 PVC 是否 Bound。
+
+运维与 break-glass 入口为 `platform/openebs/README.md`。
+StorageClass 独立于 Helm release 管理；不要通过卸载 chart、删除 CRD 或业务卷验证升级。
+依赖包括 OpenEBS ZFS CSI、宿主 ZFS、文件系统与 Kubernetes 调度。