The issue opens pre-filled with this page title and URL.
Deploying an application on Kubernetes means declaring how it must run, then giving it a stable access point. You will create a namespace, deploy nginx with a Deployment, expose it through a Service, check that it answers, then increase the number of replicas and watch what changes. You then write the same deployment in a YAML file, and delete the namespace to clean everything up.
What you will learn
Create a namespace to organize your application
Deploy an application with kubectl create deployment
Expose the application with a Service and understand the link between labels, selectors and endpoints
Check that the application answers from inside the cluster
Scale the application and observe what Kubernetes does in the background
Write the same deployment in declarative YAML, then clean up the namespace
Prerequisites
You need a working Kubernetes cluster, for example the one from the lesson Create your first cluster, and kubectl. The Pod, Deployment and Service objects are presented in the key concepts. Before the first command, check which cluster kubectl is talking to with kubectl config current-context: the lesson Kubeconfig and contexts explains that answer.
What you will create
Throughout this guide, you will create:
A demo-app namespace to organize the resources
A Deployment that manages nginx Pods through a ReplicaSet
A Service that targets the Pods carrying the label app=nginx
Read the diagram below as a chain of responsibility. Each level creates and watches the level below it: you declare only the Deployment, the rest appears on its own. The Service is deliberately set apart, at the same level as the Deployment: it does not descend from it, it aims at the Pods from the side, by their label.
The image reference has two parts. The tag 1.30 says which version you want, and it is the part you will recognize. The digest @sha256:… designates an exact content. You use both because a tag is mutable: the publisher can republish nginx:1.30 with other content, and you would only find out when a Pod restarts.
A digest designates one content and only one: you get the image this guide was written on. Avoid latest, which tells you neither the version nor the content.
This guide starts with this approach so you can watch the Kubernetes objects appear without going through YAML. The "Declarative method" section, at the end of the page, gives the equivalent in a file: it is the normal method as soon as you want to replay, review and share a configuration.
Check that the Deployment is ready
Creating the Deployment is instantaneous, starting the Pod is not: the node must first download the image, which takes from a few seconds to a minute depending on your connection. If the next command shows 0/1, run it again after a few seconds before concluding there is a problem. If the result does not change after a minute or two, go to the "The Deployment stays at 0/1" section of the troubleshooting.
See the Deployment status
kubectlgetdeploymentnginx-ndemo-app
Output
NAME READY UP-TO-DATE AVAILABLE AGE
nginx 1/1 1 1 10s
Column
Meaning
READY
Ready Pods / desired Pods
UP-TO-DATE
Pods up to date with the latest configuration
AVAILABLE
Pods that can serve traffic
Swipe to see more
1/1 means one Pod is ready out of one requested: when both numbers are equal, the Deployment is operational.
See the ReplicaSet that was created
The Deployment does not create the Pods directly: it goes through a ReplicaSet, which creates and watches the Pods.
See the ReplicaSet
kubectlgetreplicasets-ndemo-app
Output
NAME DESIRED CURRENT READY AGE
nginx-6d8867d6c 1 1 1 15s
Here, the ReplicaSet is called nginx-6d8867d6c. You will never have to handle it yourself: the Deployment takes care of it.
See the Pod that was created
It is the Pod that actually runs nginx: the Deployment and the ReplicaSet are only management objects. Look at the READY column: the 1/1 here counts the ready containers in the Pod, whereas the one for the Deployment counted the ready Pods. Two columns that look alike, two different units.
List the Pods
kubectlgetpods-ndemo-app
Output
NAME READY STATUS RESTARTS AGE
nginx-6d8867d6c-z2j62 1/1 Running 0 18s
The Pod name (nginx-6d8867d6c-z2j62) is generated automatically:
nginx: name of the Deployment
6d8867d6c: identifier of the ReplicaSet
z2j62: unique identifier of the Pod
Step 3: Expose with a Service
The Pod is running, but its address changes every time it is recreated: it cannot be reached reliably. To reach it, create a Service.
A Service does not make your Pods public. First of all, it gives them a stable address inside the cluster: Pods can die and be reborn with different addresses, the Service address does not move. To test from your workstation, you will use port-forward, in step 5.
Step 4: Understand how the Service finds the Pods
This is where you see how Kubernetes links objects together.
See the labels of the Pods
A label is a key=value tag placed on an object. The Deployment created Pods with the label app=nginx. You never wrote it: kubectl create deployment set it for you from the name of the Deployment. The second label, pod-template-hash, is added by Kubernetes to identify the originating ReplicaSet, and you can ignore it.
Only two lines matter in this very verbose output: Selector and Endpoints. The selector is the label the Service looks for. The endpoints are the addresses of the Pods it actually reaches, those of Pods that carry this label. Comparing the two is a good diagnostic reflex: a correct selector with empty endpoints means no Pod carries the expected label.
Service details
kubectldescribeservicenginx-ndemo-app
Output (excerpt)
Name: nginx
Namespace: demo-app
Selector: app=nginx
Type: ClusterIP
IP: 10.96.17.210
Port: <unset> 80/TCP
Endpoints: 10.244.0.5:80
Field
Meaning
Selector
Label the Service looks for (app=nginx)
Endpoints
IP addresses of the Pods that match the selector
Swipe to see more
The link is now clear:
The Deployment creates Pods carrying the label app=nginx
The Service selects the Pods that carry this same label
The Endpoints show the Pods actually reached
The list of endpoints can also be read with kubectl get endpointslice -n demo-app. Kubernetes stores it in objects called EndpointSlices, and the ENDPOINTS column gives the same Pod addresses as the Endpoints line of the describe. The old kubectl get endpoints command has been deprecated since Kubernetes 1.33: it prints the warning Warning: v1 Endpoints is deprecated in v1.33+; use discovery.k8s.io/v1 EndpointSlice, then its table.
Above all, remember the failure case, because it is silent. If Endpoints is empty, the Service selector matches no Pod: the Service exists, it has an IP address, but it routes to nothing. No error warns you, neither at creation nor afterwards. kubectl get pods --show-labels confirms the fault in one command.
Step 5: Check that the application answers
There are two ways to test, and they do not prove the same thing. From a Pod, you validate the path inside the cluster, the one your other applications will use, DNS resolution included. From your workstation, you only validate that the Pod serves content, the cluster network being bypassed. Start with the first.
Option 1: Test from a temporary Pod
This command creates a temporary Pod, runs wget, prints the result, then deletes the Pod:
The application answers. The nginx Service is reachable from any Pod in the namespace by its DNS name (nginx, or nginx.demo-app.svc.cluster.local).
To keep the answer in a file instead of reading it on screen, redirect the output of the command with >, as you would for any other command. For example, add > reponse.html at the end of the kubectl run command: the file is written on your workstation, not in the Pod, which is gone.
Option
Meaning
--rm
Deletes the Pod after execution
-i
Interactive mode (retrieves the output)
--restart=Never
Do not restart if the command fails
wget -qO-
Downloads and prints the content
Swipe to see more
Option 2: Port-forward (access from your workstation)
To reach nginx from your browser:
Forward the port locally
kubectlport-forwardsvc/nginx8080:80-ndemo-app
Output
Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80
Open http://localhost:8080 in your browser: you will see the nginx welcome page. The command stays in the foreground as long as it runs. Open a second terminal for the following commands, or stop it with Ctrl+C.
Step 6: Scale the application
For now, you have a single Pod. A replica is a copy of the application, hence a Pod: ask for three.
Go to 3 replicas
kubectlscaledeploymentnginx--replicas=3-ndemo-app
Output
deployment.apps/nginx scaled
Check that the new Pods start:
See the Pods
kubectlgetpods-ndemo-app
Output
NAME READY STATUS RESTARTS AGE
nginx-6d8867d6c-57bpf 1/1 Running 0 10s
nginx-6d8867d6c-lptvk 1/1 Running 0 10s
nginx-6d8867d6c-z2j62 1/1 Running 0 2m
Three Pods are now running. Check that the Service sees all of them:
The Service added the new Pods to its list of endpoints and spreads requests among them. Compare with step 3: you went from 1 to 3 Pods, and the Service address (10.96.17.210, or nginx.demo-app) did not move. This is what you expect from a stable access point when what stands behind it changes.
The same object handles scaling down. Go back to a single replica, then list the Pods again:
Go back to 1 replica
kubectlscaledeploymentnginx--replicas=1-ndemo-app
kubectlgetpods-ndemo-app
Two of the three Pods go to Terminating then disappear from the list, and only one remains Running. The ReplicaSet deletes the extra Pods, just as it had created two more: the number of Pods always follows the number of replicas requested. Go back to 3 with the same command before continuing.
Step 7: Observe the application
There are three sources of information, to query in this order when something is wrong. describe gives the configuration and the events of the object, logs gives what the application says, and the namespace events give what Kubernetes decided. Mixing up the three sends you looking in the wrong place.
See the details of the Deployment
describe is more verbose than get because it adds two things absent from a table: the full Pod template, that is, what the Deployment reproduces for each replica, and the list of recent events at the bottom of the output. When something is wrong, read these events first.
Full details
kubectldescribedeploymentnginx-ndemo-app
Output (excerpt)
Name: nginx
Namespace: demo-app
Labels: app=nginx
Selector: app=nginx
Replicas: 3 desired | 3 updated | 3 total | 3 available | 0 unavailable
2026/11/10 07:38:17 [notice] 1#1: start worker process 36
2026/11/10 07:38:17 [notice] 1#1: start worker process 37
2026/11/10 07:38:17 [notice] 1#1: start worker process 38
2026/11/10 07:38:17 [notice] 1#1: start worker process 39
The date and time at the start of each line are those of your startup, and the number of worker processes depends on the cores of your machine: your values will differ, the format is the same.
Shortcut: logs through the Deployment
kubectl also accepts the name of the Deployment:
Logs through the Deployment (shortcut)
kubectllogsdeployment/nginx-ndemo-app--tail=10
Output
Found 3 pods, using pod/nginx-6d8867d6c-z2j62
2026/11/10 07:38:17 [notice] 1#1: using the "epoll" event method
2026/11/10 07:38:17 [notice] 1#1: nginx/1.30.5
2026/11/10 07:38:17 [notice] 1#1: built by gcc 14.2.0 (Debian 14.2.0-19)
2026/11/10 07:38:17 [notice] 1#1: OS: Linux 6.12.116+deb13-amd64
2026/11/10 07:38:17 [notice] 1#1: start worker process 36
2026/11/10 07:38:17 [notice] 1#1: start worker process 37
2026/11/10 07:38:17 [notice] 1#1: start worker process 38
2026/11/10 07:38:17 [notice] 1#1: start worker process 39
Logs always come from a single Pod: kubectl picks one for you, as the first line announces.
See the namespace events
Events are the namespace's logbook: Kubernetes explains there why it acted. Sorting by .lastTimestamp makes the output chronological, which it is not by default.
You will find there the creation of the Pods, the scaling and any errors. Events are not kept forever: they expire after one hour by default, and an incident from the day before will no longer appear.
Declarative method (YAML file)
The declarative method means describing the desired state in a file, and letting Kubernetes reach it. As soon as you want to replay, review or share a configuration, describe the resources in YAML files versioned in Git.
Before reading this file, keep four YAML rules in mind. YAML is the format Kubernetes reads its manifests in. A pair is written key: value, with a space after the colon. Indentation expresses ownership: a line shifted by two spaces under a key belongs to that key. Use spaces, never tabs, which YAML rejects, and keep the same shift everywhere. A list is written with one dash per item. Finally, three dashes --- alone on a line separate several documents in the same file, here one per Kubernetes object.
The four rules in miniature
metadata:
name: nginx
labels:
app: nginx
ports:
- port: 80
- port: 443
---
kind: Service
Here, name and labels belong to metadata, and app belongs to labels. ports is a list of two items, then --- opens a second document. The basic YAML syntax lesson covers these rules in detail.
Here is the equivalent of what you created, in the state reached at the end of step 6: the namespace, three replicas and the Service. The file also declares the container port (containerPort: 80), which kubectl create deployment had not set: once applied, it therefore modifies the Pod template. The Deployment then replaces its Pods with new ones, under other names.
To apply this file, run the command below. The three objects already exist, since you created them in steps 1 to 3: kubectl updates them instead of creating them. Expect three long warnings, one per object: the output explains them right after.
Apply the configuration
kubectlapply-fdemo-app.yaml
Output
Warning: resource namespaces/demo-app is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
namespace/demo-app configured
Warning: resource deployments/nginx is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
deployment.apps/nginx configured
Warning: resource services/nginx is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
service/nginx configured
The word configured says the object existed and kubectl apply took it over: from then on, the file is authoritative. The three Warning messages are normal: you created these objects with create and expose, so without the kubectl.kubernetes.io/last-applied-configuration annotation where apply keeps the last applied configuration. kubectl adds it automatically, and the object then comes under declarative management.
To see the opposite case, delete the namespace, then apply the same file on a cluster where demo-app no longer exists:
Apply on an empty namespace
kubectldeletenamespacedemo-app
kubectlapply-fdemo-app.yaml
Output
namespace "demo-app" deleted
namespace/demo-app created
deployment.apps/nginx created
service/nginx created
The three lines now say created, because nothing existed, and no warning appears. The file alone is therefore enough to recreate the whole application identically.
Before an apply, kubectl diff -f demo-app.yaml shows what would change without applying anything: get into the habit of running it so you do not overwrite a change made by hand in the meantime. As long as the file and the cluster agree, the command prints nothing. It returns exit code 1 when it finds a difference and 0 otherwise, which is useful in a script.
The everyday gesture is to modify the file, then reapply it. Open demo-app.yaml, replace replicas: 3 with replicas: 2 in the Deployment, then compare the file with the cluster:
See what would change
kubectldiff-fdemo-app.yaml
Output (excerpt)
- generation: 1
+ generation: 2
...
- replicas: 3
+ replicas: 2
Lines preceded by - are the cluster state and those preceded by + are the state wanted by the file. The diff also prints a few header and context lines, which this excerpt omits. Then apply the file and look at the result:
Apply the change
kubectlapply-fdemo-app.yaml
kubectlgetpods-ndemo-app
Output
namespace/demo-app unchanged
deployment.apps/nginx configured
service/nginx unchanged
NAME READY STATUS RESTARTS AGE
nginx-5f4db8497d-2jqz6 1/1 Running 0 7s
nginx-5f4db8497d-9wbdb 1/1 Running 0 7s
Only the Deployment is configured: the namespace and the Service did not change, and kubectl says so with unchanged. Two Pods remain, although you typed no kubectl scale: the change is in the file, and it is the file that Git keeps. The names of your Pods will differ.
The choice between the two approaches depends on what you plan to do with the result.
Approach
When to use it
Imperative (kubectl create)
Learn, test quickly, debug
Declarative (kubectl apply -f)
As soon as you want to version, review, share, automate
Swipe to see more
Once you have taken up this reflex, the YAML file becomes the starting point of every change, and the cluster configuration can be read back in Git. A deployment is replayed identically, by you tomorrow or by a colleague.
What Kubernetes did in the background
Here is what happened when you ran these commands:
You created a Deployment, and Kubernetes created a ReplicaSet
The ReplicaSet created the Pods, and Kubernetes assigned each Pod to a node
Each node downloaded the image and started the nginx container
You created a Service, and Kubernetes registered the Pods matching the selector app=nginx
The Service received a stable IP, and its endpoints point to the Pods
You scaled the Deployment to three replicas, and the ReplicaSet created two more Pods
The Service updated its endpoints automatically
That is the Kubernetes model: you declare what you want, and Kubernetes takes care of making it happen and keeping it that way.
Clean up
To delete everything you created, delete the namespace:
Delete the namespace and its content
kubectldeletenamespacedemo-app
Output
namespace "demo-app" deleted
This command deletes all the resources in the namespace: Deployment, ReplicaSet, Service and Pods. Deletion is not instantaneous. The namespace stays in Terminating for a few seconds, and kubectl delete waits for this cleanup to finish before giving you back control. In the meantime, you cannot recreate a namespace with the same name.
That is the whole point of a dedicated namespace: if you break something while learning, delete it and start again.
Troubleshooting
Here are four failures you may meet while following this page. A blocked Deployment sends you to the Pod's events, a crashing Pod sends you to its logs, a silent Service sends you to its endpoints.
The Deployment stays at 0/1
A Deployment stuck at 0/1 does not say why: it only notes that its Pod is not ready. The reason lies one level down, in the Pod's events. First run these two commands, before changing anything.
See why the Pod does not start
kubectldescribedeploymentnginx-ndemo-app
kubectlgetevents-ndemo-app
What you see
What it means
Where to start
ErrImagePull, then ImagePullBackOff
the node cannot fetch the image
reread the name and tag: a typo gives exactly this error. Only then: private image without credentials, or unreachable registry
Pending with no image event
no node can host the Pod
insufficient resources, or a placement constraint
Swipe to see more
ImagePullBackOff is a symptom, not a cause: it says the download failed and that Kubernetes retries with growing delays. The cause is read in the events, and it is often a simple typo.
The Pod is in CrashLoopBackOff
CrashLoopBackOff means the container starts then stops, in a loop. Between two attempts, it is stopped: kubectl logs <pod-name> -n demo-app then shows the last run, the one that just failed. Start there.
Read the last run, the one that just failed
kubectllogs<pod-name>-ndemo-app
If the container has already restarted and is running again, the trace of the crash belongs to the previous run. The --previous option fetches it:
Read the previous run, if the container is running again
kubectllogs<pod-name>-ndemo-app--previous
If --previous answers previous terminated container ... not found, the container never restarted and the problem is not a crash. If it answers unable to retrieve container logs, that run is no longer kept: go back to kubectl logs without the option. The lesson read the cluster state shows both cases on a real failure.
Kubernetes spaces out successive restarts, up to five minutes of waiting. A Pod in CrashLoopBackOff for a long time can therefore seem stuck while it is waiting for its next attempt.
The Service does not answer
A Service that does not answer is rarely broken: it works, but it points to nothing. The diagnosis comes down to one check, which comes before any other.
Check the endpoints
kubectldescribeservicenginx-ndemo-app
Look at whether Endpoints is empty. If it is, no ready Pod matches the Service selector. Two causes share this symptom: labels that do not match the selector, which kubectl get pods --show-labels shows, or Pods that exist but are not ready yet, which the READY column of kubectl get pods shows.
The namespace stays in Terminating
This is normal, give it a few seconds: Kubernetes first deletes the content of the namespace. If it lasts several minutes, a resource refuses to be deleted, often because it carries a finalizer, a rule that blocks deletion until a cleanup task is finished.
Put it into practice
The guided lab takes up the demonstration of the lesson in the demo-app namespace of a kind cluster. You create the nginx Deployment with a single replica, on the digest-pinned image of the lesson, you expose it through a Service, then you scale it to three replicas. You then query the Service from a temporary client Pod, as in step 5, and you redirect the answer into ~/demo-app/reponse.html.
The validation reads the state of the cluster. It refuses a Deployment created with three replicas from the start, an unpinned image, a Service that counts fewer than three ready endpoints and a hand-typed answer, because it compares the file with the page that nginx really serves.
Key takeaways
A Deployment manages your Pods through a ReplicaSet: it creates them, watches them and recreates them if needed
A Service exposes your Pods and provides a stable address even when the Pods change
The Service targets Pods by labels, not through the Deployment: always check the Endpoints
A dedicated namespace lets you organize and clean up cleanly: if you break something while learning, delete it and start again
Pin image versions, tag and digest (nginx:1.30@sha256:… rather than nginx:latest)
Imperative commands are for learning: in production, switch to declarative (YAML), and run kubectl diff -f before kubectl apply -f
kubectl describe is the first reflex to understand what is going on: events at the bottom of the output
A container that crashes in a loop (CrashLoopBackOff) is read in its logs: kubectl logs --previous gives the previous run
Knowledge check
Seven questions about what you just handled, and above all about silent
failures: a Service that routes to nothing without raising an error, and
logs that seem empty while they belong to the previous run.
Knowledge check
Check what you have learned with this interactive quiz
7 questions
5 min
80% to pass
How it works
The timer starts when you click Start
Multiple choice, true/false and short answer questions
You can move between questions
Detailed results are shown at the end
Starts the quiz and the timer
⏱️--:--
0 / 7
Review
(0/0)
--:--
0%
0Correct
0To review
0:00Time
-Level
Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.