Labels and Annotations

Working with labels and annotations in Kubernetes Dashboard

Labels and annotations are key-value pairs that provide metadata for Kubernetes resources. This guide covers how to view, add, and manage labels and annotations through the Dashboard interface.

Overview

Kubernetes uses two types of metadata:

Labels

Identifying metadata used for selection and organization

Annotations

Non-identifying metadata for tools and libraries

Labels

Labels are key-value pairs attached to objects for identification and selection:

metadata:
  labels:
    app: nginx
    environment: production
    tier: frontend
    version: v1.2.3

Use cases:

• Resource selection via label selectors
• Service discovery and routing
• Organizing resources by application, environment, or team
• Scheduling and placement decisions

Annotations

Annotations store arbitrary non-identifying metadata:

metadata:
  annotations:
    kubernetes.io/change-cause: "Updated nginx to 1.21"
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
    deployment.kubernetes.io/revision: "3"

Use cases:

• Build/release information
• Tool configuration (monitoring, logging, service mesh)
• Documentation and contact information
• Deployment history and rollout tracking

Viewing Labels and Annotations

In List Views

Resource list views display common labels:

1. Navigate to any resource type (Pods, Deployments, Services, etc.)
2. Labels are shown in the list view columns
3. Click on a label to filter resources with that label

In Detail Views

View all labels and annotations for a resource:

1. Open Resource

   Click on any resource name to open its detail view

2. View Metadata Section

   Scroll to the metadata section showing labels and annotations

3. Expand Lists

   Click to expand the full list of labels or annotations

In YAML View

See the raw metadata:

1. Open resource detail view
2. Click the YAML tab
3. Find the metadata section:

metadata:
  name: nginx-deployment
  namespace: default
  labels:
    app: nginx
    tier: frontend
  annotations:
    deployment.kubernetes.io/revision: "1"
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment"...}

Adding Labels

Add labels through the Dashboard UI:

During Resource Creation

When creating applications via the form:

1. Access Creation Form

   Navigate to Create → Create from form

2. Show Advanced Options

   Expand the advanced options section

3. Add Labels

   In the labels section, click Add Label

4. Enter Key-Value Pairs

   Provide label key and value:

   Key: environment
   Value: production
   

Dashboard automatically adds the k8s-app label to deployments created via the form. This label is used for service discovery and dashboard organization.

Editing Existing Resources

Add labels to existing resources:

1. Open Resource

   Navigate to the resource detail view

2. Edit YAML

   Click the Edit button

3. Add Labels

   Update the metadata.labels section:

   metadata:
     labels:
       app: nginx
       team: platform  # New label
       cost-center: engineering  # New label
   
4. Save Changes

   Click Update to apply changes

Adding Annotations

Add annotations for documentation and tool integration:

Via YAML Editor

metadata:
  annotations:
    # Documentation
    description: "Primary web application frontend"
    owner: "[e-mail]"
    
    # Monitoring integration
    prometheus.io/scrape: "true"
    prometheus.io/port: "8080"
    prometheus.io/path: "/metrics"
    
    # Service mesh
    sidecar.istio.io/inject: "true"
    
    # Custom tooling
    company.com/backup-policy: "daily"
    company.com/pii-data: "false"

Common Annotations

Kubernetes System Annotations

kubernetes.io/change-cause: "Deployment reason"
kubernetes.io/description: "Resource description"
kubernetes.io/ingress.class: "nginx"
deployment.kubernetes.io/revision: "3"

Prometheus Annotations

prometheus.io/scrape: "true"
prometheus.io/port: "9090"
prometheus.io/path: "/metrics"
prometheus.io/scheme: "https"

Service Mesh Annotations

# Istio
sidecar.istio.io/inject: "true"
sidecar.istio.io/proxyCPU: "100m"
sidecar.istio.io/proxyMemory: "128Mi"

# Linkerd
linkerd.io/inject: "enabled"

Label Selectors

Use label selectors to filter and organize resources:

Equality-Based Selectors

Match labels exactly:

selector:
  app: nginx
  environment: production

This matches resources with both labels.

Set-Based Selectors

More flexible matching:

selector:
  matchLabels:
    app: nginx
  matchExpressions:
  - key: environment
    operator: In
    values:
    - production
    - staging
  - key: tier
    operator: NotIn
    values:
    - deprecated

Operators:

• In: Label value is in the set
• NotIn: Label value is not in the set
• Exists: Label key exists
• DoesNotExist: Label key doesn’t exist

Using Selectors in Dashboard

Filter resources by labels:

1. Navigate to any resource list view
2. Click a label value in the list
3. Dashboard filters to show only resources with that label

Label Best Practices

Use meaningful, hierarchical labels

Structure labels for clarity:

labels:
  app.kubernetes.io/name: wordpress
  app.kubernetes.io/instance: wordpress-prod
  app.kubernetes.io/version: "6.2.0"
  app.kubernetes.io/component: frontend
  app.kubernetes.io/part-of: blog-platform
  app.kubernetes.io/managed-by: helm

Follow Kubernetes recommended labels

Use recommended label keys:

• app.kubernetes.io/name: Application name
• app.kubernetes.io/instance: Unique instance identifier
• app.kubernetes.io/version: Application version
• app.kubernetes.io/component: Component within architecture
• app.kubernetes.io/part-of: Higher-level application
• app.kubernetes.io/managed-by: Tool managing the resource

Keep labels short and descriptive

Good:

env: prod
tier: frontend

Avoid:

environment_type_for_deployment: production
application_tier_classification: frontend-web-servers

Use consistent labeling schemes

Standardize across your organization:

# Consistent environment labels
env: dev | staging | prod

# Consistent tier labels  
tier: frontend | backend | database

# Consistent team ownership
team: platform | data | security

Don't store large data in annotations

Annotations are limited to 256KB total. For large data, use ConfigMaps or external storage.

Common Label Patterns

Application Identification

labels:
  app: wordpress
  app.kubernetes.io/name: wordpress
  app.kubernetes.io/instance: wordpress-prod-01

Environment Segregation

labels:
  environment: production
  env: prod

Team Ownership

labels:
  team: platform
  owner: platform-team

Release Tracking

labels:
  version: v1.2.3
  release: spring-2026

Cost Allocation

labels:
  cost-center: engineering
  project: customer-portal
  budget-code: ENG-2026-Q1

Service Discovery with Labels

Services use label selectors to find pods:

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx      # Matches pods with this label
    tier: frontend
  ports:
  - port: 80
    targetPort: 8080

Dashboard displays the label selector in the service detail view, showing which pods are selected by the service.

Deployment Selectors

Deployments use selectors to manage pods:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx        # Must match selector
        version: v1.21

Deployment selectors are immutable after creation. You cannot change the selector without deleting and recreating the deployment.

Label Validation

Labels must follow specific rules:

Label Keys

• Optional prefix + name separated by /
• Prefix: DNS subdomain (max 253 characters)
• Name: max 63 characters
• Characters: alphanumeric, -, _, .
• Must start and end with alphanumeric

Valid:

app: nginx
app.kubernetes.io/name: wordpress
company.com/team: platform

Invalid:

-app: nginx                    # Can't start with -
app-: nginx                    # Can't end with -  
too-long-label-key-that-exceeds-sixty-three-characters-limit: value

Label Values

• Max 63 characters
• Can be empty
• Characters: alphanumeric, -, _, .
• Must start and end with alphanumeric (if non-empty)

Troubleshooting

Labels not showing in list view

Dashboard shows a limited set of common labels in list views. View the full list in the detail view or YAML tab.

Cannot change deployment selector

Deployment selectors are immutable. You must delete and recreate the deployment with a new selector.

Service not finding pods

Verify the service selector matches pod labels:

kubectl get pods -l app=nginx,tier=frontend
kubectl describe service nginx-service

Invalid label format

Ensure labels follow naming conventions:

• Max 63 characters for name
• Alphanumeric, -, _, . only
• Start and end with alphanumeric

Next Steps

Managing Resources

Learn about resource management

Managing Applications

Deploy and manage applications