Kubernetes CRD Naming Management

Kubernetes CRD Naming Management is the set of conventions, constraints, and operational practices governing the identifiers assigned to a Custom Resource Definition and its resulting resource type, covering group naming, the mandatory <plural>.<group> object name, kind capitalization rules, short name allocation, and the collision-avoidance discipline required when multiple CRDs are installed into the same cluster by different parties.

The Mandatory Object Name Convention

Plural-Dot-Group Requirement

The API server enforces that a CRD's own metadata.name be exactly the concatenation of its plural resource name and its API group, separated by a dot; this is not a stylistic recommendation but a hard validation rule rejected at creation time if violated.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: cronbackups.batch.example.com
spec:
  group: batch.example.com
  names:
    plural: cronbackups
    singular: cronbackup
    kind: CronBackup
    listKind: CronBackupList

kubectl apply -f cronbackup-crd.yaml
# error if metadata.name != cronbackups.batch.example.com

Why the Convention Exists

Because CustomResourceDefinition objects are themselves cluster-scoped and share a single flat namespace of names, encoding both the plural and the group into the object name is what guarantees two unrelated CRDs can never collide even if they happen to choose the same plural resource name, since their groups necessarily differ.

Choosing the API Group

Domain-Based Group Naming

Groups are conventionally a reverse-DNS-style domain the CRD author controls, such as databases.example.com or batch.acme.io, which is what prevents two independently developed Operators from ever registering conflicting CRDs even without any coordination between their authors.

spec:
  group: databases.example.com

Choosing a generic, ungoverned group name such as custom.io or apps.local risks collision with another vendor's CRD of the same plural name installed in the same cluster, since the combination of plural and group is the only global uniqueness guarantee the API server enforces.

Group Stability Across Versions

The API group is fixed for the lifetime of a CRD's identity; changing it is equivalent to defining an entirely new resource type with no automatic migration path, so group naming decisions make at CRD design time are effectively permanent for that resource's existing installed base.

Kind, Singular, and Plural Rules

Casing Conventions

kind follows PascalCase (CronBackup), while plural and singular are lowercase (cronbackups, cronbackup), matching the convention used by every built-in Kubernetes resource type and expected by tooling that inspects resource metadata generically.

names:
  kind: CronBackup
  singular: cronbackup
  plural: cronbackups
  listKind: CronBackupList

listKind Derivation

listKind is conventionally kind with List appended, and while it can technically be set independently, deviating from this convention breaks the expectations of client-go code generation tooling and controller-runtime scaffolding that assume the standard suffix.

Short Names and Categories

Short Name Allocation

names:
  shortNames: ["cb", "cbackup"]

Short names enable abbreviated kubectl commands (kubectl get cb) but are a shared, unscoped namespace across the entire cluster; a short name already claimed by another installed CRD, or worse, by a built-in resource abbreviation, silently causes kubectl to require disambiguation or resolve to the wrong resource, making short name selection a collision risk that must be checked against existing cluster CRDs before assignment.

kubectl api-resources | grep -w cb

Categories

names:
  categories: ["all"]

Adding a resource to the all category makes it appear in kubectl get all output, which is convenient for operator-authored resources meant to be visible in routine cluster inspection, but should be applied deliberately since it also means the resource appears, potentially unexpectedly, in every broad listing command cluster-wide.

Multi-Tenant and Multi-Vendor Naming Discipline

Avoiding Cross-Operator Collisions

In clusters that install CRDs from multiple independent sources — a service mesh, a database Operator, an internal platform team's custom resources — naming management requires auditing the full set of installed CRD groups, kinds, and short names before introducing a new one, since the API server's uniqueness enforcement only guards against exact plural-group collisions, not against kind-name or short-name ambiguity that confuses operators using kubectl interactively.

kubectl get crds -o custom-columns=NAME:.metadata.name,KIND:.spec.names.kind

Relationship to CRD Management and Spec Structure

Naming management is the identity layer beneath the broader CRD spec structure and lifecycle management practices: while spec structure defines how a CRD's versions and schema are configured, and CRD management governs how those versions evolve safely, naming management is what ensures the resource can be uniquely and unambiguously referred to, by the API server, by kubectl, and by every controller and human operator interacting with the cluster, for as long as that CRD remains installed.