Organizing Pods with Labels

Introduction: Why You Need Labels

In the previous lessons, you created individual Pods with unique names like nginx-configured and nginx-broken . Each Pod had its own manifest file, and you managed them one at a time using their specific names. This approach works fine when you're learning or running a small experiment, but it breaks down quickly in real-world scenarios. Imagine you're running a production application with 50 Pods spread across different versions, environments, and teams. How do you find all the Pods running version 2 of your app? How do you identify which Pods belong to the staging environment versus production? Relying on unique names becomes impossible because you'd need to remember or document every single Pod name. Labels solve this problem. They are human-readable tags that you attach to Pods (and other Kubernetes resources) to organize and group them. Instead of tracking individual Pod names, you tag Pods with meaningful information like which application they belong to, what version they're running, or which team owns them. Then, you can query and filter Pods based on those tags. This lesson teaches you how to add labels to Pods and use them to organize your resources effectively.

Understanding Labels: Key-Value Metadata

Labels are key-value pairs that you attach to Kubernetes resources in the metadata section of a manifest. They look like this: app: demo or version: v1 . The key is on the left side of the colon, and the value is on the right. You can attach as many labels as you want to a single Pod, and multiple Pods can share the same labels. Labels serve as organizational metadata. They don't change how a Pod runs or what containers it contains. Instead, they provide a way to categorize and group resources based on characteristics that matter to you and your team. Common uses include tracking which application or project a Pod belongs to (app: demo, app: payment-service), tracking versions (version: v1, version: v2), tracking environments (env: production, env: staging), and tracking ownership (team: backend, team: frontend). The power of labels comes from their flexibility. Unlike Pod names, which must be unique within a namespace, labels can be shared across many Pods. You might have 20 Pods all labeled with app: demo because they all belong to the same application. You might have 10 of those labeled version: v1 and 10 labeled version: v2 because you're running two versions side by side. Labels let you slice and organize your Pods in whatever way makes sense for your use case. It's important to understand the difference between labels and names . A Pod's name is a unique identifier that you use to reference that specific Pod. You can't have two Pods named nginx-one in the same namespace. Labels, on the other hand, are shared tags. Many Pods can have the same label, and that's exactly the point. Labels group Pods together so you can work with them as a set rather than individually.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Creating Multiple Pods with Labels

Let's create three Pods and organize them using labels. In real-world scenarios, you'll often manage related Pods across multiple separate files. This approach makes it easier to version control individual components, update them independently, and organize your configuration by component or service.

Each Pod will have two labels: app to indicate which application it belongs to, and version to indicate which version it's running. All three Pods will have app: demo because they're all part of the same demo application. Two Pods will have version: v1, and one will have version: v2 to simulate running multiple versions of the same app.

Create a file called nginx-one.yaml:

YAML

apiVersion: v1
kind: Pod
metadata:
  name: nginx-one
  labels:
    app: demo
    version: v1
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80

apiVersion: v1
kind: Pod
metadata:
  name: nginx-one
  labels:
    app: demo
    version: v1
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80

Let's break down what's new here. The metadata section now includes a labels field. This field contains key-value pairs where each key is a label name and each value is the label's value. In this case, we're setting app: demo and version: v1. The rest of the Pod definition is the same as what you've seen before: a single container running nginx version 1.25 with port 80 exposed.

Now, let's create the second Pod in a separate file. Create nginx-two.yaml:

YAML

apiVersion: v1
kind: Pod
metadata:
  name: nginx-two
  labels:
    app: demo
    version: v1
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80

apiVersion: v1
kind: Pod
metadata:
  name: nginx-two
  labels:
    app: demo
    version: v1
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80

This Pod is almost identical to the first one. It has a different name (nginx-two instead of nginx-one), but it shares the same labels: app: demo and version: v1. Both Pods are part of the demo application, and both are running version 1. Having separate files makes it easy to manage each Pod independently.

Finally, let's create the third Pod with a different version label. Create nginx-three.yaml:

YAML

apiVersion: v1
kind: Pod
metadata:
  name: nginx-three
  labels:
    app: demo
    version: v2
spec:
  containers:
    - name: nginx
      image: nginx:1.26
      ports:
        - containerPort: 80

apiVersion: v1
kind: Pod
metadata:
  name: nginx-three
  labels:
    app: demo
    version: v2
spec:
  containers:
    - name: nginx
      image: nginx:1.26
      ports:
        - containerPort: 80

This Pod has version: v2 instead of version: v1, and it's running a newer nginx image (1.26 instead of 1.25). This simulates a scenario where you're testing a new version of your application alongside the old version. Both versions share the app: demo label because they're both part of the same application, but the version label lets you distinguish between them.

Now, create all three Pods at once by applying all files:

Shell

kubectl apply -f nginx-one.yaml -f nginx-two.yaml -f nginx-three.yaml

kubectl apply -f nginx-one.yaml -f nginx-two.yaml -f nginx-three.yaml

You'll see:

text

pod/nginx-one created
pod/nginx-two created
pod/nginx-three created

pod/nginx-one created
pod/nginx-two created
pod/nginx-three created

Kubernetes processed all three files and created all three Pods in a single command. This is efficient and lets you manage each Pod's configuration separately. You can verify that all three Pods are running:

Shell

kubectl get pods

kubectl get pods

You'll see:

text

NAME          READY   STATUS    RESTARTS   AGE
nginx-one     1/1     Running   0          10s
nginx-two     1/1     Running   0          10s
nginx-three   1/1     Running   0          10s

NAME          READY   STATUS    RESTARTS   AGE
nginx-one     1/1     Running   0          10s
nginx-two     1/1     Running   0          10s
nginx-three   1/1     Running   0          10s

All three Pods are running, but this output doesn't show their labels yet. Let's learn how to query Pods based on those labels.

Note: You can also define multiple resources in a single file by separating them with three dashes (---) on their own line. This creates a multi-document YAML file. While this approach can be useful for very tightly coupled resources, separate files are generally preferred because they're easier to manage, update independently, and organize in version control systems.

Querying and Filtering Pods by Labels

Now that your Pods have labels, you can use label selectors to filter and find specific groups of Pods. Instead of listing all Pods and manually looking for the ones you care about, you can ask Kubernetes to show you only the Pods that match certain label criteria.

The -l flag (short for --selector) lets you filter Pods by label. Let's find all Pods that belong to the demo application:

Shell

kubectl get pods -l app=demo

kubectl get pods -l app=demo

You'll see:

text

NAME          READY   STATUS    RESTARTS   AGE
nginx-one     1/1     Running   0          2m
nginx-two     1/1     Running   0          2m
nginx-three   1/1     Running   0          2m

NAME          READY   STATUS    RESTARTS   AGE
nginx-one     1/1     Running   0          2m
nginx-two     1/1     Running   0          2m
nginx-three   1/1     Running   0          2m

All three Pods appear because they all have the label app: demo. This query answered the question "show me all Pods for the demo application" without requiring you to know or remember the specific Pod names. If you had 50 Pods in your cluster but only 3 belonged to the demo app, this command would show you just those 3.

Now, let's filter by version. Show only the Pods running version 1:

Shell

kubectl get pods -l version=v1

kubectl get pods -l version=v1

You'll see:

text

NAME        READY   STATUS    RESTARTS   AGE
nginx-one   1/1     Running   0          3m
nginx-two   1/1     Running   0          3m

NAME        READY   STATUS    RESTARTS   AGE
nginx-one   1/1     Running   0          3m
nginx-two   1/1     Running   0          3m

Only nginx-one and nginx-two appear because they're the only Pods with version: v1. The nginx-three Pod is excluded because it has version: v2. This is useful when you want to check the status of a specific version of your application or perform operations on just that version.

You can also view all labels directly in the kubectl get pods output using the --show-labels flag:

Shell

kubectl get pods --show-labels

kubectl get pods --show-labels

You'll see:

text

NAME          READY   STATUS    RESTARTS   AGE   LABELS
nginx-one     1/1     Running   0          4m    app=demo,version=v1
nginx-two     1/1     Running   0          4m    app=demo,version=v1
nginx-three   1/1     Running   0          4m    app=demo,version=v2

NAME          READY   STATUS    RESTARTS   AGE   LABELS
nginx-one     1/1     Running   0          4m    app=demo,version=v1
nginx-two     1/1     Running   0          4m    app=demo,version=v1
nginx-three   1/1     Running   0          4m    app=demo,version=v2

The LABELS column shows all labels attached to each Pod. This gives you a quick overview of how your Pods are organized without needing to describe each one individually. You can see at a glance that two Pods are running v1 and one is running v2.

For more detailed information about a Pod's labels, use kubectl describe:

Shell

kubectl describe pod nginx-one

kubectl describe pod nginx-one

Near the top of the output, you'll see:

text

Name:             nginx-one
Namespace:        default
Priority:         0
Service Account:  default
Node:             node-1/192.168.1.10
Start Time:       Mon, 15 Jan 2024 10:30:00 +0000
Labels:           app=demo
                  version=v1
Annotations:      <none>
Status:           Running

Name:             nginx-one
Namespace:        default
Priority:         0
Service Account:  default
Node:             node-1/192.168.1.10
Start Time:       Mon, 15 Jan 2024 10:30:00 +0000
Labels:           app=demo
                  version=v1
Annotations:      <none>
Status:           Running

The Labels section shows all labels attached to the Pod. This is the same information you saw with --show-labels, but kubectl describe presents it in a more readable format along with all the other Pod details. Labels appear in the metadata section because that's where you defined them in the manifest.

The real power of labels becomes clear when you're managing many Pods. Instead of remembering that nginx-one and nginx-two are the v1 Pods, you just query for version=v1. Instead of tracking which Pods belong to which application, you query for app=demo. Labels turn Pod management from a memory exercise into a simple filtering operation.

Organizing Pods with Labels

Introduction: Why You Need Labels

Understanding Labels: Key-Value Metadata

Join the 1M+ learners on CodeSignal

Creating Multiple Pods with Labels

Querying and Filtering Pods by Labels

Summary: From Human Organization to Machine Automation