Kubernetes ClusterIP service explained (with YAML examples)

ClusterIP is the default Kubernetes Service type. When you create a Service without specifying a type, you get a ClusterIP. It assigns a stable virtual IP address that is only reachable from within the cluster. Traffic from outside the cluster cannot reach a ClusterIP Service directly.

Use ClusterIP for communication between services inside your cluster: your frontend connecting to your backend, your application connecting to a database, or any workload that should only be reachable by other pods.

How ClusterIP works

A ClusterIP Service does two things. It provides a stable virtual IP address (the ClusterIP) that does not change even when the pods behind it are replaced. And it uses a label selector to discover which pods to route traffic to, updating its endpoint list automatically when pods are created, updated, or deleted.

Port vs targetPort

This is the most commonly misunderstood aspect of Services.

port is the port the Service itself listens on. This is what other pods use to connect to the Service.

targetPort is the port the application inside the pod is listening on. This is where the Service forwards traffic to.

They are often different values. For example, your Service might listen on port 3000 (a clean, predictable port for callers) while your application inside the pod runs on port 8080 (whatever the application was written to use). The Service translates between the two automatically.

1Other pod connects to: service-name:3000
2Service forwards to: pod-ip:8080

Working example

Create a namespace and deployment:

1kubectl create namespace example
2kubectl create deployment node-application --image=node:18 --port=8080 -n example
3kubectl label deployment node-application run=node-application -n example

Create the ClusterIP Service:

1apiVersion: v1
2kind: Service
3metadata:
4  name: node-application
5  namespace: example
6spec:
7  type: ClusterIP
8  selector:
9    run: node-application
10  ports:
11  - name: http
12    protocol: TCP
13    port: 3000
14    targetPort: 8080

1kubectl apply -f service.yaml -n example

Verify the Service and pods are running:

1kubectl get all -n example

Expected output:

1NAME                                   READY   STATUS    RESTARTS   AGE
2pod/node-application-6b7f9d8c5-abc12   1/1     Running   0          30s
3
4NAME                       TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
5service/node-application   ClusterIP   10.96.145.23    <none>        3000/TCP   10s

The ClusterIP 10.96.145.23 is only reachable from within the cluster. Other pods can connect to the Service at node-application.example.svc.cluster.local:3000.

Check the pods and their IP addresses:

1kubectl get pods -o wide -n example

Check the endpoints the Service has discovered:

1kubectl get endpoints -n example

Expected output:

1NAME               ENDPOINTS           AGE
2node-application   10.244.1.5:8080     15s

The endpoint shows the pod IP and the targetPort (8080), not the Service port (3000). This confirms the Service is correctly translating between port 3000 (callers) and port 8080 (the application).

How the Service discovers pods

The selector field in the Service YAML is the key:

1selector:
2  run: node-application

Any pod with the label run: node-application becomes an endpoint for this Service. When a pod is rescheduled and gets a new IP address, the Service automatically updates its endpoint list. You never need to update the Service configuration when pods change.

Accessing the Service from within the cluster

From another pod in the same namespace:

1curl node-application:3000

From another namespace:

1curl node-application.example.svc.cluster.local:3000

To test from your local machine during development, use port-forward:

1kubectl port-forward service/node-application 3000:3000 -n example

Then open http://localhost:3000 in your browser.