Before any commands or files, let us be clear about what we are trying to achieve and why a simple approach is not enough.

The old way

In the past, deploying meant renting a computer, logging in, copying your program onto it and starting it. That works for one program on one machine. But problems appear quickly.

• If the program crashes at night, nobody restarts it until someone notices.
• If more customers arrive, one machine is not enough, and adding machines by hand is slow.
• If you update the program, it stops for a moment, and users see errors.
• If the machine breaks, your program is gone until someone builds a new one.
• Every machine is a little different, so “it works on my laptop” often means “it breaks somewhere else”.

The Kubernetes way

Kubernetes is a free, open-source system that runs your programs on a group of computers and keeps them healthy for you. You do not tell it the steps to follow. Instead, you describe the end result you want, such as “run three copies of this program and make them reachable on the network”. Kubernetes then works tirelessly to make reality match your description, and to keep it that way when things break.

Ten small ideas carry this whole guide. Learn them once and every later step will make sense.

Only four things are required. None of them are hard to get, and most are free.

Choosing a cluster to learn on

Here is the whole trip in one picture. Each step will get its own chapter, but it helps to see where we are going.

flowchart LR
    CODE["Your code on your laptop"] --> BUILD["Build a container image"]
    BUILD --> REG["Image Registry"]
    YOU["You apply a manifest"] --> API
    subgraph CL["Kubernetes Cluster"]
        API["API Server"] --> DEP["Deployment"]
        DEP --> RS["ReplicaSet"]
        RS --> P1["Pod 1"]
        RS --> P2["Pod 2"]
        RS --> P3["Pod 3"]
        SVC["Service"] --> P1
        SVC --> P2
        SVC --> P3
    end
    REG -. images are pulled .-> P1
    REG -. images are pulled .-> P2
    REG -. images are pulled .-> P3
    USERS["Users"] --> SVC
    

The nine steps

Kubernetes does not run raw programs. It runs container images. So the first job is turning your app into one.

The recipe file

An image is built from a short text file, most often called a Dockerfile. It is a recipe with a few lines, each doing one job.

• Start from a base. Choose a ready-made image that already contains the language or system your app needs, such as one with the right version of your programming language.
• Copy in your code. Place your program files inside the image.
• Install what it needs. Add libraries or packages your program depends on.
• Say how to start it. Name the command that runs when a container begins, and note which port it listens on.

Then you ask your build tool to follow the recipe. It produces an image and stores it on your computer, ready to be tested.

Names and tags

Every image has a name and a tag, which is a label for its version, such as “1.0” or “2.3”. Together they look like “my-shop-web:1.0”. Tags are how you tell versions apart, so pick clear ones. Avoid the tag called “latest” for real work, because it means different things on different days and makes it impossible to know exactly what is running.

Making the image small and safe

• Use small base images. Less software inside means faster downloads and fewer things that can be attacked.
• Use multi-stage builds. Build your program in one stage, then copy only the finished result into a small final image, leaving compilers and tools behind.
• Do not include secrets. Passwords and keys must never be baked into an image, since anyone with the image can read them.
• Run as a normal user. Tell the image to run your program as a non-administrator user.
• Print logs to the screen. Write messages to standard output so that Kubernetes can collect them.

The nodes in your cluster need to download your image. A registry is the shared place where they find it.

Your image currently lives only on your laptop. The cluster’s nodes cannot see your laptop’s storage. So you upload, or push, the image to a registry, and later the nodes pull it down when they need to start a container.

Public or private?

A public image can be downloaded by anyone, so the cluster needs no special permission. A private image needs credentials. In Kubernetes you store those credentials in a special object and tell your Pods to use it when they pull. Real company code should almost always be in a private registry.

A shortcut for laptop clusters

Local tools such as minikube and kind can load an image straight from your computer into the cluster, skipping the registry. This is a handy shortcut while learning, but it does not exist on real clusters, so it is worth learning the registry route early.

A manifest is how you talk to Kubernetes. Once you understand its four-part shape, every manifest looks familiar.

Declarative: describe the result

There are two ways to give orders. In the imperative way you say each action: “start this”, “add one more”, “stop that”. In the declarative way you write the final picture you want, and hand it over. Kubernetes compares your picture with reality and changes whatever is different. Professionals prefer the declarative way, because the picture can be saved, reviewed and repeated.

The four parts of every manifest

Labels: the sticky notes that connect things

A label is a small tag with a name and a value, like “app” with the value “shop-web”. Kubernetes uses labels to connect objects. A Deployment says “manage the Pods that carry this label”. A Service says “send visitors to the Pods that carry this label”. Labels are the glue of Kubernetes, and a wrong label is the number one cause of “my Service reaches nothing”.

The Deployment is the star of your first app. It runs your Pods, keeps them alive and manages updates.

flowchart TB
    DEP["Deployment: wants 3 copies of image v1"] --> RS1["ReplicaSet for version 1"]
    RS1 --> A["Pod"]
    RS1 --> B["Pod"]
    RS1 --> C["Pod"]
    DEP -. keeps an old copy for rollback .-> RS0["Older ReplicaSet with 0 Pods"]
    

Why not create Pods directly?

You can create a bare Pod, but if it dies, nobody brings it back, and if its node fails, it is gone. A Deployment fixes both. It hires a middle manager called a ReplicaSet, whose only job is to keep the exact number of Pods you asked for. When you update the app, the Deployment creates a new ReplicaSet for the new version and gradually hands work over, keeping the old one around in case you need to go back.

What you write inside a Deployment

Pods come and go and their addresses change. A Service gives visitors one steady place to knock.

The problem a Service solves

Every Pod gets its own private address, but that address disappears with the Pod. If your Deployment replaces a Pod, the new one has a different address. Visitors and other apps cannot keep up with such changes. A Service provides a fixed name and a fixed address, watches which Pods currently match its label rule, and shares incoming traffic among them.

Choosing the type

Ports, explained simply

A Service has a port, which is the door number visitors knock on, and a target port, which is the door number of your container. They can differ. For example, visitors may use the normal web port 80 while your app listens on 8080 inside. The Service translates between them.

Names inside the cluster

Kubernetes also runs a small phone book, called DNS. Every Service gets a name in it. Other apps in the same namespace can simply use the Service’s name to reach it, without ever knowing an address. That is how your front-end will find your back-end later.

Trying it out safely

To peek at your app from your laptop without exposing it, you can use port-forwarding, a feature that creates a temporary private tunnel from a port on your computer to your Pod or Service. It is perfect for a first look and is closed the moment you stop it.

The moment of truth. Let us follow exactly what happens after you hand your manifests to the cluster.

sequenceDiagram
    participant You
    participant API as API Server
    participant DC as Deployment Controller
    participant SCH as Scheduler
    participant KUB as Kubelet
    participant REG as Registry
    You->>API: Apply the manifest
    API-->>DC: New Deployment saved
    DC->>API: Create ReplicaSet and Pods
    API-->>SCH: Pods need a node
    SCH->>API: Assign each Pod to a node
    API-->>KUB: Pod assigned to your node
    KUB->>REG: Pull the image
    REG-->>KUB: Image downloaded
    KUB->>KUB: Start the container
    KUB-->>API: Pod is running and ready
    

After applying, do not just hope. Learn to read the signs. Three questions solve almost every problem.

The three questions

Reading Pod statuses

Your app is live. Tomorrow you will change it. Kubernetes can swap versions while visitors keep being served.

The rolling update

To release a new version, you build and push a new image with a new tag, then change the image name in your Deployment and apply it again. Kubernetes notices that the Pod blueprint changed and starts a rolling update. Instead of switching everything at once, it swaps Pods a few at a time.

flowchart LR
    S1["Start: 3 Pods on v1"] --> S2["Add 1 Pod on v2 and wait until it is ready"]
    S2 --> S3["Remove 1 Pod on v1"]
    S3 --> S4["Add another Pod on v2"]
    S4 --> S5["Remove another Pod on v1"]
    S5 --> S6["Finish: 3 Pods on v2"]
    

Controlling the pace

Two settings decide how bold the update is. Max surge is how many extra Pods may be created above your normal count during the update. Max unavailable is how many Pods may be missing at once. By default each is a quarter of your Pods. A cautious team might allow no missing Pods at all, trading speed for safety.

Going back

If the new version turns out to be bad, you can ask the Deployment to undo the last change. It simply re-activates the previous ReplicaSet and rolls back the same gentle way. You can also view the history of revisions and return to a specific one.

Two of the biggest reasons people move to Kubernetes are handling more visitors and surviving failures. Both are one-line experiences.

Scaling by hand

To handle more visitors, raise the replica count in the Deployment. Kubernetes creates the extra Pods, schedules them, and adds them to the Service. To scale down, lower the count and extra Pods are retired gracefully. This can be done in seconds, without touching the app itself.

Scaling automatically

A feature called the Horizontal Pod Autoscaler watches how busy your Pods are and adjusts the replica count for you. For example, it can add Pods when average processor use climbs above a target and remove them when things calm down. It needs a small helper called the metrics server to read usage numbers, and it needs your Pods to declare resource requests so it can calculate a percentage.

Watching self-healing happen

A great first experiment: delete one of your running Pods on purpose. Within a moment, the ReplicaSet notices that the count is below what you asked for, and a fresh Pod appears. Visitors barely notice, since the Service simply stops sending traffic to the removed one and starts using the new one when it is ready.

Real apps need settings, passwords and sometimes data that survives restarts. Kubernetes has a place for each.

The golden rule: build once, configure anywhere

The same image should run in testing and in production, with only its settings changing. Never bake environment-specific values or secrets into the image. Put them in ConfigMaps and Secrets and let each environment supply its own.

Start with stateless

For your very first app, choose one that keeps no important data inside itself. It reads from a database or file service elsewhere and can be freely copied, moved and replaced. Stateful software such as databases is possible in Kubernetes, but it needs extra care around storage, identity and backups, so save it for your second or third project.

Kubernetes is powerful, but it is not free of cost. An honest view helps you decide when it is the right tool.

The trade-offs behind the choices

Managed versus self-run. A managed cluster from a cloud provider removes most of the operating chores, but costs money and ties you to that provider’s way of doing things. Running your own gives full control and demands full responsibility.

Simple app hosting versus Kubernetes. A basic hosting service can be far easier for a small website. Kubernetes shines when you have several services, need reliable updates, or expect growth.

Speed of learning versus depth. You can deploy a first app in an afternoon using just a Deployment and a Service. Mastering networking, security and storage takes months of practice.

Few big Pods versus many small ones. More, smaller replicas spread risk and scale smoothly, but each carries overhead. Find a balance that fits your app.

It is far easier to build good habits at the beginning than to fix bad ones later. Here are the essentials for your very first app.

A running app that nobody watches is a surprise waiting to happen. A few simple signals make problems visible early.

Alarms worth setting

• Pods stuck in Pending, image pull failures or crash loops for more than a few minutes.
• Restart counts rising quickly.
• Fewer ready Pods than the count you asked for.
• Memory use approaching the limit.
• Error rate or response time above your agreed target.

Patterns are solutions that many teams found reliable. Anti-patterns are traps many teams fell into.

Patterns that work

Traps to avoid

A few habits and a short checklist will save you hours of confusion.

Habits that pay off

• Test the image on your laptop first. Fix problems where they are easiest to see.
• Set readiness and liveness probes. They make updates safe and repairs automatic.
• Set resource requests and limits. Without them, scheduling and autoscaling cannot work well.
• Use clear, consistent labels. Names like app, version and team make everything easier to find and connect.
• Start with two or more replicas. One copy is a single point of failure.
• Log to standard output. Kubernetes and log tools can collect it without extra work.
• Handle shutdown politely. Let your app finish current requests when it is told to stop.
• Keep everything in version control. Files, not memory, are your source of truth.
• Clean up experiments. Delete test namespaces and cloud load balancers you no longer need, since they cost money.

Mistakes beginners make

Here is how this same journey looks in practice for different kinds of teams.

Quick answers to the questions beginners ask most often.

You began with a cake baked in your own kitchen. Now you know how to open a reliable shop for it.