Kubernetes Naming & Labeling

Resource naming conventions, label taxonomy, and annotation standards

Language / Topic

Kubernetes

Rules

Kubernetes Naming & Labeling · balanced balanced

- Use the standard Kubernetes label taxonomy: app.kubernetes.io/name, /version, /component, /part-of

- Name resources with lowercase, hyphen-separated names: my-app-api, not myAppApi or my_app_api

- Organize resources by namespace: one namespace per team or per application environment

- Use annotations for non-identifying metadata: build URLs, git commit SHAs, documentation links

- Apply consistent labels across all resource types for effective kubectl filtering and monitoring queries

- Standard labels on all resources: app.kubernetes.io/name, /instance, /version, /component, /part-of, /managed-by

- Resource naming: lowercase, hyphen-separated, DNS-compatible: my-app-api, order-service, redis-cache

- Namespace strategy: per-environment (dev/staging/prod) or per-team (team-a/team-b) — not both simultaneously

- Annotations for metadata: build/pipeline-url, git/commit-sha, owner/team, docs/runbook-url

- Consistent labels enable: kubectl get pods -l app.kubernetes.io/name=my-app, Prometheus metric grouping

- Use label selectors in Services and NetworkPolicies that match on app.kubernetes.io/name and /component

- Name ConfigMaps and Secrets descriptively: my-app-config, my-app-db-credentials (not config1, secret1)

- Prefix custom labels with your domain: mycompany.com/team, mycompany.com/cost-center

- Keep resource names under 63 characters (DNS label limit); shorter is better for readability

- Use helm.sh/chart label for Helm-managed resources; argocd.argoproj.io/instance for ArgoCD-managed resources