Jon Chery
d1aa5daf2b
---ci--- project: atelier phase: 5 milestone: v0.2 status: complete requirements: covered: [ATELIER-36, ATELIER-37, ATELIER-38, ATELIER-39, ATELIER-40, ATELIER-41, ATELIER-42, ATELIER-43, ATELIER-44, ATELIER-45, ATELIER-46, ATELIER-47, ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56, ATELIER-57, ATELIER-58, ATELIER-59] partial: [] ---/ci---
3.6 KiB
3.6 KiB
Networking — Derived Rules
Derives from
domains/kubernetes/first-principles.md. Covers Service, Ingress, Gateway API, EndpointSlices, NetworkPolicy, and DNS. Applies P1, P3, P6.
The Service (P3 Labels Select)
- A Service routes traffic to pods selected by a label selector. The selector is the join between the network abstraction and the workloads.
- Service types:
ClusterIP(in-cluster only, default),NodePort(exposed on every node's IP at a fixed port),LoadBalancer(cloud-managed LB points to the Service). Default toClusterIP; expose only what must be exposed. - A Service fronts a Deployment (or other controller), never a bare pod. The controller keeps pods available; the Service routes to whichever are ready (per the readiness probe — see
workloads.md).
EndpointSlices (P3 Labels Select, P5 Probes Drive Health)
- An EndpointSlice lists the pod IPs currently backing a Service. Only pods passing their readiness probe appear.
- The Service routes by EndpointSlice, not by selector directly. A pod with the right labels but a failed readiness probe is not in the Service.
Ingress and Gateway API (P6 Namespaces Bound Blast Radius)
- Ingress routes HTTP/HTTPS traffic from outside the cluster to Services. It is L7 routing by host and path.
- Gateway API is the successor to Ingress: more expressive (TCP, UDP, TLS passthrough), role-oriented (GatewayClass → Gateway → Route), and cross-platform. Prefer Gateway API for new L7 needs.
- Both Ingress and Gateway API are implemented by a controller (nginx-ingress, Traefik, Istio, Envoy Gateway). Pick one; mixing ingress controllers in a cluster is operational debt.
NetworkPolicy (P6 Namespaces Bound Blast Radius, P7 RBAC by Intent)
- A NetworkPolicy is a firewall rule for pods. Default-deny ingress; allow by namespace and pod selector.
- Without a default-deny NetworkPolicy, every pod can reach every other pod. In production, default-deny is the baseline; allows are the exceptions.
- NetworkPolicy is the network-layer expression of zero-trust authorization — see
domains/security/authorization.md. RBAC (seerbac.md) governs the API; NetworkPolicy governs the network; together they bound blast radius (P6). - NetworkPolicy is enforced by the CNI plugin (Calico, Cilium, etc.). A NetworkPolicy with no supporting CNI is a no-op. Verify the CNI enforces before relying on it.
DNS (P3 Labels Select)
- Every Service gets a DNS record:
<service>.<namespace>.svc.cluster.local. Pods getpod-ip-address.<namespace>.pod.cluster.local(with dots replaced). - Headless Services (
clusterIP: None) resolve directly to pod IPs — use for StatefulSet peer discovery (<statefulset>-0.<service>). - DNS is how workloads find each other without hardcoded IPs. Use the DNS name, not the ClusterIP.
Dual-Stack (C4 Locality)
- IPv4/IPv6 dual-stack is opt-in per cluster. Services can be single-stack or dual-stack per Service.
- Decide at cluster creation. Migrating a single-stack cluster to dual-stack is disruptive and rarely worth it.
What Violates Networking Discipline
| Violation | Principle |
|---|---|
LoadBalancer on an internal-only Service |
P6 Namespaces Bound Blast Radius |
| No default-deny NetworkPolicy | P6 Namespaces Bound Blast Radius, P7 RBAC by Intent |
| Hardcoded pod IP in config | P3 Labels Select (use DNS) |
| Service pointing at a bare pod | P3 Labels Select (point at a controller) |
| Multiple ingress controllers in one cluster | C3 Simplicity (operational debt) |
| No readiness probe on a Service-backed workload | P5 Probes Drive Health (empty EndpointSlices) |