Working with Container Labels

1. Adding Labels at Build Time

Method	Usage	Description
Dockerfile LABEL	`LABEL key="value"`	Set labels during image build
docker build --label	`docker build --label key=value .`	Set labels at build time using CLI

Example: Dockerfile LABEL usage

FROM ubuntu:20.04
LABEL maintainer="dev@example.com"
LABEL version="1.0"
LABEL description="A sample application"

Example: CLI label during build

docker build --label org.label-schema.build-date="2026-01-01" --label org.label-schema.name="myapp" .

Note: Labels are stored as strings and can include spaces or special characters when quoted.

2. Adding Labels at Runtime

Method	Description	Example
docker update	Update labels of a running container	`docker update --label com.example.description="Production service" my-container`
docker run	Add labels when starting a new container	`docker run --label org.example.team="backend" --label org.example.version="v1.2.3" nginx`

Note: Labels added at runtime are stored in the container's configuration and persist across restarts.

3. Filtering Containers by Label

Label Key	Label Value	Filter Expression	Description
environment	`production`	`label=environment=production`	Filter containers with the environment label set to production
team	`backend`	`label=team=backend`	Filter containers labeled with the backend team
version	`v2.0`	`label=version=v2.0`	Filter containers with version label set to v2.0

Example: Using Label Filters in Docker CLI

docker ps --filter label=environment=production

Example: Combining Multiple Label Filters

docker ps --filter label=team=backend --filter label=version=v2.0

4. Organizing Resources with Labels

Label Key	Value	Description
app.name	`myapp`	Name of the application
app.version	`v1.2.3`	Version of the application
environment	`production`	Deployment environment (e.g., dev, staging, prod)
team	`backend`	Team responsible for the container

Example: Setting Labels During Build

FROM ubuntu:20.04
LABEL app.name="myapp"
LABEL app.version="v1.2.3"
LABEL environment="production"
LABEL team="backend"
RUN apt-get update && apt-get install -y nginx
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Example: Setting Labels at Runtime

docker run -d \
  --label app.name=myapp \
  --label app.version=v1.2.3 \
  --label environment=production \
  --label team=backend \
  nginx:latest

Note: Labels are stored as strings and can be used for filtering and organizing containers, images, and networks.

Label Usage Summary

Filtering: Use labels to filter containers or images with docker ps or docker images.
Organization: Labels help categorize and manage resources in large deployments.
Metadata: Labels provide metadata for containers, aiding in automation and monitoring.

5. Using Labels for Automation

Label Key	Value	Description	Usage
com.example.environment	`production`	Environment type for deployment	Used by orchestration tools to route containers
com.example.version	`v2.1.0`	Application version	Helps in tracking and updating containers
com.example.owner	`dev-team`	Team responsible for the container	Aids in team accountability and management
com.example.backup	`true`	Indicates if container should be backed up	Used by backup scripts to identify containers

Example: Applying Labels During Build

docker build --label com.example.version=v2.1.0 \
  --label com.example.environment=production \
  --label com.example.owner=dev-team \
  -t myapp:latest .

Example: Filtering Containers by Labels

docker ps --filter label=com.example.environment=production

Note: Labels are stored as key-value pairs and can be used for filtering, tagging, and automation purposes.

6. Implementing Labeling Standards

Example: Setting Standardized Labels

docker build \
  --label org.opencontainers.image.title="MyApp" \
  --label org.opencontainers.image.version=1.2.3 \
  --label org.opencontainers.image.authors="Dev Team" \
  --label org.opencontainers.image.documentation="https://docs.example.com" \
  -t myapp:1.2.3 .

Label Key	Value Format	Description	Usage
org.opencontainers.image.title	`string`	Human-readable title of the image	Display name in UIs
org.opencontainers.image.version	`string`	Version of the image	Version tracking and updates
org.opencontainers.image.authors	`string`	Author or maintainer of the image	Ownership and contact info
org.opencontainers.image.documentation	`URL`	Documentation URL for the image	Link to project docs
org.opencontainers.image.source	`URL`	Source code repository URL	Link to source code
org.opencontainers.image.license	`string`	License identifier (SPDX format)	Compliance and attribution

Note: These labels follow the Open Container Initiative (OCI) image spec for standardization.

Workflow: Applying Labels to Existing Images

Tag the image with new labels using docker build
Use docker inspect to verify labels are applied
Push image to registry with updated labels

Comparison: Labeling Approaches

Build-time labels: Set during docker build, immutable after build
Runtime labels: Applied via docker label command (not supported in all versions)
Registry labels: Stored in registry metadata (requires registry support)

7. Viewing Container Labels

Command	Description	Example
docker inspect	Displays detailed information about a container, including labels	`docker inspect --format="{{.Config.Labels}}" container_name`
docker ps	Lists running containers with label information if available	`docker ps --format "table {{.Names}}\t{{.Labels}}"`
docker ps -a	Lists all containers (running and stopped) with labels	`docker ps -a --format "table {{.Names}}\t{{.Labels}}"`

Example: Inspecting Labels Using docker inspect

docker inspect --format="{{.Config.Labels}}" my_container

Example: Filtering Containers by Label

docker ps --filter "label=environment=production"

8. Updating Container Labels

Method	Description	Notes
docker label set	Sets labels on a running container	Available in Docker 20.10+
docker run --label	Assigns labels at container creation time	Labels are immutable once set
docker commit --label	Applies labels to a container's image	Useful for creating labeled base images

Example: Setting labels on a running container

docker label set my-container com.example.environment=production

Example: Creating a container with labels

docker run --label com.example.version=1.0 --label com.example.team=backend nginx

Note: Labels are stored as key-value pairs and can be used for filtering, organization, and metadata purposes.

9. Using Labels with Orchestrators

Orchestrator	Label Usage	Examples	Notes
Docker Swarm	Labels used for service placement and filtering	`"com.example.environment=production"`	Labels help define service constraints and resource allocation
Kubernetes	Labels used for pod selection and service discovery	`"app=nginx"`	Labels are used in selectors and annotations for orchestration
Amazon ECS	Labels used for task and service definitions	`"aws.ecs.cluster=production"`	Labels can be used for task placement and resource grouping
Azure Container Instances	Labels used for grouping and identifying containers	`"team=backend"`	Labels help in organizing and managing container instances

Example: Docker Swarm Label Usage

docker service create \
  --label com.example.environment=production \
  --label com.example.team=backend \
  nginx

Example: Kubernetes Label Usage

apiVersion: v1
kind: Pod
metadata:
  labels:
    app: nginx
    version: v1.0
spec:
  containers:
  - name: nginx
    image: nginx:latest

10. Implementing Metadata Conventions

Convention	Description	Example
org.opencontainers.image.title	Human-readable title of the image	`"MyApp"`
org.opencontainers.image.version	Version of the image	`"v1.2.3"`
org.opencontainers.image.description	Short description of the image	`"A web application server"`
org.opencontainers.image.url	URL to the project homepage	`"https://myapp.example.com"`
org.opencontainers.image.documentation	URL to documentation	`"https://docs.myapp.example.com"`
org.opencontainers.image.source	URL to source code repository	`"https://github.com/myorg/myapp"`
org.opencontainers.image.revision	Source control revision identifier	`"a1b2c3d4"`
org.opencontainers.image.licenses	License(s) for the image content	`"MIT"`
org.opencontainers.image.authors	Author(s) of the image	`"John Doe <john@example.com>"`
org.opencontainers.image.vendor	Vendor or maintainer of the image	`"MyOrg"`

Example: Setting Metadata Labels in Dockerfile

FROM node:20-alpine
LABEL org.opencontainers.image.title="MyApp"
LABEL org.opencontainers.image.version="v1.2.3"
LABEL org.opencontainers.image.description="A web application server"
LABEL org.opencontainers.image.url="https://myapp.example.com"
LABEL org.opencontainers.image.documentation="https://docs.myapp.example.com"
LABEL org.opencontainers.image.source="https://github.com/myorg/myapp"
LABEL org.opencontainers.image.revision="a1b2c3d4"
LABEL org.opencontainers.image.licenses="MIT"
LABEL org.opencontainers.image.authors="John Doe <john@example.com>"
LABEL org.opencontainers.image.vendor="MyOrg"
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

Note: These labels follow the Open Container Initiative Image Specification for interoperability.