e0f8e6471c
- best-practices/: 11 topic files + INDEX.md extracted from cluster-bootstrap and custom-claude-skills (validation, k8s, helm, ansible, secrets, debugging, etc.) - settings.yaml: pipeline config (log retention, tracked projects, max logs per run) - CLAUDE.md: updated with best-practices loading and pipeline documentation - memory/log/: first session log demonstrating the format Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
37 lines
2.2 KiB
Markdown
37 lines
2.2 KiB
Markdown
# Kubernetes Patterns
|
|
|
|
## Volume Mounts
|
|
|
|
- **Avoid `subPath` volume mounts** for Secrets and ConfigMaps. The kubelet does not auto-update `subPath` mounts when the source changes — the pod must be restarted. Use directory mounts instead and adjust the application's config path.
|
|
- **Secret volume propagation is async.** After updating a Secret, the kubelet takes seconds to sync mounted volumes. A `rollout restart` issued immediately after may start pods with stale data. Add a short delay (5s) before restarting.
|
|
|
|
## Deployment Strategies
|
|
|
|
- **RWO PVC + RollingUpdate = Deadlock.** New pod can't attach the volume while the old pod holds it. Use `strategy: Recreate` for single-replica deployments with RWO PVCs.
|
|
- **SSA + strategy change conflict.** Switching from RollingUpdate to Recreate via ServerSideApply fails because SSA won't remove the old `rollingUpdate` field. Must patch the live resource first.
|
|
|
|
## Naming
|
|
|
|
- `metadata.name` must be DNS-1035 compliant — no dots allowed. Replace dots with dashes (e.g., `oreillyit-nz` not `oreillyit.nz`). Label values CAN contain dots.
|
|
|
|
## Bootstrap Ordering
|
|
|
|
Some components have chicken-and-egg dependencies:
|
|
1. CNI (e.g., Cilium) must be installed before anything else — nodes are NotReady without it
|
|
2. GitOps controller (e.g., ArgoCD) installed second
|
|
3. Root app applied last — the GitOps controller then "adopts" CLI-installed releases
|
|
|
|
Manual bootstrap secrets (encryption keys, OIDC client secrets) must be documented as explicit steps.
|
|
|
|
## Network Policies
|
|
|
|
- DNS egress for `toFQDNs` rules must use `toEndpoints` targeting kube-dns pods with `rules.dns` — this triggers the DNS proxy. Using `toCIDRSet` for DNS bypasses the proxy and FQDN rules never populate.
|
|
- Cross-namespace policies need explicit namespace matching (e.g., `matchExpressions` on namespace label).
|
|
- Always test from the actual consumer namespace, not same-namespace test pods.
|
|
|
|
## Miscellaneous
|
|
|
|
- `enableServiceLinks: false` may be needed when K8s-injected service env vars conflict with app config (e.g., Authelia interprets `AUTHELIA_*` service vars as configuration).
|
|
- Proxmox VM names must match K8s node hostnames for cloud controller manager integration.
|
|
- Metrics-server on Talos needs `--kubelet-insecure-tls` (self-signed kubelet certs).
|