UUID in Docker

Docker uses 256-bit hex identifiers (not standard UUIDs) for its internal objects. When building applications that run in Docker, you often need to generate, pass, and persist UUID values for instance identification, distributed tracing, and database primary keys. Docker’s reference documentation covers the container ID format, but application-level UUIDs are a separate concern.

Docker’s internal identifiers

Docker container, image, network, and volume IDs are SHA-256 digests truncated or abbreviated:

# Full container ID (64 hex chars = 256 bits)
docker inspect mycontainer --format '{{.Id}}'
# a3b2c1d0e9f8...64chars

# Short ID (12 chars, shown in docker ps)
docker ps --format '{{.ID}}'
# a3b2c1d0e9f8

# These are NOT RFC 9562 UUIDs — no version nibble, no variant bits

Do not use Docker container IDs as application-level identifiers. They are non-portable (unique only on a single host), change on container restart, and are not RFC-compliant UUIDs.

Passing UUIDs to containers at runtime

A common pattern is assigning each container instance a stable UUID for distributed tracing and log correlation:

# Generate once and pass to the container
export INSTANCE_ID=$(uuidgen)           # UUID v4 on most Linux systems
docker run -e INSTANCE_ID="$INSTANCE_ID" myapp

Inside the container, INSTANCE_ID is available as a standard environment variable. Every log line can include it for correlation across distributed traces.

For UUID v7 (time-sortable), generate it from your application’s language library rather than uuidgen (which only produces v1 or v4):

# Node.js — generate UUID v7 for container environment
INSTANCE_ID=$(node -e "const {v7}=require('uuid'); console.log(v7())")
docker run -e INSTANCE_ID="$INSTANCE_ID" myapp

Docker Compose — instance UUIDs

In a Docker Compose file, use shell variable interpolation to assign a UUID at docker compose up time:

# docker-compose.yml
services:
  api:
    image: myapp:latest
    environment:
      # Reads from .env file or shell environment
      - INSTANCE_ID=${INSTANCE_ID}
      - NODE_ENV=production

# .env file or CI/CD pipeline
INSTANCE_ID=018fbe3a-4c5d-7b12-8abc-0123456789ab

For a fresh UUID on every docker compose up:

INSTANCE_ID=$(uuidgen) docker compose up -d

Docker Secrets for UUID-format tokens

If your UUID is a security-sensitive token (API key, signing key, session secret), use Docker Secrets instead of environment variables. Secrets are mounted as files inside the container and do not appear in docker inspect output:

# Create a secret from a UUID v4
uuidgen | docker secret create api_signing_key -

# Reference in Docker Swarm compose file
services:
  api:
    image: myapp:latest
    secrets:
      - api_signing_key

secrets:
  api_signing_key:
    external: true

Inside the container, the secret is available at /run/secrets/api_signing_key. Read it at startup:

// Node.js — read UUID secret from Docker Secrets mount
import { readFileSync } from 'fs';

const signingKey = readFileSync('/run/secrets/api_signing_key', 'utf8').trim();

Kubernetes and container orchestration

In Kubernetes (which runs Docker-compatible containers), pod names include a random suffix but are not UUIDs. Kubernetes does assign RFC 4122-compliant UUIDs to pods, nodes, namespaces, and other resources via the uid field, as described in the Kubernetes object names and UIDs documentation:

kubectl get pod mypod -o jsonpath='{.metadata.uid}'
# 018fbe3a-4c5d-4b12-8abc-0123456789ab

These are Kubernetes-managed UUIDs — do not use them as application primary keys. See UUID in Kubernetes for the full picture.

UUID v7 for containerized database services

When running PostgreSQL in Docker, enable UUID v7 via the built-in function (PostgreSQL 18+) or the pg_uuidv7 extension for earlier versions. No Docker-specific configuration is needed:

FROM postgres:18-alpine

# pg_uuidv7 extension for PostgreSQL 14–17
# (not needed for PG 18 — uuidv7() is built-in)
RUN apk add --no-cache postgresql14-dev make gcc && \
    git clone https://github.com/fboulnois/pg_uuidv7 /tmp/pg_uuidv7 && \
    cd /tmp/pg_uuidv7 && make && make install

-- In your init SQL script, enable for PostgreSQL 14–17:
CREATE EXTENSION IF NOT EXISTS pg_uuidv7;

-- For PostgreSQL 18 — uuidv7() is available with no extension:
SELECT uuidv7();

Multi-container tracing with UUID v7

UUID v7’s timestamp prefix is useful for distributed tracing across containers: a trace ID that starts with a UUID v7 value is both globally unique and naturally ordered by creation time, simplifying log aggregation:

// api-service — generate trace ID for request
import { v7 as uuidv7 } from 'uuid';

app.use((req, res, next) => {
    req.traceId = req.headers['x-trace-id'] || uuidv7();
    res.setHeader('x-trace-id', req.traceId);
    next();
});

// downstream-service — propagate trace ID
const response = await fetch('http://db-service/query', {
    headers: { 'x-trace-id': req.traceId }
});

Log aggregation tools (Loki, Elasticsearch, CloudWatch) can then sort by traceId to reconstruct request timelines across containers without a separate timestamp field. This pattern aligns with the OpenTelemetry context propagation specification, which uses a similar trace ID header (traceparent) for distributed tracing across services.

Related reading

• UUID in Kubernetes — pod UIDs, namespace UUIDs, and application patterns
• UUID Generation Strategies — client, server, and database generation trade-offs
• UUID in Databases — PostgreSQL and MySQL configuration for containers
• UUID v7 Generator — generate RFC 9562 v7 values for testing

External references

• Docker reference documentation — container IDs, environment variables, and secrets
• Docker Secrets — secure storage for sensitive values including UUID-format tokens
• pg_uuidv7 on GitHub — UUID v7 extension for PostgreSQL 14–17
• RFC 9562 — UUID specification — the IETF standard for UUID v4 and v7