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>
2.2 KiB
2.2 KiB
Kubernetes Patterns
Volume Mounts
- Avoid
subPathvolume mounts for Secrets and ConfigMaps. The kubelet does not auto-updatesubPathmounts 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 restartissued 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: Recreatefor 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
rollingUpdatefield. Must patch the live resource first.
Naming
metadata.namemust be DNS-1035 compliant — no dots allowed. Replace dots with dashes (e.g.,oreillyit-nznotoreillyit.nz). Label values CAN contain dots.
Bootstrap Ordering
Some components have chicken-and-egg dependencies:
- CNI (e.g., Cilium) must be installed before anything else — nodes are NotReady without it
- GitOps controller (e.g., ArgoCD) installed second
- 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
toFQDNsrules must usetoEndpointstargeting kube-dns pods withrules.dns— this triggers the DNS proxy. UsingtoCIDRSetfor DNS bypasses the proxy and FQDN rules never populate. - Cross-namespace policies need explicit namespace matching (e.g.,
matchExpressionson namespace label). - Always test from the actual consumer namespace, not same-namespace test pods.
Miscellaneous
enableServiceLinks: falsemay be needed when K8s-injected service env vars conflict with app config (e.g., Authelia interpretsAUTHELIA_*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).