port, targetPort and containerPort correctly, and choose between ClusterIP, NodePort and LoadBalancer.","html":"Run kubectl get pods -o wide twice, with a rollout in between, and every IP is different. Pods are replaced constantly: new versions, rescheduling, scaling. Anything that remembered a Pod’s IP is now pointing at nothing. A Service is the stable thing you point at instead.
apiVersion: v1\nkind: Service\nmetadata:\n name: notes-api\n labels:\n app.kubernetes.io/name: notes-api\nspec:\n selector:\n app.kubernetes.io/name: notes-api\n ports:\n - name: http\n port: 80\n targetPort: httpThis creates a virtual IP and a DNS name, notes-api, that last as long as the Service exists. Connections to it are spread across the Pods its selector matches, the same label query the Deployment uses. Kubernetes tracks the current set of matching ready Pods in EndpointSlices and updates them as Pods come and go. Clients never notice.
A ClusterIP isn’t a machine and no process listens on it. Each node’s networking layer (kube-proxy, or an eBPF-based replacement in many clusters) programs rules that rewrite packets sent to the Service’s IP and port so they go to one of the ready Pods. That’s why you can’t ping a Service IP and shouldn’t worry when it doesn’t answer: only the declared ports exist. It’s also why a Service costs almost nothing, so create one for every workload that receives traffic.
This is where most Service bugs live.
\ncontainerPort in the Pod spec is the port your process listens on: 3000. It’s informational, like EXPOSE, but naming it (name: http) lets other objects refer to it.targetPort on the Service is where traffic is delivered on the Pod. It must match where the app actually listens. Here it uses the name http, which resolves to 3000.port on the Service is what clients connect to: 80.Cluster DNS gives every Service a name of the form <service>.<namespace>.svc.cluster.local. From a Pod in the same namespace, the short name notes-api is enough; from another namespace, use notes-api.notes or the full name.
notes-api needs a database, so give it one the same way. For practice in kind, run Postgres as a single-replica Deployment with a ClusterIP Service:
\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: notes-db\nspec:\n replicas: 1\n selector:\n matchLabels:\n app.kubernetes.io/name: notes-db\n template:\n metadata:\n labels:\n app.kubernetes.io/name: notes-db\n spec:\n containers:\n - name: postgres\n image: postgres:17\n env:\n - name: POSTGRES_USER\n value: notes\n - name: POSTGRES_PASSWORD\n value: notes # moved to a Secret in the next lesson\n - name: POSTGRES_DB\n value: notes\n ports:\n - name: postgres\n containerPort: 5432\n---\napiVersion: v1\nkind: Service\nmetadata:\n name: notes-db\nspec:\n selector:\n app.kubernetes.io/name: notes-db\n ports:\n - name: postgres\n port: 5432\n targetPort: postgresnotes-api’s DATABASE_URL host is now notes-db, exactly as db was in Compose. The --- separates two objects in one file.
| Type | \nReachable from | \nUse it for | \n
|---|---|---|
ClusterIP (default) | \nInside the cluster | \nService-to-service traffic, like notes-api → notes-db | \n
NodePort | \nEvery node’s IP on a port in 30000–32767 | \nQuick tests, or as a building block for external load balancers | \n
LoadBalancer | \nA cloud load balancer’s address | \nExposing one service publicly on a managed cluster | \n
There’s also the headless Service, with clusterIP: None. It gets no virtual IP; instead its DNS name returns the IPs of the individual Pods. Databases and other clustered systems use it when each member needs to be addressed directly. You won’t need it for notes-api.
LoadBalancer builds on the other two: the cloud provider creates a load balancer that typically forwards to node ports, which forward to the Service (some controllers send traffic straight to Pod IPs instead). One per public service gets expensive and repetitive when you have many HTTP services; lesson 5.4 covers Gateway API, which puts many routes behind one entry point.
kubectl apply -f k8s/\nkubectl get svc\nkubectl get endpointslices -l kubernetes.io/service-name=notes-api\nkubectl port-forward svc/notes-api 8080:80\ncurl localhost:8080/readyzport-forward tunnels a local port to the Service through the API server. It’s for debugging, not for real traffic. If the EndpointSlice lists no addresses, the Service matches no ready Pods: compare the selector with kubectl get pods --show-labels, then check readiness.
Two problems are now visible in the YAML: a password sits in plain text, and configuration is mixed into the Deployment. The next lesson moves both out.
\n","toc":[{"id":"sec-1","text":"A Service for notes-api","level":2},{"id":"sec-2","text":"Three ports, three meanings","level":2},{"id":"sec-3","text":"Finding Services by name","level":2},{"id":"sec-4","text":"Service types","level":2},{"id":"sec-5","text":"Reaching it from your laptop","level":2}],"takeaways":["A Service gives a changing set of Pods one stable virtual IP and DNS name, and spreads connections across the ready Pods its selector matches.","port is what clients connect to on the Service; targetPort is where traffic goes on the Pod and must match the container’s listening port.","Inside the cluster, Pods reach a Service by name, such as notes-db in the same namespace or notes-db.notes.svc.cluster.local from anywhere.","Use ClusterIP for internal traffic, LoadBalancer to expose one service through a cloud load balancer, and NodePort mainly for testing.","An empty EndpointSlice means the Service matches no ready Pods; check the selector and readiness first."],"further":[{"title":"Service","url":"https://kubernetes.io/docs/concepts/services-networking/service/"},{"title":"DNS for Services and Pods","url":"https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/"},{"title":"Use Port Forwarding to Access Applications in a Cluster","url":"https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/"}],"quiz":[{"q":"notes-api listens on 3000. The Service has port: 80 and targetPort: 3000. Which URL do other Pods in the same namespace use?
http://notes-api:3000","why":"3000 is the Pod’s port. Clients of the Service connect to the Service’s port, which is 80."},{"text":"http://<pod-ip>:80","why":"Pod IPs change on every replacement, and nothing in the Pod listens on 80."},{"text":"http://notes-api (port 80)","why":"Correct. The Service name resolves through cluster DNS, and port 80 is forwarded to 3000 on a ready Pod."},{"text":"http://localhost:80","why":"localhost is the calling Pod itself, not the Service."}],"answer":2},{"q":"kubectl get endpointslices -l kubernetes.io/service-name=notes-api shows no endpoints, but three notes-api Pods are Running. What do you check first?
latest.","why":"Image tags don’t affect Service matching."},{"text":"Whether the cluster DNS is running.","why":"DNS resolves the Service name, but endpoints are computed from labels and readiness, independently of DNS."}],"answer":0},{"q":"You need notes-api reachable from the internet on a managed cluster in AWS, and it’s the only public service. Which Service type fits?
","options":[{"text":"ClusterIP","why":"ClusterIP is only reachable inside the cluster."},{"text":"NodePort, with users connecting to a node IP on port 30080","why":"That exposes every node on a high port and breaks when nodes are replaced. It’s a building block, not a public endpoint."},{"text":"Headless (clusterIP: None)","why":"Headless Services give DNS records for each Pod, for things like databases with stable identities. They don’t expose anything externally."},{"text":"LoadBalancer, which provisions a cloud load balancer in front of the Service","why":"Correct. For one public service it’s the simplest option. With many HTTP services you’d share one entry point through Gateway API instead."}],"answer":3},{"q":"Which targetPort is correct for a container that declares ports: [{ name: http, containerPort: 3000 }]?
targetPort: 80, to match the Service’s port.","why":"targetPort is where traffic lands in the Pod. Nothing listens on 80 there."},{"text":"targetPort: http, the container port’s name (or 3000).","why":"Correct. A named port keeps working even if you later change the number in one place."},{"text":"targetPort: notes-api, the Deployment’s name.","why":"targetPort takes a number or the name of a container port, not an object name."},{"text":"targetPort: 30000, from the NodePort range.","why":"The NodePort range applies to nodePort, a different field on the node side."}],"answer":1}],"exercise":{"kind":"spot-bug","language":"yaml","code":"apiVersion: v1\nkind: Service\nmetadata:\n name: notes-api\nspec:\n selector:\n app.kubernetes.io/name: notes-api\n ports:\n - port: 80\n targetPort: 80\n---\n# excerpt from the Deployment's Pod template\ncontainers:\n - name: api\n image: ghcr.io/skylane/notes-api:1.4.0\n ports:\n - containerPort: 3000","bugLines":[10],"title":"Endpoints exist, requests fail","prompt":"The Service below has three endpoints, the Pods are Running and Ready, yet curl notes-api from another Pod gets connection refused every time. Select the line that causes it.
Line 10 sends traffic to port 80 on the Pods, but notes-api listens on 3000, so every connection is refused. Point targetPort at the container’s port, ideally by name so the two can’t drift:
# Service\n ports:\n - port: 80\n targetPort: http\n# Pod template\n ports:\n - name: http\n containerPort: 3000