# Kubernetes development mTLS overlay

该 Overlay 在 base 资源之上启用 Controller 控制面 mTLS，并启动一个 Gateway 和
Checker。进程通过 `PROXY_POOL_AUTO_IDENTITY=true` 从各自证书的 URI SAN 派生身份；
它只用于开发或预发布的单副本控制面验证，不是生产弹性身份方案。

## Prepare certificates

先生成未提交的开发证书。输出目录必须为空；生成器的 `controller` 证书包含
`DNS:controller`，Overlay 中的客户端也只拨号 `controller:8443`。

```powershell
./scripts/generate-local-controlplane-certs.ps1
kubectl apply -f deploy/kubernetes/base/namespace.yaml
```

将生成的三组证书写入 Kubernetes Secret。下面的命令可重复执行，只更新对应 Secret：

```powershell
kubectl -n proxy-pool create secret generic proxy-pool-controlplane-server-tls `
  --from-file=tls.crt=deploy/.control-plane-tls/controller/tls.crt `
  --from-file=tls.key=deploy/.control-plane-tls/controller/tls.key `
  --from-file=ca.crt=deploy/.control-plane-tls/controller/ca.crt `
  --dry-run=client -o yaml | kubectl apply -f -

kubectl -n proxy-pool create secret generic proxy-pool-controlplane-gateway-tls `
  --from-file=tls.crt=deploy/.control-plane-tls/gateway-a/tls.crt `
  --from-file=tls.key=deploy/.control-plane-tls/gateway-a/tls.key `
  --from-file=ca.crt=deploy/.control-plane-tls/gateway-a/ca.crt `
  --dry-run=client -o yaml | kubectl apply -f -

kubectl -n proxy-pool create secret generic proxy-pool-controlplane-checker-tls `
  --from-file=tls.crt=deploy/.control-plane-tls/checker-a/tls.crt `
  --from-file=tls.key=deploy/.control-plane-tls/checker-a/tls.key `
  --from-file=ca.crt=deploy/.control-plane-tls/checker-a/ca.crt `
  --dry-run=client -o yaml | kubectl apply -f -
```

另行从私密配置系统创建 `proxy-pool-secrets`。可参考 base 目录的
`secret.example.yaml`，但不要把实际数据库、Redis、Provider 或 API 凭据写入 Git。

## Deploy

```powershell
kubectl apply -k deploy/kubernetes/overlays/development-mtls
kubectl -n proxy-pool rollout status deployment/proxy-controller --timeout=5m
kubectl -n proxy-pool rollout status deployment/proxy-gateway --timeout=5m
kubectl -n proxy-pool rollout status deployment/proxy-checker --timeout=5m
```

Overlay 的 Gateway 从 `gateway-a` 证书派生 `worker_id=gateway-a`，Checker 从
`checker-a` 证书派生 `checker_id=checker-a`，并把 Gateway HPA 限制为
`minReplicas=maxReplicas=1`。因此不得在此 Overlay 上增加副本数或放宽 HPA；重复使用
同一证书和 Worker 身份会破坏 session、ownership 和证书角色边界。

生产环境需要由工作负载身份系统为每个副本签发独立、可轮换的证书，并将该副本的
身份注入 Gateway Client TLS 或 Checker Client TLS，并启用自动身份派生。应用会在每次新
控制面 TLS 握手读取更新后的叶证书和信任根；已有 gRPC 流仍按原会话保留，根轮换时先投放
新旧根的重叠信任包，再按 PDB 滚动排空旧连接。