DEV Community: B.R.O.L.Y

Mastering Kubernetes Step by Step Part 2 Pods and Containers Explained

B.R.O.L.Y — Fri, 24 Oct 2025 13:05:25 +0000

Hands On: Getting Started

Let's dive right in and get practical experience before explaining the theory. First, I recommend installing Docker Desktop so we can run example clusters locally on a single node.

Once installed, make sure to check the settings and enable the Kubernetes cluster option. After that, we'll use kubectl, the command-line interface for Kubernetes (we'll cover this in detail later).

$ kubectl get pods
NAME                                READY   STATUS    RESTARTS   AGE
nginx-deployment-66b6c48dd5-8xqmk   1/1     Running   0          2d
nginx-deployment-66b6c48dd5-k9pzx   1/1     Running   0          2d
redis-master-f46ff57fd-7jq8w        1/1     Running   0          5d

Now you have a Kubernetes cluster running on your laptop with multiple pods across multiple namespaces.

Understanding Pods

Kubernetes uses pods as its fundamental deployment unit for several important reasons: they provide an abstraction layer, enable resource sharing, add essential features, enhance scheduling capabilities, and much more.

Every application runs inside a pod on Kubernetes. Here's what that means in practice:

When you deploy an app, you deploy it in a Pod
When you terminate an app, you terminate its Pod
When you scale an app up, you add more Pods
When you scale an app down, you remove Pods
When you update an app, you replace Pods with new ones

Pods as an Abstraction Layer

Pods abstract away the complexity of different workload types. This powerful design means you can run containers, VMs, serverless functions, and WebAssembly apps inside pods, and Kubernetes treats them all the same way.

The benefits of this abstraction:

Kubernetes can focus on deploying and managing Pods without needing to understand what's running inside them
Different types of workloads can run side-by-side on the same cluster
All workloads leverage the full power of the declarative Kubernetes API
Every workload benefits from Pod features like health checks, restart policies, and resource limits

How different workloads use Pods:

Containers and WebAssembly apps work directly with standard Pods, standard workload controllers, and standard runtimes. However, serverless functions and VMs need additional components:

Serverless functions run in standard Pods but require frameworks like Knative to extend the Kubernetes API with custom resources and controllers
Virtual machines need tools like KubeVirt to extend the API and run VMs as pod-like resources (called VirtualMachineInstances or VMIs)

The diagram above shows four different workload types running on the same cluster. Each workload is wrapped in a Pod (or VMI), managed by a controller, and uses a standard runtime interface.

What Pods add to your workloads:

Resource sharing between containers
Advanced scheduling capabilities
Application health probes
Restart policies
Security policies
Termination control
Volume management

How Pods Enable Resource Sharing

A Pod can run one or more containers, and all containers within the same Pod share the Pod's execution environment. This shared environment includes:

Shared filesystem and volumes (mount namespace)
Shared network stack (network namespace) - all containers share the same IP address
Shared memory (IPC namespace)
Shared process tree (PID namespace)
Shared hostname (UTS namespace)

Real-world example:

Imagine a Pod running at IP address 10.0.10.15 with two containers:

A main application container listening on port 8080
A sidecar container listening on port 5005

External clients access both containers using the Pod's single IP address (10.0.10.15), but on different ports. Inside the Pod, the containers can communicate with each other using localhost since they share the same network namespace.

Both containers can also mount the same volume to share data. For example, the sidecar might sync static content from a Git repository and store it in a shared volume, while the main container reads that content and serves it as a web page.

Pods and Scheduling

Kubernetes guarantees that all containers in the same Pod will be scheduled to the same cluster node. However, you should only group containers in the same Pod if they truly need to share resources like memory, volumes, or networking.

Important principle: If you just want two applications to run on the same node (without resource sharing), place them in separate Pods and use scheduling features to co-locate them.

Advanced Scheduling Features

Pods provide powerful scheduling capabilities:

1. Node Selectors

The simplest way to control Pod placement. You provide a list of node labels, and the scheduler only assigns the Pod to nodes that have all those labels.

nodeSelector:
  disktype: ssd
  environment: production

2. Affinity and Anti-Affinity

More powerful than node selectors, these rules give you fine-grained control over Pod placement.

The basics:

Affinity rules attract Pods to specific nodes or other Pods
Anti-affinity rules repel Pods away from specific nodes or other Pods
Hard rules (requiredDuringScheduling) must be satisfied - the Pod won't schedule if they can't be met
Soft rules (preferredDuringScheduling) are preferences - the scheduler tries to honor them but will still schedule the Pod if it can't

Node affinity example:

This works like a node selector - you provide labels, and the scheduler assigns the Pod only to nodes with those labels.

Pod affinity example:

With Pod affinity, you provide labels of other Pods, and the scheduler places your Pod on nodes that are already running Pods with those labels. This is useful when you want related services to run close together for better performance.

Anti-affinity example:

Anti-affinity ensures your Pods spread out. For example, you might use anti-affinity to ensure database replicas run on different nodes for high availability.

3. Topology Spread Constraints

These rules help you distribute Pods evenly across failure domains like zones, regions, or nodes to improve reliability.

4. Resource Requests and Limits

You can specify how much CPU and memory your Pod needs (requests) and the maximum it can use (limits). The scheduler uses this information to place Pods on nodes with sufficient resources.

Deploying Pods

Deploying a Pod involves a carefully orchestrated series of steps across multiple Kubernetes components:

Define the Pod in a YAML manifest file
Post the manifest to the API server
The request is authenticated and authorized
The Pod spec is validated
The scheduler filters nodes based on nodeSelectors, affinity and anti-affinity rules, topology spread constraints, resource requirements and limits, and more
The Pod is assigned to a healthy node meeting all requirements
The kubelet on the node watches the API server and notices the Pod assignment
The kubelet downloads the Pod spec and asks the local container runtime to start it
The kubelet monitors the Pod status and reports status changes back to the API server

If the scheduler can't find a suitable node, it marks the Pod as pending.

Deploying a Pod is an atomic operation. This means a Pod only starts servicing requests when all its containers are up and running.

Pod Deployment Flow

This diagram shows the complete journey from running a kubectl command to having a Pod running on a node. Each component plays a specific role in ensuring the Pod is deployed correctly and securely.

Pod Lifecycle

Pods are designed to be mortal and immutable.

Mortal means you create a Pod, it executes a task, and then it terminates. Once it completes, it gets deleted and cannot be restarted. The same is true if it fails — it gets deleted and cannot be restarted.

Immutable means you cannot modify them after they're deployed. This can be a huge mindset change if you're from a traditional background where you regularly patched live servers and logged on to them to make fixes and configuration changes. If you need to change a Pod, you create a new one with the changes, delete the old one, and replace it with the new one. If a Pod needs to store data, you should attach a volume and store the data in the volume so it's not lost when the Pod is deleted.

A Typical Pod Lifecycle

You define a Pod in a declarative YAML object that you post to the API server. It goes into the pending phase while the scheduler finds a node to run it on. Assuming it finds a node, the Pod gets scheduled, and the local kubelet instructs the container runtime to start its containers. Once all of its containers are running, the Pod enters the running phase. It remains in the running phase indefinitely if it's a long-lived Pod, such as a web server.

If it's a short-lived Pod, such as a batch job, it enters the succeeded state as soon as all containers complete their tasks.

A note on running VMs on Kubernetes: VMs are designed as mutable immortal objects. For example, you can restart them, change their configurations, and even migrate them. This is very different from the design goals of Pods, which is why KubeVirt wraps VMs in a modified Pod-like resource called a VirtualMachineInstance (VMI) and manages them using custom workload controllers.

Restart Policies

Earlier, we said Pods augment apps with restart policies. However, these policies apply to individual containers, not the actual Pod.

Let's consider some scenarios:

You use a Deployment controller to schedule a Pod to a node, and the node fails. When this happens, the Deployment controller notices the failed node, deletes the Pod, and replaces it with a new one on a surviving node. Even though the new Pod is based on the same Pod spec, it has a new UID, a new IP address, and no state from the previous Pod.

The same thing happens when nodes evict Pods during node maintenance or due to resource constraints — the evicted Pod is deleted and replaced with a new one on another node.

This pattern even applies during scaling operations, updates, and rollbacks:

Scaling down deletes Pods
Scaling up creates new Pods
Updates replace old Pods with new ones

The key takeaway: Anytime we say we're "updating" or "restarting" Pods, we really mean replacing them with new ones.

Although Kubernetes can't restart Pods, it can definitely restart containers. This is always done by the local kubelet and governed by the spec.restartPolicy field, which can be set to:

Always - Always attempt to restart a failed container
Never - Never attempt to restart a container
OnFailure - Only restart if the container fails (not if it completes successfully)

The policy is Pod-wide, meaning it applies to all containers in the Pod except for init containers (more on those later).

Choosing the Right Restart Policy

The restart policy you choose depends on the nature of your application:

Long-lived containers host apps such as web servers, databases, and message queues that run indefinitely. If they fail, you want to restart them, so you'll typically use the Always restart policy.

apiVersion: v1
kind: Pod
metadata:
  name: web-server
spec:
  restartPolicy: Always
  containers:
  - name: nginx
    image: nginx:1.21

Short-lived containers typically run batch-style workloads that execute a task through to completion. Most of the time, you're happy when they complete successfully, and you only want to restart them if they fail. As such, you'll probably use the OnFailure restart policy. If you don't care whether they fail or succeed, use the Never policy.

apiVersion: v1
kind: Pod
metadata:
  name: batch-job
spec:
  restartPolicy: OnFailure
  containers:
  - name: data-processor
    image: batch-processor:1.0

Remember: Kubernetes never restarts Pods — when they fail, get scaled, or get updated, Kubernetes always deletes old Pods and creates new ones. However, Kubernetes can restart individual containers within a Pod on the same node.

Static Pods vs Controllers

There are two ways to deploy Pods:

Directly via a Pod manifest (rare)
Indirectly via a workload resource and controller (most common)

Static Pods

Deploying directly from a Pod manifest creates a static Pod that cannot self-heal, scale, or perform rolling updates. This is because static Pods are only managed by the kubelet on the node they're running on, and kubelets are limited to restarting containers on the same node. If the node fails, the kubelet fails as well and cannot do anything to help the Pod.

Controller-Managed Pods

On the flip side, Pods deployed via workload resources (like Deployments, StatefulSets, or DaemonSets) get all the benefits of being managed by a highly available controller that can:

Restart Pods on other nodes if a node fails
Scale Pods when demand changes
Perform advanced operations such as rolling updates and versioned rollbacks

The local kubelet can still attempt to restart failed containers, but if the node fails or gets evicted, the controller can restart the Pod on a different node.

The controller runs in the Kubernetes control plane and constantly watches the state of your Pods. If reality doesn't match your desired state, it takes action to fix it.

The Pod Network

Every Kubernetes cluster runs a pod network and automatically connects all Pods to it. It's usually a flat Layer 2 overlay network that spans every cluster node and allows every Pod to talk directly to every other Pod, even if the remote Pod is on a different cluster node.

The pod network is implemented by a third-party plugin that interfaces with Kubernetes and configures the network via the Container Network Interface (CNI).

You choose a network plugin at cluster build time, and it configures the Pod network for the entire cluster. Many plugins exist, each with its own pros and cons. However, at the time of writing, Cilium is the most popular and implements advanced features such as security policies and observability.

How the Pod Network Works

The Pod network creates a unified network space where every Pod gets its own unique IP address, and all Pods can communicate directly without NAT (Network Address Translation).

Key characteristics:

Each Pod gets a unique IP from the pod network CIDR range (e.g., 10.244.0.0/16)
Pods can communicate with any other Pod using its IP address
The pod network spans all nodes in the cluster
Node IPs (192.168.x.x) are separate from Pod IPs (10.244.x.x)

Network Configuration Example

When a Pod is created, the CNI plugin performs these steps:

Allocates an IP address from the pod network range
Creates a virtual ethernet pair (veth pair) - one end in the Pod's network namespace, one end on the node
Configures routing so the Pod can reach other Pods and external networks
Sets up network policies if defined (firewall rules for Pod-to-Pod traffic)

Real-world example:

Imagine you have a three-tier application:

Frontend Pods (10.244.1.x) on Node 1
Backend API Pods (10.244.2.x) on Node 2
Database Pods (10.244.3.x) on Node 3

The frontend Pods can directly call the backend API using its Pod IP (10.244.2.8:8080) even though they're on different physical nodes. The CNI plugin handles all the routing transparently using overlay networking (typically VXLAN or similar encapsulation).

The diagram above shows three nodes running five Pods. All five Pods are connected to the pod network and can communicate with each other. You can also see the Pod network spanning all three nodes.

Important distinction: The network is only for Pods, not nodes. As shown in the diagram, you can connect nodes to multiple different networks (management network, storage network, etc.), but the Pod network spans them all, creating a unified communication layer for your applications.

Kubernetes has two main patterns for multi-container Pods: init containers and sidecar containers. Let's quickly explain each.

Multi-container Pods

Multi-container Pods are a powerful pattern and very popular in real-world deployments.

According to microservices design patterns, every container should have a single clearly defined responsibility. For example, an application that syncs content from a repository and serves it as a web page has two distinct responsibilities:

Sync the content
Serve the web page

You should design this app with two microservices and give each one its own container — one container responsible for syncing the content and the other responsible for serving it. We call this separation of concerns, or the single responsibility principle, and it keeps containers small and simple, encourages reuse, and makes troubleshooting easier.

Most of the time, you'll put application containers in their own Pods and they'll communicate over the network. However, sometimes putting them in the same Pod is beneficial. Sticking with the sync and serve example, putting the containers in the same Pod allows the sync container to pull content from a remote system and store it in a shared volume where the web container can read it and serve it.

Kubernetes has two main patterns for multi-container Pods: init containers and sidecar containers.

Multi-container Pods: Init Containers

Init containers are a special type of container defined in the Kubernetes API. You run them in the same Pod as application containers, but Kubernetes guarantees they'll start and complete before the main app container starts. It also guarantees they'll only run once.

The purpose of init containers is to prepare and initialize the environment so it's ready for application containers.

Real-world Examples

Example 1: Waiting for a Service

You have an application that should only start when a remote API is accepting connections. Instead of complicating the main application with the logic to check the remote API, you run that logic in an init container in the same Pod. When you deploy the Pod, the init container comes up first and sends requests to the remote API waiting for it to respond. While this is happening, the main app container cannot start. However, as soon as the remote API accepts a request, the init container completes, and the main app container starts.

Example 2: Content Preparation

You have another application that needs a one-time clone of a remote repository before starting. Again, instead of bloating and complicating the main application with the code to clone and prepare the content (knowledge of the remote server address, certificates, auth, file sync protocol, checksum verifications, etc.), you implement that in an init container that is guaranteed to complete the task before the main application container starts.

Init Container Lifecycle

A drawback of init containers is that they're limited to running tasks before the main app container starts. For something that runs alongside the main app container, you need a sidecar container.

Multi-container Pods: Sidecars

Sidecar containers are regular containers that run at the same time as application containers for the entire lifecycle of the Pod.

Unlike init containers, sidecars are not a special resource in the Kubernetes API — we're currently using regular containers to implement the sidecar pattern. Work is in progress to formalize the sidecar pattern in the API, but at the time of writing, it's still an early alpha feature.

The job of a sidecar container is to add functionality to an app without having to implement it in the actual app. Common examples include sidecars that:

Scrape and ship logs
Sync remote content
Broker connections
Transform or munge data
Provide encryption and decryption

They're also heavily used by service meshes where the sidecar intercepts network traffic and provides traffic encryption and telemetry.

The figure below shows a multi-container Pod with a main app container and a service mesh sidecar. The sidecar intercepts all network traffic and provides encryption and decryption. It also sends telemetry data to the service mesh control plane.

Experimentation

Basic Pod Manifest

A typical Pod manifest file looks like this:

apiVersion: v1
kind: Pod
metadata:
  name: hello-pod
  labels:
    zone: prod
    version: v1
spec:
  containers:
  - name: hello-ctr
    image: nigelpoulton/k8sbook:1.0
    ports:
    - containerPort: 8080
    resources:
      limits:
        memory: 128Mi
        cpu: 0.5

Let's break down each section:

kind: Tells Kubernetes what type of object you're defining. This one defines a Pod, but if you were defining a Deployment, the kind field would say Deployment.
apiVersion: Tells Kubernetes what version of the API to use when creating the object. This manifest uses the v1 version of the API.
metadata: Names the Pod hello-pod and gives it two labels. You'll use labels in future chapters to connect the Pod to a Service for networking.
spec: Where most of the action happens. This example defines a single-container Pod with an application container called hello-ctr. The container is based on the nigelpoulton/k8sbook:1.0 image, listens on port 8080, and tells the scheduler it needs a maximum of 128MB of memory and half a CPU.

To make it a multi-container Pod, you simply add more containers below the spec.containers section.

Deploying Pods from a Manifest File

Run the following kubectl apply command to deploy the Pod. The command sends the pod.yml file to the API server defined in the current context of your kubeconfig file. It also attaches credentials from your kubeconfig file.

$ kubectl apply -f pod.yml
pod/hello-pod created

Although the output says the Pod is created, it might still be pulling the image and starting the container.

Run a kubectl get pods to check the status:

$ kubectl get pods
NAME        READY   STATUS              RESTARTS   AGE
hello-pod   0/1     ContainerCreating   0          9s

The Pod in the example isn't fully created yet — the READY column shows zero containers ready, and the STATUS column shows why.

Note: Kubernetes automatically pulls (downloads) images from Docker Hub. To use another registry, just add the registry's URL before the image name in the YAML file.

Once the READY column shows 1/1 and the STATUS column shows Running, your Pod will be running on a healthy cluster node and monitored by the node's kubelet.

You'll see how to connect to the app and test it in future chapters.

Inspecting Pods

You've already run a kubectl get pods command and seen that it returns a single line of basic info. However, the following flags provide much more information:

-o wide: Gives a few more columns but is still a single line of output
-o yaml: Gets you everything Kubernetes knows about the object

The following example shows the output of kubectl get pods with the -o yaml flag. The output is truncated, but notice how it's divided into two main parts:

spec: Shows the desired state of the object
status: Shows the observed state

$ kubectl get pods hello-pod -o yaml
apiVersion: v1
kind: Pod
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","kind":"Pod"...}
  name: hello-pod
  namespace: default
spec:                           # Desired state
  containers:
  - image: image-name
    imagePullPolicy: IfNotPresent
    name: hello-ctr
    ports:
    - containerPort: 8080
      protocol: TCP
    resources:
      limits:
        cpu: 500m
        memory: 128Mi
  restartPolicy: Always
status:                         # Observed state
  conditions:
  - lastProbeTime: null
    lastTransitionTime: "2024-01-03T18:21:51Z"
    status: "True"
    type: Initialized
  - lastProbeTime: null
    lastTransitionTime: "2024-01-03T18:22:05Z"
    status: "True"
    type: Ready
  containerStatuses:
  - containerID: containerd://abc123...
    image: image-name
    name: hello-ctr
    ready: true
    state:
      running:
        startedAt: "2024-01-03T18:22:04Z"

kubectl describe

Another great command is kubectl describe. This gives you a nicely formatted overview of an object, including lifecycle events.

$ kubectl describe pod hello-pod
Name:         hello-pod
Namespace:    default
Labels:       version=v1
              zone=prod
Status:       Running
IP:           10.1.0.103
Containers:
  hello-ctr:
    Container ID:   containerd://ec0c3e...
    Image:          image-name
    Port:           8080/TCP
    State:          Running
      Started:      Wed, 03 Jan 2024 18:22:04 +0000
    Ready:          True
Conditions:
  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True
Events:
  Type    Reason     Age    From               Message
  ----    ------     ----   ----               -------
  Normal  Scheduled  5m30s  default-scheduler  Successfully assigned default/hello-pod to node-1
  Normal  Pulling    5m30s  kubelet            Pulling image "nigelpoulton/k8sbook:1.0"
  Normal  Pulled     5m8s   kubelet            Successfully pulled image "nigelpoulton/k8sbook:1.0"
  Normal  Created    5m8s   kubelet            Created container hello-ctr
  Normal  Started    5m8s   kubelet            Started container hello-ctr

kubectl logs

You can use the kubectl logs command to pull the logs from any container in a Pod. The basic format of the command is kubectl logs <pod>.

If you run the command against a multi-container Pod, you automatically get the logs from the first container in the Pod. However, you can override this by using the --container flag and specifying the name of the container you want the logs from. If you're unsure of the names of containers or the order they appear in a multi-container Pod, just run a kubectl describe pod <pod> command. You can get the same info from the Pod's YAML file.

The following YAML shows a multi-container Pod with two containers. The first container is called app, and the second is called syncer. Running kubectl logs against this Pod without specifying the --container flag will get you the logs from the app container.

apiVersion: v1
kind: Pod
metadata:
  name: logtest
spec:
  containers:
  - name: app                    # First container (default)
    image: nginx
    ports:
    - containerPort: 8080
  - name: syncer                 # Second container
    image: image-name
    volumeMounts:
    - name: html
      mountPath: /tmp/git
  volumes:
  - name: html
    emptyDir: {}

You'd run the following command if you wanted the logs from the syncer container. Don't run this command, as you haven't deployed this Pod yet.

$ kubectl logs logtest --container syncer

kubectl exec

The kubectl exec command is a great way to execute commands inside running containers.

You can use kubectl exec in two ways:

Remote command execution
Exec session

Remote command execution lets you send commands to a container from your local shell. The container executes the command and returns the output to your shell.

An exec session connects your local shell to the container's shell and is the same as being logged on to the container.

Let's look at both, starting with remote command execution.

Run the following command from your local shell. It's asking the first container in the hello-pod Pod to run a ps command.

$ kubectl exec hello-pod -- ps
PID   USER     TIME  COMMAND
  1   root     0:00  node ./app.js
 17   root     0:00  ps

The container executed the ps command and displayed the result in your local terminal.

The format of the command is kubectl exec <pod> -- <command>, and you can execute any command installed in the container. By default, commands execute in the first container in a Pod, but you can override this with the --container flag.

Try running the following command:

$ kubectl exec hello-pod -- curl localhost:8080
OCI runtime exec failed: exec failed: unable to start container process:
exec: "curl": executable file not found in $PATH

This one failed because the curl command isn't installed in the container.

Let's use kubectl exec to get an interactive exec session to the same container. This works by connecting your terminal to the container's terminal, and it feels like you're logged on to the container.

Run the following command to create an exec session to the first container in the hello-pod Pod. Your shell prompt will change to indicate you're connected to the container's shell.

$ kubectl exec -it hello-pod -- sh
/#

The -it flag tells kubectl exec to make the session interactive by connecting your shell's STDIN and STDOUT streams to the STDIN and STDOUT of the first container in the Pod. The sh command starts a new shell process in the session, and your prompt will change to indicate you're now inside the container.

Run the following commands from within the exec session to install the curl binary and then execute a curl command:

/# apk add curl
fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/main/x86_64/APKINDEX.tar.gz
fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/community/x86_64/APKINDEX.tar.gz
(1/5) Installing ca-certificates (20230506-r0)
(2/5) Installing brotli-libs (1.0.9-r14)
(3/5) Installing libunistring (1.1-r1)
(4/5) Installing libidn2 (2.3.4-r1)
(5/5) Installing curl (8.1.2-r0)
OK: 12 MiB in 20 packages

/# curl localhost:8080
<html>
  <head>
    <title>Hello from Kubernetes!</title>
  </head>
  <body>
    <h1>Hello from Kubernetes Storage!</h1>
  </body>
</html>

Making changes like this to live Pods is an anti-pattern, as Pods are designed as immutable objects. However, it's OK for demonstration purposes like this.

Pod Hostnames

Pods get their names from their YAML file's metadata.name field, and Kubernetes uses this as the hostname for every container in the Pod.

If you're following along, you'll have a single Pod deployed called hello-pod. You deployed it from the following YAML file that sets the Pod name as hello-pod:

apiVersion: v1
kind: Pod
metadata:
  name: hello-pod    # Pod hostname - inherited by all containers
  labels:
    zone: prod
    version: v1

Run the following command from inside your existing exec session to check the container's hostname. The command is case-sensitive.

/# env | grep HOSTNAME
HOSTNAME=hello-pod

As you can see, the container's hostname matches the name of the Pod. If it was a multi-container Pod, all containers would have the same hostname.

Because of this, you should ensure that Pod names are valid DNS names (a-z, 0-9, the minus and period signs).

Type exit to quit your exec session and return to your local terminal.

Check Pod Immutability

Pods are designed as immutable objects, meaning you shouldn't change them after deployment.

Immutability applies at two levels:

Object immutability (the Pod)
App immutability (containers)

Kubernetes handles object immutability by preventing changes to a running Pod's configuration. However, Kubernetes can't always prevent you from changing the app and filesystem in containers. You're responsible for ensuring containers and their apps are stateless and immutable.

The following example uses kubectl edit to edit a live Pod object. Try changing any of these attributes:

Pod name
Container name
Container port
Resource requests and limits

You'll find that Kubernetes prevents most changes to running Pods, enforcing immutability at the object level.

Resource Requests and Resource Limits

Kubernetes lets you specify resource requests and resource limits for each container in a Pod.

Requests are minimum values
Limits are maximum values

Consider the following snippet from a Pod YAML:

resources:
  requests:
    cpu: 0.5
    memory: 256Mi
  limits:
    cpu: 1.0
    memory: 512Mi

This container needs a minimum of 256Mi of memory and half a CPU. The scheduler reads this and assigns it to a node with enough resources. If it can't find a suitable node, it marks the Pod as pending, and the cluster autoscaler will attempt to provision a new cluster node.

Assuming the scheduler finds a suitable node, it assigns the Pod to the node, and the kubelet downloads the Pod spec and asks the local runtime to start it. As part of the process, the kubelet reserves the requested CPU and memory, guaranteeing the resources will be there when needed. It also sets a cap on resource usage based on each container's resource limits. In this example, it sets a cap of one CPU and 512Mi of memory. Most runtimes will also enforce resource limits, but how each runtime implements this can vary.

While a container executes, it is guaranteed its minimum requirements (requests). However, it's allowed to use more if the node has additional available resources, but it's never allowed to use more than what you specify in its limits.

For multi-container Pods, the scheduler combines the requests for all containers and finds a node with enough resources to satisfy the full Pod.

Note: If you've been following the examples closely, you'll have noticed that the pod.yml you used to deploy the hello-pod only specified resource limits — it didn't specify resource requests. However, some command outputs have shown both limits and requests. This is because Kubernetes automatically sets requests to match limits if you only specify limits.

Multi-container Pod Example – Init Container

apiVersion: v1
kind: Pod
metadata:
  name: initpod
  labels:
    app: initializer
spec:
  initContainers:
  - name: init-ctr
    image: busybox:1.28.4
    command: ['sh', '-c', 'until nslookup k8sbook; do echo waiting for k8sbook service; sleep 1; done; echo Service found!']
  containers:
  - name: web-ctr
    image: nigelpoulton/k8sbook:1.0
    ports:
    - containerPort: 8080

Defining a container under the spec.initContainers block makes it an init container that Kubernetes guarantees will run and complete before regular containers.

Regular app containers are defined under the spec.containers block and will not start until all init containers successfully complete.

This example has a single init container called init-ctr and a single app container called web-ctr. The init container runs a loop looking for a Kubernetes Service called k8sbook. As soon as you create the Service, the init container will get a response and exit. This allows the main container to start. You'll learn about Services in a future chapter.

Deploy the multi-container Pod with the following command and then run a kubectl get pods with the --watch flag to see if it comes up.

$ kubectl apply -f initpod.yml
pod/initpod created

$ kubectl get pods --watch
NAME      READY   STATUS     RESTARTS   AGE
initpod   0/1     Init:0/1   0          6s

The Init:0/1 status tells you that the init container is still running, meaning the main container hasn't started yet. If you run a kubectl describe command, you'll see the overall Pod status is Pending.

$ kubectl describe pod initpod
Name:         initpod
Namespace:    default
Status:       Pending
Init Containers:
  init-ctr:
    State:          Running
      Started:      Thu, 04 Jan 2024 10:15:32 +0000
    Ready:          False
Containers:
  web-ctr:
    State:          Waiting
      Reason:       PodInitializing
Events:
  Type    Reason     Age   From               Message
  ----    ------     ----  ----               -------
  Normal  Scheduled  45s   default-scheduler  Successfully assigned default/initpod to node-1
  Normal  Pulling    44s   kubelet            Pulling image "busybox:1.28.4"
  Normal  Pulled     42s   kubelet            Successfully pulled image "busybox:1.28.4"
  Normal  Created    42s   kubelet            Created container init-ctr
  Normal  Started    42s   kubelet            Started container init-ctr

The Pod will remain in this phase until you create a Service called k8sbook. Run the following commands to create the Service and re-check the Pod status.

$ kubectl apply -f initsvc.yml
service/k8sbook created

$ kubectl get pods --watch
NAME      READY   STATUS              RESTARTS   AGE
initpod   0/1     Init:0/1            0          15s
initpod   0/1     PodInitializing     0          3m39s
initpod   1/1     Running             0          3m57s

The init container completes as soon as the Service appears, and the main application container starts. Give it a few seconds to fully start.

If you run another kubectl describe against the initpod Pod, you'll see the init container is in the terminated state because it completed successfully (exit code 0).

Multi-container Pod Example – Sidecar Container

Sidecar containers run alongside the main application container for the entire lifecycle of the Pod. We currently define them as regular containers under the spec.containers section of the Pod YAML, and their job is to augment the main application container or provide a secondary support service.

The following YAML file defines a multi-container Pod with both containers mounting the same shared volume. It's conventional to list the main app container as the first container and sidecars after it.

apiVersion: v1
kind: Pod
metadata:
  name: sidecar-pod
  labels:
    app: webserver
spec:
  containers:
  - name: ctr-web                              # Main application container
    image: nginx:1.21
    ports:
    - containerPort: 80
    volumeMounts:
    - name: html
      mountPath: /usr/share/nginx/html
  - name: ctr-sync                             # Sidecar container
    image: image-name
    volumeMounts:
    - name: html
      mountPath: /tmp/git
    env:
    - name: GIT_SYNC_REPO
      value: "...."
    - name: GIT_SYNC_BRANCH
      value: "main"
    - name: GIT_SYNC_DEST
      value: "html"
    - name: GIT_SYNC_WAIT
      value: "60"
  volumes:
  - name: html
    emptyDir: {}

The main app container is called ctr-web. It's based on an NGINX image and serves a static web page loaded from the shared html volume.

The second container is called ctr-sync and is the sidecar. It watches a GitHub repo and syncs changes into the same shared html volume.

When the contents of the GitHub repo change, the sidecar copies the updates to the shared volume, where the app container notices and serves an updated version of the web page.

Mastering Kubernetes Step by Step Part 1: Introduction to Kubernetes Architecture

B.R.O.L.Y — Tue, 14 Oct 2025 23:52:19 +0000

Introduction

Kubernetes is an orchestrator for containerized, cloud-native, microservices applications. But what does that mean exactly? A bunch of jumbled words, right? Let's break it down step by step.

Orchestration

An orchestrator is like an operating system: it has to dynamically respond to changes. In our case, Kubernetes reacts to deployed applications, scales them up or down as needed, self-heals when things break, and performs rolling updates and rollbacks with zero downtime — meaning the app should never go offline and users should never be frustrated. All of this happens automatically, without human interference, except for the initial setup of course.

Containerization

Containerization is packaging your application into an image along with its dependencies so it can run anywhere. If you are familiar with Docker, this will come naturally. I recommend taking a moment to read a couple of blogs on Docker and Docker Compose, including some lower-level concepts, because these fundamentals are crucial for this course.

Cloud Native

We call an application cloud-native if it leverages cloud features like auto-scaling, self-healing, automated updates, and rollbacks — basically, the things Kubernetes is capable of managing.

Microservices

Microservices is an architectural decision to make your application composed of independent services. This means if one service is down, the others continue working. This approach is excellent because it helps developers manage projects better — teams can work on individual services independently and track them properly.

A Bit of History

Kubernetes was developed by a group of engineers at Google in response to AWS's growing popularity. Google had its own internal tools for orchestrating containers due to the massive scale of the applications they managed. They released Kubernetes in 2014 and donated it to the Cloud Native Computing Foundation (CNCF).

Kubernetes and Docker

Early versions of Kubernetes shipped with Docker as the default runtime, handling tasks like creating, starting, and stopping containers. Over time, Docker became bloated, and many alternatives emerged. To address this, Kubernetes introduced the Container Runtime Interface (CRI), allowing users to choose the runtime that best fits their needs. As of Kubernetes 1.24, Docker is no longer supported, and most clusters now use containerd, a lightweight runtime optimized for Kubernetes that fully supports Docker container images. Multiple runtimes can run on the same cluster, offering flexibility for performance and isolation requirements.

Kubernetes: the operating system of the cloud

Kubernetes is often called the operating system of the cloud because it transforms the chaos of distributed infrastructure into a seamless platform for developers. Just as Linux or Windows hides the complexity of CPUs, memory, and storage from application processes, Kubernetes abstracts the sprawling resources of clouds and datacenters, letting you deploy microservices without worrying about which node, storage volume, or failure zone they run on. Whether your cluster lives on AWS, Azure, GCP, or a mix of clouds, Kubernetes schedules, scales, and heals your applications automatically, making hybrid deployments, multi-cloud setups, and cloud migrations effortless. From a developer’s perspective, you simply declare what your application needs — replicas, resources, dependencies — and Kubernetes handles the rest, turning the cloud into a reliable, self-managing operating environment.

Kubernetes: cluster

A cluster is is just what the word means LMAO. well its a grouping of one or more nodes that provide CPU, MEMORY .. for an app
kubernetes has two nodes A Control plane and a Worker node. a plus is that a control plane has to be a linux node indifferent from the worker node which can be windows/linux. in a good setup you'll have to setup multiple control planes for HA(High Availability) the control planes mainly manaage the worker nodes which in turn are for running applications. people sometimes run application on control planes mainly for testing but prohibit it in production so that control planes only focus on manaing the worker nodes properly.

Control Plane

As we mentioned, a Kubernetes cluster is a combination of a control plane and worker nodes. The control plane is the brain of the cluster — a collection of services that manage the cluster’s state, schedule tasks, handle auto-scaling, and orchestrate updates. It also exposes the API server, which is the entry point for all interactions with the cluster. A simple setup might involve one control plane managing multiple worker nodes, but what really makes the control plane tick? Let’s take a closer look.

The API Server

The API server acts as the front door for Kubernetes, handling all requests and communication within the cluster. Every action — from deploying an application to communicating between controllers and the cluster store — goes through the API server. It exposes a RESTful API over HTTPS, and every request must be authenticated and authorized.

For example, deploying an application involves these steps:

Define the desired state of the application in a YAML configuration file.
Submit the file to the API server.
The API server authenticates and authorizes the request.
The desired state is stored in the cluster database.
The control plane schedules and executes the necessary changes on the worker nodes.

The Cluster Store

The cluster store is essentially a database that records the desired state of the cluster and all object definitions. Kubernetes uses etcd, a distributed key-value store, as its backend. Each control plane node contains an etcd replica to ensure high availability (HA). In larger setups, architects may run a separate etcd cluster connected to all control planes to handle high-demand workloads.

One challenge in distributed databases like etcd is the split-brain scenario, which occurs when network partitions isolate some nodes from the rest, potentially causing multiple nodes to believe they are the leader and accept conflicting writes. For example, imagine a three-node etcd cluster: if one node gets disconnected from the other two, it might try to process updates independently. Etcd prevents this by requiring a majority quorum for any write operation — only the majority of nodes can commit a change, ensuring consistency.

Etcd also handles concurrent writes to the same key using version numbers. If two clients try to update the same value at the same time, etcd will accept the first write and reject the second with a conflict error. The client must then retry using the latest version of the key, ensuring that no updates are accidentally overwritten.

Controllers and the controller manager

Kubernetes relies on controllers to handle much of the cluster’s “intelligence” and automation. These controllers run on the control plane and continuously monitor the cluster, comparing the observed state with the desired state you define. Common examples include the Deployment controller, StatefulSet controller, and ReplicaSet controller, each responsible for different types of workloads. Essentially, controllers act like caretakers: if you ask for three replicas of an application, the controller ensures that exactly three healthy instances are running and will create, delete, or restart pods as needed to maintain that state. To keep everything organized, Kubernetes runs a controller manager, which spawns and supervises these individual controllers, ensuring they operate reliably and maintain the overall health and consistency of the cluster.

The scheduler

The Kubernetes scheduler is responsible for assigning new workloads to healthy worker nodes. It continuously watches the API server for new tasks and evaluates which nodes are capable of running them. This involves filtering nodes based on factors like taints, affinity and anti-affinity rules, network port availability, and available CPU and memory. The scheduler then ranks the suitable nodes using a scoring system, considering criteria such as whether the required container image is already present, how much CPU and memory are free, and how many tasks the node is currently running. The nodes with the highest scores are chosen to execute the tasks. If no suitable node is available, the task is marked as pending. In clusters configured with autoscaling, a pending task can trigger a node autoscaling event, adding a new node to the cluster so the task can be scheduled and run.

The cloud controller manager

If your Kubernetes cluster runs on a public cloud like AWS, Azure, GCP, or Civo Cloud, it uses a cloud controller manager to integrate with cloud services. This component handles tasks such as provisioning instances, storage, and load balancers. For example, if an application requests a load balancer, the cloud controller manager automatically creates one in the cloud and connects it to your app, making cloud resources seamless to use.

Worker nodes

an architecture of a worker node looks like this :

kubelet

The kubelet is the main Kubernetes agent running on every worker node, acting as the bridge between the node and the control plane. It watches the API server for new tasks, instructs the appropriate container runtime to execute them, and continuously reports the status of these tasks back to the API server. If a task fails to run, the kubelet reports the problem so the control plane can take the necessary actions to maintain the desired state of the cluster.

Runtime

Each worker node also has one or more container runtimes responsible for executing tasks. Most modern Kubernetes clusters use containerd, which handles pulling container images and managing container lifecycle operations like starting and stopping containers. Older clusters shipped with Docker, which is now deprecated as a runtime, while platforms like Red Hat OpenShift often use CRI-O. Each runtime has its strengths and trade-offs, and Kubernetes can work with any runtime that implements the Container Runtime Interface (CRI).

Kube-proxy

Finally, every worker node runs a kube-proxy service that manages cluster networking. Kube-proxy ensures that network traffic is correctly routed to the tasks running on the node and handles load balancing, making communication between services and pods seamless. With the kubelet, container runtime, and kube-proxy in place, each worker node becomes a self-managing unit capable of running applications reliably within the Kubernetes cluster.

Packaging apps for kubernetes

In Kubernetes, all workloads — whether containers, VMs, or Wasm apps — must be wrapped in Pods to run on the cluster. Think of Pods like standardized packages for a courier service: just as couriers can ship books, clothes, or electronics only if they’re properly packaged and labeled, Kubernetes can run any workload only when it’s packaged in a Pod. Once wrapped, Kubernetes handles the logistics of running the app — choosing the right nodes, connecting networks, attaching storage volumes, and monitoring its health. Typically, Pods are managed by higher-level controllers like Deployments, which add extra value, similar to courier services offering insurance, express delivery, or tracking. Controllers ensure your applications stay healthy, scale automatically when needed, and maintain the desired state, letting you focus on building apps rather than managing the infrastructure.

The important thing to understand is that each layer of wrapping adds something:
• The container wraps the app and provides dependencies
• The Pod wraps the container so it can run on Kubernetes
• The Deployment wraps the Pod and adds self-healing, scaling, and more

The declarative model and desired state

At the heart of Kubernetes lies the declarative model, a powerful system that revolves around three key concepts — observed state, desired state, and reconciliation. The observed state represents the current reality of your cluster, while the desired state defines how you want it to look or behave. The reconciliation process acts as the bridge between the two, continuously ensuring that what exists matches what you’ve declared. In practice, this model starts when you define your application’s configuration in a YAML manifest — specifying details like container images, replicas, and ports — and submit it to the Kubernetes API server. Once authenticated and stored in the cluster’s key-value store, this configuration becomes a “record of intent.” From there, controllers constantly monitor the system, detecting any drift between the observed and desired states. If a discrepancy appears — say, a pod crashes or a node fails — the controller automatically takes corrective actions, such as rescheduling pods or pulling new images, to restore harmony. This self-correcting loop keeps your system stable and resilient. Unlike the imperative model, which relies on manually executed, platform-specific commands and scripts, the declarative model is clean, consistent, and version-controllable — making it easier to roll out changes, recover from failures, and scale seamlessly. For example, if you declare ten replicas of an app and two nodes fail, Kubernetes automatically creates two new replicas to maintain the declared count. Similarly, updating a deployment is as simple as changing one line in your YAML file — Kubernetes handles the rollout, monitoring, and recovery automatically. This model’s elegance lies in its simplicity and automation: you tell Kubernetes what you want, and it continuously works to make that true.

Internet Relay Chat

B.R.O.L.Y — Wed, 21 Aug 2024 08:40:00 +0000

1 — Introduction to IRC Servers:

An Internet Relay Chat (IRC) server is a crucial component in the infrastructure of IRC networks, facilitating real-time communication among users globally. IRC servers act as hubs where users connect to exchange messages in chat rooms (channels) or directly with each other. This decentralized model allows for a robust and flexible communication platform that has persisted since its inception in the late 1980s.

How IRC Servers Work

Connection Establishment: Users connect to an IRC server using a client software capable of handling IRC protocols. These clients initiate a connection to the server, typically on a specific port (usually 6667 or 6697 for SSL/TLS).
Authentication and Identification: Upon connecting, users may need to authenticate themselves using a nickname (nick) and optional credentials (like passwords). This process ensures that users can be identified within the network.
Channel and Private Messaging: Users can join various channels based on topics or interests. Channels are virtual spaces where multiple users can exchange messages simultaneously. Additionally, users can communicate privately with each other via direct messaging.
Server Communication: IRC servers communicate among themselves to synchronize channels and user information across the network. This synchronization ensures that users can see the same list of channels and users, regardless of which server they are connected to within the network.
Commands and Services: IRC networks often provide additional services through bots and automated systems. These services can include channel management (like creating or maintaining channels), user authentication, and network-wide messaging.

Examples of IRC Servers

Several software implementations serve as IRC servers, each with its own features and configurations:

ircd-hybrid: A popular open-source IRC server known for its stability and scalability.
InspIRCd: Another widely used open-source IRC server with extensive customization options.
ircd-seven: Part of the IRCD-Hybrid family, focusing on improvements and added features.

These servers, along with others, form the backbone of various IRC networks, catering to different communities and needs.

2— Process of creating an IRC:

Creating an IRC server involves setting up a platform that facilitates real-time communication between clients in a chat-based environment. Unlike traditional IRC setups that include server-to-server connections for network federation, my IRC project focuses solely on client-server interactions. This chapter will guide you through the process of setting up and configuring your IRC server from scratch.

1-Planning and Requirements

Before diving into implementation, it’s crucial to define your server’s requirements:

Functionality: Determine the core features your IRC server will support, such as user authentication, channel management, and message broadcasting.
Scalability: Consider how your server will handle multiple concurrent connections and optimize for performance.
Security: Plan for user authentication mechanisms and ensure data transmission is secure, especially if handling sensitive information.

2-Setting Up the Server Infrastructure

Begin by setting up the foundational infrastructure for your IRC server:

Network Socket: Implement socket programming to handle incoming client connections.
Protocol Implementation: Develop support for IRC protocol commands such as PASS, NICK, USER, JOIN, PRIVMSG, etc.
Data Persistence: Consider how user data (nicknames, channels) will be stored and accessed, either through in-memory data structures or a database.

3-Implementing IRC Server Features

Focus on implementing essential IRC server features:

User Authentication: Implement mechanisms for users to register nicknames (NICK) and authenticate (PASS) to the server.
Channel Management: Allow users to create (JOIN) and manage channels (PART, MODE, TOPIC).
Message Handling: Support for broadcasting messages (PRIVMSG), including private messages and channel communication.

3 — Starting the server socket:

To begin, the program expects user input specifying the socket port and password in the following format:
./ircserv <port> <password>

port: The port number on which your IRC server will be listening to for incoming IRC connections.
password: The connection password. It will be needed by any IRC client that tries to connect to your server.

For official operation, ensure the port number falls within specific ranges that are not reserved:

+-------------------------+-------------------------------------------------------------+
| Range                   | Use Cases                                                   |
+-------------------------+-------------------------------------------------------------+
| Well-Known Ports        | Reserved for standard services (HTTP, FTP, SSH)             |
|                         | Range: 0-1023                                               |
+-------------------------+-------------------------------------------------------------+
| Registered Ports        | Used by registered applications and services                |
|                         | Range: 1024-49151                                           |
+-------------------------+-------------------------------------------------------------+
| Dynamic or Private Ports| Ephemeral ports for temporary use                           |
|                         | Range: 49152-65535                                          |
+-------------------------+-------------------------------------------------------------+

Next, we will proceed to create the server class and initialize the server socket. Refer to the project structure outlined in the image below for guidance.

1-Creating Server socket:

To establish communication with IRC clients, the server initializes a socket using the following code snippet:

void Server::createSocket(std::string port)
{
    // Create a TCP socket
    this->sock_fd = socket(AF_INET, SOCK_STREAM, 0);
    if (this->sock_fd == -1)
    {
        close(this->sock_fd);
        throw std::runtime_error("Can't create socket");
    }

    // Define server address structure
    sockaddr_in ServerAddress = {};
    ServerAddress.sin_family = AF_INET;
    ServerAddress.sin_addr.s_addr = INADDR_ANY;
    ServerAddress.sin_port = htons(std::atoi(port.c_str()));

    // Set socket to non-blocking mode
    if (fcntl(sock_fd, F_SETFL, O_NONBLOCK) == -1)
    {
        close(sock_fd);
        throw std::runtime_error("Can't set non-blocking");
    }

    // Bind socket to the specified port
    if (bind(sock_fd, (struct sockaddr*)&ServerAddress, sizeof(ServerAddress)) == -1){
        close(this->sock_fd);
        throw std::runtime_error("Can't bind socket");
    }

    // Listen for incoming connections with a queue size of 10
    if (listen(sock_fd, 10) == -1)
    {
        close(sock_fd);
        throw std::runtime_error("Error listening");
    }

    // Server socket created successfully
    std::cout << "Server socket created and listening on port " << port << std::endl;
}

2-Starting the server:

initiate the IRC server and handle incoming client connections and messages, the following Server::start() function is utilized:

void Server::start()
{
    // Add server socket to pollfds array for monitoring
    pollfd serverfd = {sock_fd, POLLIN, 0};
    _pollfds.push_back(serverfd);

    // Inform that the server is running on the specified port
    std::cout << "Server is running on port " << this->port << std::endl;

    // Main server loop for handling events
    while(true)
    {
        // Wait indefinitely for events on monitored file descriptors
        if (poll(_pollfds.data(), _pollfds.size(), -1) == -1) {
            throw std::runtime_error("Poll error");
        }

        // Iterate through all monitored file descriptors
        for(auto it = _pollfds.begin(); it != _pollfds.end(); ++it)
        {
            // Check if the file descriptor has events to process
            if (it->revents == 0)
                continue;

            // Handle incoming connection request on the server socket
            if (it->revents & POLLIN)
            {
                if(it->fd == sock_fd) {
                    addClient(sock_fd); // Accept new client connection
                    break;
                }
                else {
                    handleMessage(it->fd); // Handle message from client
                }
            }
        }
    }
}

Explanation:

Adding Server Socket to Pollfds:

pollfd serverfd = {sock_fd, POLLIN, 0}; initializes a pollfd structure for the server socket (sock_fd) to monitor for input readiness (POLLIN).
_pollfds.push_back(serverfd); adds the server socket to the _pollfds vector for polling.

Polling for Events:

if (poll(_pollfds.data(), _pollfds.size(), -1) == -1) polls all file descriptors in _pollfds indefinitely (-1 timeout) for events.
Throws an exception if poll encounters an error.

Processing Events:

Iterates through each file descriptor in _pollfds to check for events (revents).

Handling Server Socket Event:

if (it->fd == sock_fd) checks if the event is on the server socket:
Calls addClient(sock_fd); to accept and add a new client connection.

Handling Client Messages:

else if (it->revents & POLLIN) processes incoming messages from connected clients:
Calls handleMessage(it->fd); to handle the message from the client.

3-Adding a client:

To integrate a new client into the IRC server, the Server::addClient(int sock_fd) function is employed:

void Server::addClient(int sock_fd)
{
    // Accept incoming client connection
    int client_fd;
    sockaddr_in clientAddress = {};
    socklen_t clientAddressSize = sizeof(clientAddress);
    client_fd = accept(sock_fd, (struct sockaddr*)&clientAddress, &clientAddressSize);
    if (client_fd == -1)
        throw std::runtime_error("Can't accept client");

    // Add client socket to pollfds array for monitoring
    pollfd client_poll = {client_fd, POLLIN, 0};
    _pollfds.push_back(client_poll);

    // Retrieve client hostname
    char hostname[NI_MAXHOST];
    int result = getnameinfo((struct sockaddr*)&clientAddress, sizeof(clientAddress), hostname, NI_MAXHOST, NULL, 0, NI_NUMERICSERV);

    // Handle error if unable to retrieve hostname
    if (result != 0) {
        close(client_fd);
        throw std::runtime_error("Can't get hostname");
    }

    // Create a new Client object and store in clients map
    Client *client = new Client(hostname, ntohs(clientAddress.sin_port), client_fd);
    _clients.insert(std::make_pair(client_fd, client));

    // TODO: Log client connection
}

Explanation:

Accepting Client Connection: accept() is used to accept a new client connection on the server socket (sock_fd). If unsuccessful (client_fd == -1), an exception is thrown.
Adding Client to Pollfds: A pollfd structure is initialized for the client socket (client_fd) with POLLIN flag indicating readiness for reading.
Retrieving Client Hostname: getnameinfo() retrieves the hostname of the connecting client from clientAddress. If unsuccessful (result != 0), the client socket is closed and an exception is thrown.
Creating Client Object: A new Client object is instantiated with the retrieved hostname, client port (converted from network to host byte order), and client socket file descriptor (client_fd). This client object is stored in _clients map for future management.

4-Handling message and commands:

To manage incoming messages and execute commands from clients within the IRC server, the following functions are employed:

void Server::handleMessage(int fd)
{
    try
    {
        // Retrieve client associated with the file descriptor
        Client* client = _clients.at(fd);

        // Read incoming message from client
        std::string message = readMessage(fd);

        // Pass message to command handler for processing
        _commandHandler->handleCommand(message, client);
    }
    catch(const std::exception& e)
    {
        std::cout << e.what() << std::endl;
        throw std::runtime_error("Error handling message");
    }
}

Explanation:

Retrieve Client: _clients.at(fd) retrieves the client object associated with the provided file descriptor (fd).
Read Message: readMessage(fd) reads the incoming message from the client socket (fd).
Handle Command: _commandHandler->handleCommand(message, client) delegates message handling and command execution to _commandHandler, passing the received message and client object.

std::string Server::readMessage(int fd)
{
    char buffer[1024];
    std::string message;

    // Receive message from client
    int bytes = recv(fd, buffer, 1024, 0);

    // Handle receive errors
    if (bytes == -1)
        throw std::runtime_error("Can't read message");
    else
        message = std::string(buffer, bytes);

    return message;
}

Explanation:

Receive Message: recv(fd, buffer, 1024, 0) reads up to 1024 bytes from the client socket (fd) into buffer.
Handle Receive Errors: Throws an exception if recv returns -1, indicating an error occurred during message reception.

void CommandHandler::handleCommand(std::string command, Client *client)
{
    // Remove leading colon from command if present
    if (command[0] == ':')
        command = command.substr(1);

    // Process each command line by line
    std::stringstream ss(command);
    std::string cmd;
    while(std::getline(ss, cmd))
    {
        // Trim any trailing carriage return characters
        if (cmd.back() == '\r')
            cmd.pop_back();

        // Retrieve command name
        std::string commandName = cmd.substr(0, cmd.find(" "));

        try
        {
            // Retrieve corresponding command object
            Command *c = _commands.at(commandName);

            // Extract command arguments
            std::string argsBuffer = cmd.substr(cmd.find(" ") + 1);
            std::istringstream argsStream(argsBuffer);
            std::string arg;
            std::list<std::string> args;
            while(std::getline(argsStream, arg, ' '))
            {
                arg.erase(std::remove_if(arg.begin(), arg.end(), ::isspace), arg.end());
                args.push_back(arg);
            }

            // Execute command with client and arguments
            c->run(client, args);
        }
        catch (const std::out_of_range &e)
        {
            // Handle unknown command error
            client-reply(Replies::ERR_UNKNOWNCOMMAND(commandName));
        }
    }
}

Command Processing: Splits the incoming command into individual lines (cmd), trims any trailing carriage return characters, and retrieves the command name.
Command Execution: Attempts to locate and execute the corresponding command handler (Command *c = _commands.at(commandName);) using _commands map.
Argument Parsing: Extracts command arguments from cmd, parses them, and executes the command with the client and parsed arguments (c->run(client, args);).
Error Handling: Catches std::out_of_range exception to handle unknown command scenarios (clientreply(Replies::ERR_UNKNOWNCOMMAND(commandName));).

the diagram of the algorithm followed is below

4 — Creating a bot:

In this section, you have the discretion to select the type of bot to develop, ensuring its relevance within the project framework. For this purpose, I have chosen to develop a weather bot, which functions as a client connecting to the server. Other clients interact with this bot using the command format: WEATHER . When the server receives such a command, it relays it to the bot and awaits the bot's response. Upon receiving the weather information from the bot, the server then directs this response back to the specific client who initiated the query.

Below is an overview of the logical structure underlying this process:

1.Clients send a request in the form WEATHER to the server.
2.The server receives the request and forwards it to the weather bot.
3.The bot processes the request, querying the relevant weather data.
4.The bot sends the weather information back to the server.
5.The server, upon receiving the bot’s response, forwards this information to the client who made the initial request.

1 — inside weather bot brain:

The code blow check args and weather_api_key and attempts to connect and register with the server then in case of success start listening for incoming calls

int main(int argc, char **argv) {
    if (argc != 3) {
        std::cerr << GREEN << "Usage: " << argv[0] << " <port> <password>" << RESET << std::endl;
        return 1;
    }

    std::string server = "localhost";
    int port = std::stoi(argv[1]);
    std::string password = argv[2];
    int sockfd;
    char *apikey = getenv("WEATHER_API_KEY");
    std::string apiKey;
    if (apikey)
    {
        apiKey = apikey;
        std::cout << GREEN << "WEATHER_API_KEY environment variable set ✅" << RESET << std::endl;
    }
    else
    {
        std::cerr << RED << "WEATHER_API_KEY environment variable not set ❌" << RESET << std::endl;
        exit(1);
    }

    if (connectToServer(server, port, sockfd)) {

        std::cout << GREEN << "Connected to server ✅" << RESET << std::endl;

        // Send registration messages
        if (!sendToServer(sockfd, "PASS " + password + "\r\n") ||
            !sendToServer(sockfd, "NICK bot\r\n") ||
            !sendToServer(sockfd, "USER botname 0 * :bot\r\n")) {
            std::cerr << RED << "Failed to register with the server ❌" << RESET << std::endl;
            close(sockfd);
            return 1;
        }
        std::cout << GREEN << "Registered with the server ✅" << RESET << std::endl;
        std::cout << GREEN << "Listening for messages..." << RESET << std::endl;
        listenForMessages(sockfd, apiKey);
        close(sockfd);
    } else {
        std::cerr << RED << "Failed to connect to server ❌" << RESET << std::endl;
    }

    return 0;
}

now we check the connectToServer function that attempts to connect with the server using a socket

bool connectToServer(const std::string &server, int port, int &sockfd) {
    struct sockaddr_in server_addr;
    struct hostent *host;

    if ((host = gethostbyname(server.c_str())) == NULL) {
        std::cerr << RED << "Failed to get host by name ❌" << RESET << std::endl;
        return false;
    }

    if ((sockfd = socket(AF_INET, SOCK_STREAM, 0)) == -1) {
        std::cerr << RED << "Failed to create socket ❌" << RESET << std::endl;
        return false;
    }

    server_addr.sin_family = AF_INET;
    server_addr.sin_port = htons(port);
    server_addr.sin_addr = *((struct in_addr *)host->h_addr);
    memset(&(server_addr.sin_zero), '\0', 8);

    if (connect(sockfd, (struct sockaddr *)&server_addr, sizeof(struct sockaddr)) == -1) {
        std::cerr << RED << "Failed to connect to server ❌" << RESET << std::endl;
        close(sockfd);
        return false;
    }
    return true;
}

Hostname Resolution (`gethostbyname`):

The function first attempts to resolve the hostname (server) to an IP address using gethostbyname. If unsuccessful (returns NULL), it prints an error message and returns false, indicating failure to resolve the host.

Socket Creation (`socket`):

If hostname resolution succeeds, the function creates a TCP socket (SOCK_STREAM) using socket(AF_INET, SOCK_STREAM, 0). If socket creation fails (returns -1), it prints an error message and returns false.

Server Address Configuration (`server_addr`):

The function initializes a sockaddr_in structure (server_addr) to hold the server's address information:
sin_family is set to AF_INET indicating IPv4.
sin_port is set to the specified port number (port) in network byte order (htons).
sin_addr is set to the resolved IP address obtained from gethostbyname.
memset initializes the remaining bytes of sin_zero to 0.

Connecting to the Server (`connect`):

The function attempts to establish a connection to the server using connect(sockfd, (struct sockaddr *)&server_addr, sizeof(struct sockaddr)). If connection fails (returns -1), it prints an error message, closes the socket (sockfd), and returns false.

void listenForMessages(int sockfd, std::string& apiKey) {
    char buffer[512];
    int numBytes;
    while (true) {
        if ((numBytes = recv(sockfd, buffer, sizeof(buffer) - 1, 0)) > 0) {
            buffer[numBytes] = '\0';
            std::string message(buffer);
            std::istringstream iss(message);
            std::string command, user, city;

            iss >> command >> user >> city;

            if (command == "WEATHER") {
                std::string weatherJson = fetchWeatherData(city, apiKey);

                std::string formattedMessage = formatWeatherResponse(weatherJson);
                std::cout << "Client: " << user << " requested weather for " << city << std::endl;
                std::istringstream iss(formattedMessage);
                std::string line;
                while (std::getline(iss, line)) {
                    std::string response = "PRIVMSG " + user + " :" + line + "\r\n";
                    sendToServer(sockfd, response);
                }
            }

        } else if (numBytes == 0) {
            std::cout << RED << "Server closed the connection" << RESET << std::endl;
            break;
        } else {
            std::cerr << RED << "Failed to receive message ❌" << RESET << std::endl;
            break;
        }
    }
}

std::string fetchWeatherData(const std::string& city, const std::string& apiKey) {
    //saving api keys is a vonerable point, so we will use the environment variable instead
    // std::string apiKey = "be44eb7afe554d9890b210909240806"; 

        std::string url = "http://api.weatherapi.com/v1/current.json?key=" + apiKey + "&q=" + city;
        std::string command = "curl -s \"" + url + "\" -o weather.json";

        // Execute the curl command
        system(command.c_str());

        // Read the content of the file into a string
        std::ifstream file("weather.json");
        std::string response((std::istreambuf_iterator<char>(file)), std::istreambuf_iterator<char>());
        file.close();

        // Optionally remove the temporary file
        remove("weather.json");

        return response;
}

  std::string formatWeatherResponse(const std::string& weatherJson) {
    std::string location = extractValue(weatherJson, "name");
    std::string country = extractValue(weatherJson, "country");
    std::string condition = extractValue(weatherJson, "text");
    std::string temp_c = extractValue(weatherJson, "temp_c");
    std::string wind_kph = extractValue(weatherJson, "wind_kph");
    std::string humidity = extractValue(weatherJson, "humidity");
    std::string uv_index = extractValue(weatherJson, "uv");

    std::ostringstream oss;
    oss << "------------------------\n";
    oss << "Weather Information:\n";
    oss << "Location: " << location << ", " << country << "\n";
    oss << "Condition: " << condition << "\n";
    oss << "Temperature: " << temp_c << "°C\n";
    oss << "Wind Speed: " << wind_kph << " kph\n";
    oss << "Humidity: " << humidity << "%\n";
    oss << "UV Index: " << uv_index << "\n";
    oss << "------------------------\n";

    return oss.str();
}

std::string extractValue(const std::string& json, const std::string& key) {
    std::string searchKey = "\"" + key + "\":";
    std::size_t startPos = json.find(searchKey);
    if (startPos == std::string::npos) {
        return "";
    }

    startPos += searchKey.length();
    while (json[startPos] == ' ' || json[startPos] == '\"' || json[startPos] == '{') {
        startPos++;
    }

    std::size_t endPos = json.find_first_of(",}", startPos);
    std::string value = json.substr(startPos, endPos - startPos);
    value.erase(std::remove(value.begin(), value.end(), '\"'), value.end());
    return value;
}

NOTE:

When working with APIs that require authentication via API keys, it’s crucial not to hardcode or embed these keys directly into your source code. Here’s why:

Security Risk: Hardcoding API keys exposes them to potential theft if the code repository is compromised or accessed by unauthorized parties.
Best Practices: Instead of embedding API keys in code, use environment variables or configuration files that are not included in your version control system (e.g., .gitignore for Git repositories).
Environmental Variables: Store sensitive information like API keys in environment variables during development and deployment. This approach keeps them secure and separate from your application codebase.
Avoiding Accidental Exposure: Inadvertently exposing API keys in public repositories can lead to unauthorized usage, potential costs, or compromised data.
Security Hygiene: Regularly audit your codebase for any hardcoded sensitive information and implement secure practices to handle such credentials.

in my case we used environment variables but you can use other solutions