Skip to main content

Containers and Kubernetes · Intermediate · 16 min

How to Deploy an App and Expose It with a Service on Kubernetes

By Padding · Updated 15 Nov 2026
Kubernetes 1.37

You will run an app on Kubernetes 1.37 as a Deployment with two replicas, watch it heal itself, give it a stable address with a Service, reach it from your computer, and roll out a new version with a way back.

On this page

In the previous tutorial you started a bare pod, and when it was deleted, it stayed deleted. Real apps need more: several copies so that one failure does not take the site down, replacements that start by themselves, and an address that does not change when the pods behind it do. Kubernetes splits this into two objects. A Deployment keeps a set number of identical pods running and manages updates. A Service gives them one stable name and address.

You will use both on a local kind cluster. It is the fifth tutorial in the series From Docker to Kubernetes.

Step 1 · Create a cluster that publishes one port

A kind cluster runs inside a Docker container, so its internal ports are not on your computer. To reach a Service from your browser, tell kind at creation time to publish one node port. Cluster settings cannot be changed afterwards, so create a new cluster for this tutorial. If the cluster from the last tutorial still exists, kind delete cluster --name demo removes it.

Bash
cat > kind-config.yaml <<'YAML'
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 30080
        hostPort: 8080
        listenAddress: "127.0.0.1"
        protocol: TCP
YAML
kind create cluster --name apps --image kindest/node:v1.37.0 --config kind-config.yaml --wait 120s

The mapping sends port 8080 on your computer, on 127.0.0.1 only, to port 30080 on the cluster node. You will use port 30080 for the Service in a later step. Confirm the cluster answers:

Bash
kubectl get nodes

One node, apps-control-plane, is Ready. kubectl is now pointed at the context kind-apps.

Step 2 · Write a Deployment

Kubernetes objects are described in YAML and sent to the cluster with kubectl apply. This Deployment runs two copies of Nginx 1.30:

Bash
cat > deployment.yaml <<'YAML'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.30-alpine
          ports:
            - containerPort: 80
          readinessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 2
            periodSeconds: 3
          resources:
            requests:
              cpu: 50m
              memory: 32Mi
            limits:
              memory: 128Mi
YAML

The parts that matter:

  • replicas: 2 is the number of pods you want. The Deployment creates a ReplicaSet, and that keeps this many running.
  • selector.matchLabels and template.metadata.labels must match. The label app: web is how the Deployment, and later the Service, find these pods. A mismatch is rejected when you apply the file.
  • readinessProbe asks Nginx for / every three seconds. A pod only counts as ready, and only receives Service traffic, after it answers. This is what makes updates safe.
  • resources.requests is what the scheduler reserves for the pod, and a memory limit kills the container if it exceeds it. Set a request on every app. The CPU limit is left out here on purpose; many teams avoid CPU limits because they throttle the app.

Apply it and wait for it to finish rolling out:

Bash
kubectl apply -f deployment.yaml
kubectl rollout status deployment/web --timeout=120s
kubectl get deployment,pods -l app=web

rollout status ends with deployment "web" successfully rolled out. The listing shows web as 2/2 ready and two pods with generated names such as web-<hash>-<id>.

Troubleshooting

  • A pod stays in ImagePullBackOff or ErrImagePull: the image name or tag is wrong, or the node cannot reach the registry. kubectl describe pod <pod-name> shows the exact message under Events.
  • A pod is Pending: the cluster has no room for its resource requests. kubectl describe pod <pod-name> says why.
  • A pod is Running but never Ready: the readiness probe fails. Check the path and port, and kubectl logs <pod-name>.
  • error validating data or unknown field: a typo or wrong indentation in the YAML. kubectl explain deployment.spec documents every field.

Step 3 · Watch Kubernetes keep its promise

Delete one pod and look at the list a moment later:

Bash
POD="$(kubectl get pods -l app=web -o name | head -n 1)"
kubectl delete "$POD"
kubectl get pods -l app=web

There are still two pods. The ReplicaSet noticed one was missing and created a replacement, so one pod has a fresh name and a low age. Change the number of copies with scale:

Bash
kubectl scale deployment/web --replicas=3
kubectl rollout status deployment/web --timeout=120s
kubectl get pods -l app=web

Now there are three. (Right after a change, a pod being shut down can still be listed as Terminating for a few seconds.) When you keep the replica count in the YAML file, change the number there and apply the file again instead, so the file stays the source of truth. Applying the file, which says replicas: 2, sets it back:

Bash
kubectl apply -f deployment.yaml
kubectl rollout status deployment/web --timeout=120s
kubectl get pods -l app=web

Step 4 · Expose the pods with a Service

The pods' IP addresses change whenever a pod is replaced. A Service is a stable name and address that forwards to whichever ready pods carry a matching label. This one has type NodePort, which opens a fixed port on every cluster node:

Bash
cat > service.yaml <<'YAML'
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  type: NodePort
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80
      nodePort: 30080
YAML
kubectl apply -f service.yaml
kubectl get service web
  • selector: app: web picks the pods by label. This is the link between the two objects.
  • port is the port of the Service inside the cluster, targetPort is the port on the pod, and nodePort is the port on the node. Valid node ports are 30000 to 32767. If you leave nodePort out, Kubernetes picks one.
  • The Service types are: ClusterIP (the default, reachable only inside the cluster), NodePort (a port on every node), and LoadBalancer (asks a cloud provider for an external load balancer, which kind does not have). For web traffic on a real cluster you would normally put an Ingress or the Gateway API in front of a ClusterIP Service.

Check it worked

Port 30080 on the node is published on your computer's port 8080, as set up in the first step:

Bash
curl -s --retry 10 --retry-all-errors --retry-delay 2 http://127.0.0.1:8080/ | grep '<title>'

The reply includes the line <title>Welcome to nginx!</title>. The retry options matter: for a few seconds after you create a Service, the node port can answer with an empty reply or refuse the connection, while the cluster's network rules are still being set up. curl tries again until the port answers. Now look at which pods the Service sends traffic to. Kubernetes records them in an EndpointSlice:

Bash
kubectl get endpointslice -l kubernetes.io/service-name=web

One slice is listed, with the pod IPs in its ENDPOINTS column. Last, reach the Service from inside the cluster, by its name. Cluster DNS resolves web to the Service address for any pod in the same namespace:

Bash
kubectl run probe --rm -i --restart=Never --image=curlimages/curl:8.23.0 --command -- curl -s -o /dev/null -w '%{http_code}\n' http://web

The status code 200 comes back, so the Service answered by name. The pod runs once and removes itself because of --rm. In a pod, use the name web, never a pod IP.

Step 5 · Roll out a new version and roll it back

Change the image to move the app to the next Nginx release. kubectl set image takes the container name from the YAML (nginx), then the new image:

Bash
kubectl set image deployment/web nginx=nginx:1.31-alpine
kubectl rollout status deployment/web --timeout=180s
kubectl get pods -l app=web -o jsonpath='{range .items[*]}{.spec.containers[0].image}{"\n"}{end}'

The pods now show nginx:1.31-alpine. A pod from the old version can still be shutting down for a few seconds after rollout status returns, so a third line with the old image, or a pod marked Terminating in kubectl get pods, is normal; run the command again after a few seconds and only the new image remains. By default, Kubernetes replaces pods a few at a time and starts each new one only after the previous ones are ready, so the Service always has pods to send traffic to. The readiness probe is what tells it a new pod is ready. Check the history, and go back:

Bash
kubectl rollout history deployment/web
kubectl rollout undo deployment/web
kubectl rollout status deployment/web --timeout=180s
kubectl get pods -l app=web -o jsonpath='{range .items[*]}{.spec.containers[0].image}{"\n"}{end}'

rollout undo returns to the previous revision, and the pods go back to nginx:1.30-alpine (again, give the last pod of the newer version a few seconds to disappear). Imperative commands like set image change the cluster but not your YAML file. In day-to-day work, edit deployment.yaml and apply it, so that the file in Git matches the cluster.

Step 6 · Clean up

Delete the objects, or the whole cluster. Deleting the cluster is the quickest and removes everything inside it, including the published port:

Bash
kubectl delete -f service.yaml -f deployment.yaml
kind delete cluster --name apps

Next steps

  • Configure the app without rebuilding it: /tutorials/kubernetes-configmaps-and-secrets.
  • Build the image you deploy: /tutorials/write-a-dockerfile-for-a-node-app.
  • The concepts are explained at kubernetes.io/docs/concepts/workloads/controllers/deployment/ and kubernetes.io/docs/concepts/services-networking/service/.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.