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---
49 lines
3.6 KiB
Markdown
49 lines
3.6 KiB
Markdown
# 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 to `ClusterIP`; 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 (see `rbac.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 get `pod-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) | |