We closed the previous lesson saying you already had a cluster, a CLI and the language of manifests, and that all that was missing was the patient. Here it is. This lesson introduces Rutas Norte S.L. in depth, the fictional company whose coach ticket sales platform we are going to deploy and operate on Kubernetes across the eleven remaining modules. It is not a decorative example: every concept you learn from now on will enter the stage because Rutas Norte needs it, and by the end of the course you will have a complete platform —secure, observable and autoscaled— built piece by piece. You will see the company's starting position, each of its six components, the target architecture, the map of which module contributes what, and the conventions we will always follow. And you will finish with the first real deployment: web-store running in your cluster and responding in your browser.

1. The company and its current problem
2. The six components of the platform
3. The target architecture on Kubernetes
4. Roadmap: what each module contributes
5. Project conventions
6. The first deployment: web-store in rutas-norte-dev
7. Why this pod is fragile

Rutas Norte S.L. is an intercity coach operator that sells its tickets online through the Rutas Norte platform. Thirteen people in the technical department, around 4,000 bookings a day on average and 25,000 on peak days.

Its current infrastructure:

• Two rented machines with Docker Compose. One serves the website and the API; the other, the database.
• Manual deployments: somebody connects over SSH, runs docker compose pull && docker compose up -d and crosses their fingers. There is a service outage of one to two minutes, so deployments only happen in the small hours of Tuesday.
• No self-healing: in March, the API container died at 02:40 from a memory leak and nobody noticed until 07:15. Four and a half hours with no ticket sales.
• No elasticity: at bank-holiday and holiday peaks, traffic multiplies sixfold. The answer so far has been to rent a machine sized for August and pay for it all twelve months.
• Secrets everywhere: the PostgreSQL password lives in a .env file that has been shared by email. That database contains the name, ID number, phone and email of every customer.
• No observability: logs are in files inside each container. Diagnosing a problem means going in over SSH and searching with grep.

The technical leadership has approved the migration to Kubernetes with four measurable goals: zero downtime on deployments, automatic recovery from failures, elastic capacity at the peaks and traceability and access control over personal data. Those four goals are, one by one, the syllabus ahead of you.

These names will stay with you throughout the course. Keep them exactly as they are.

• What it is: the public front end. An SPA served by nginx with the search results, the seat picker and the payment process.
• State: stateless. Any replica serves any request.
• Image: registry.rutasnorte.example/web-store:1.8.0
• Domain: www.rutasnorte.example
• What it needs from the cluster: several replicas, HTTP/HTTPS exposure to the outside world, injected configuration (the API URL varies per environment) and downtime-free updates.

• What it is: the REST API in Node.js. It checks seat availability, calculates prices, creates bookings and issues tickets. It is the heart of the business.
• State: stateless. All persistence lives in PostgreSQL and Redis.
• Image: registry.rutasnorte.example/bookings-api:2.4.0
• Domain: api.rutasnorte.example
• What it needs from the cluster: replicas, autoscaling by load, database credentials as a secret, health probes, resource limits and restricted access to the database.

• What it is: PostgreSQL 16 with the tables for bookings, customers, routes and departures.
• State: stateful. It is the system's critical component.
• Image: postgres:16
• What it needs from the cluster: persistent storage that survives the pod being recreated, a stable network identity, credentials managed as a secret, backups and a network policy that stops just anyone connecting to it.

• What it is: an in-memory cache of seat availability by departure and date. It absorbs most of the search queries and stops PostgreSQL being overwhelmed.
• State: stateful, but expendable. If it is lost, it is repopulated from the database; only performance degrades, and only for a few minutes.
• Image: redis:7.2-alpine
• What it needs from the cluster: a stable name, strict memory limits and eviction policy configuration.

• What it is: a background process that consumes a queue and sends booking confirmation emails and journey reminders.
• State: stateless, but it receives no inbound traffic: it does not need to be reachable from outside.
• Image: registry.rutasnorte.example/notifications-worker:1.2.0
• What it needs from the cluster: replicas scaled by queue length rather than by CPU, SMTP credentials as a secret, and a graceful shutdown so no send is lost halfway.

• What it is: a scheduled task that every night at 02:30 calculates the previous day's occupancy by line and departure and leaves a report for the commercial department.
• State: stateless, finite in execution: it starts, works for a few minutes and finishes.
• Image: registry.rutasnorte.example/occupancy-reports:1.0.3
• What it needs from the cluster: scheduled execution, retry control, a limit on concurrent runs and a history of results.

That table already contains a design lesson: the type of Kubernetes object you need follows from two questions —is it stateful? and does it receive traffic?— before you write a single line of YAML.

This is the destination we will reach by the end of module 11.

Points worth reading in the diagram:

• A single front door: the Ingress Controller terminates TLS and routes by domain to the matching Service.
• No component knows any IPs: everything communicates through the Service name, resolved by the cluster's internal DNS.
• bookings-postgres is the only one with a persistent disk, and it must only be reachable from bookings-api, the worker and the CronJob. That will be enforced with a NetworkPolicy in module 4.
• notifications-worker has no Service: nobody talks to it, it consumes work and goes out to talk to others.

This table is the course's contract: it says which piece of Rutas Norte we add or improve in each module.

These rules apply in every lesson. Adopt them from now on; they are also real-world good practice.

Throughout module 1 and much of module 2 we will work only in rutas-norte-dev.

Every object carries at least these three labels:

This enables queries like these, which are worth their weight in gold as the cluster grows:

The company's image registry is registry.rutasnorte.example. The project's most important rule when it comes to images:

Every version is published with a unique, immutable tag that is never reused. latest is forbidden in every environment.

The one we defined in the lesson Objects, YAML Manifests and the Declarative Model:

And the golden rule that goes with it: if a change is not in Git, it does not exist. No kubectl edit as a deployment method.

Enough theory. Let us deploy the first real piece of Rutas Norte.

Note that we created it with a manifest, not with kubectl create namespace. That is a deliberate decision: the namespace is part of the project's definition and must be in Git like everything else.

And now, the productivity tip from lesson 01-05, which will save you typing -n rutas-norte-dev hundreds of times:

A field-by-field review, leaning on what we have learned:

• apiVersion: v1 and kind: Pod: the Pod belongs to the core group, which is why it carries no group prefix.
• metadata.name: a unique name within the namespace.
• metadata.labels: the project's three labels. In module 2 they will be the ones the Service uses to find its pods.
• metadata.annotations: informational metadata, not queryable.
• spec.containers: a list. Here a single element, as will be usual.
• image: nginx:1.27-alpine: we use the public nginx image because registry.rutasnorte.example is a fictional registry and does not exist. Throughout the course, whenever an image from registry.rutasnorte.example appears, mentally substitute —and substitute in your cluster— its public equivalent. An explicit tag, never latest, in line with the project convention.
• ports: this is informational documentation; it opens nothing by itself. Real exposure will come with the Service (module 2).
• resources: requests is what the scheduler reserves in order to decide which node it fits on; limits is the ceiling the kubelet enforces. We will study them thoroughly in module 3, but it is worth setting them from day one.

You are watching, live, the walkthrough from the lesson Kubernetes Architecture: Pending while the scheduler picks a node, ContainerCreating while the kubelet pulls the image and prepares the networking, Running when the container is alive. Stop it with Ctrl+C.

The four events tell the whole story: the scheduler assigned a node, and then the kubelet obtained the image, created the container and started it. Exactly the division of responsibilities we studied.

The pod has the IP 10.244.0.21, but that IP only exists inside the cluster. To reach it from your machine we use port-forward:

Open http://localhost:8080 in your browser: you will see the nginx welcome page. In Rutas Norte, that would be the ticket store's home page. Leave the command running while you test and stop it with Ctrl+C.

From another terminal you can also check it without a browser:

Congratulations: you have just deployed the first Rutas Norte component on Kubernetes.

Before celebrating too much, let us run the experiment that gives module 2 its meaning.

It has vanished and it does not come back. Compare that with what we said in the concepts lesson: a loose pod has no controller watching it. Nobody runs a reconciliation loop over it, because the desired state you declared was literally "let this pod exist", and by deleting it you also deleted that declaration.

The four problems with a loose pod:

The solution is the hierarchy you already know from the conceptual map: Deployment → ReplicaSet → Pod. A Deployment declares "I want 3 replicas of this image", the ReplicaSet keeps them alive come what may, and a Service gives them a stable name.

Recreate the pod to leave the cluster as it was and close the module with the platform up and running:

• Applying in the wrong namespace. If kubectl get pods shows nothing, check the namespace with kubectl config view --minify | grep namespace or use -A. Declaring metadata.namespace explicitly in every manifest, as we do here, removes the problem at the root.
• Using registry.rutasnorte.example literally. It is a fictional registry: it does not exist. The pod would sit in ImagePullBackOff. In the practical exercises always use the equivalent public image (nginx, postgres, redis, node).
• Believing ports.containerPort exposes the pod. It does nothing by itself: it is documentation. Real access comes with port-forward (for testing), a Service (module 2) or an Ingress (module 4).
• Settling for port-forward as the solution. It is a single-user debugging tool, tied to your terminal. It is never a way to expose a service.
• Creating loose pods and getting used to it. This has been a deliberate exercise to understand the fragility. From module 2 onwards, everything goes in Deployments.
• Forgetting resources. Without requests, the scheduler cannot plan properly; without limits, a runaway container can take down its neighbours. Set them from the start even if the tuning comes later.
• Tip: create the repository with the k8s/ structure right now and make a commit with namespace.yaml and web-store-pod.yaml. Working this way from the very first lesson is the difference between finishing the course with a reproducible platform and finishing with a cluster full of things nobody knows how were created.

Without writing any manifest, complete a table with the six Rutas Norte components and, for each one, answer: (a) is it stateful?, (b) does it receive inbound traffic and from where?, (c) which Kubernetes object will govern it?, and (d) what would happen today, with Docker Compose, if the machine hosting it were shut down? Then justify in three lines why redis-cache and bookings-postgres, both being "stateful", get very different treatment.

Following every project convention, create the manifest k8s/base/redis-cache-pod.yaml for a redis-cache pod in rutas-norte-dev with the public image redis:7.2-alpine, port 6379, the project's three labels and requests of 50m of CPU and 64Mi of memory. Then:

1. Validate it without touching the cluster and apply it.
2. Check that it is Running and find out its IP and its node.
3. Get into the container and check that Redis responds by running redis-cli ping.
4. Show only the Rutas Norte platform pods using the common label.

1. Simulate an application crash by killing the main process of the web-store container with kubectl exec, and watch what happens with --watch. Does the container come back? Does the RESTARTS counter change? Does the pod's IP change?
2. Now delete the whole pod with kubectl delete pod and watch again. Does it come back?
3. Explain the difference between the two cases, stating which component acts in each.
4. Write in two sentences which object you would need for the second case to also recover on its own.

Solution 1

redis-cache and bookings-postgres get different treatment because Redis's state is rebuildable: if it is lost, it is repopulated from the database and only performance degrades. PostgreSQL's state is the business's source of truth: losing it means losing bookings and customers' personal data. That is why PostgreSQL demands persistent storage, a stable identity, backups and network isolation, whereas Redis only needs a memory limit and an eviction policy.

Solution 2

Solution 3

The container does come back: RESTARTS goes from 0 to 1 and the pod's IP does not change, because it is the same pod. The one that recovers it is the kubelet, applying the restartPolicy: Always a pod has by default. The kubelet restarts containers inside an existing pod.

The pod does not come back. There is no controller watching over its existence.

3. The difference lies in who acts and on what: the kubelet watches the containers inside the pods assigned to it and restarts them if they die, but it cannot recreate a pod that no longer exists as an object in the API. Recreating pods is the job of a kube-controller-manager controller, and a loose pod has none associated with it: by deleting it, you deleted the desired state itself.

4. You need a Deployment, which creates a ReplicaSet whose controller permanently maintains the declared number of replicas. With it, the desired state stops being "let this specific pod exist" and becomes "let N pods with these characteristics exist", so deleting one immediately triggers the creation of another.

You now know the project that gives the whole course its meaning. Rutas Norte S.L. is a company with entirely real problems —overnight outages with no response, demand peaks on bank holidays and in the holiday season, deployments with service downtime and badly protected customer personal data— and its platform is made up of six pieces with clearly different needs: two stateless front ends, a critical stateful database, an expendable cache, a worker with no inbound traffic and a scheduled nightly task. You have the target architecture, the map of which module contributes what, and the conventions —namespaces per environment, the labelling scheme, immutable image tags and a k8s/ structure versioned in Git— that we will apply without exception.

And, above all, you have already deployed your first component: web-store running in rutas-norte-dev, inspected with get, describe and logs, and visible in your browser through port-forward. You have also seen its weak spot first-hand: a loose pod that, once deleted, never comes back.

With this you close module 1. You know what Kubernetes is, how it is built, what every term means, you have a working cluster, you have command of kubectl and you understand the declarative model. Module 2, Core Kubernetes Components, starts exactly where this lesson ends: we will turn that fragile pod into a Deployment with several replicas that recovers on its own, we will first learn what exactly a Pod is inside and how a ReplicaSet keeps it alive, and we will give web-store and bookings-api a stable address with Services. The Rutas Norte platform really starts to take shape.