Add `--domain` flag and reject ambiguous external GVK resolution

Author: camilamacedo86Created Jul 14, 2026Updated Jul 14, 2026
Labelskind/feature

What should happen?

Follow-up to #5792.

Add a per-resource --domain flag to commands using --group, --version, and --kind.

Domain resolution should follow this order:

  1. Use --domain when provided.
  2. Use --external-api-domain for external APIs when provided.
  3. If exactly one existing resource matches Group, Version, and Kind, use its stored domain.
  4. If no resource matches, use the project domain.
  5. If multiple resources match the same Group, Version, and Kind, return an error requiring an explicit domain.

Example error:

multiple resources match Group "example", Version "v1", and Kind "Widget"; specify --domain to select the intended resource

If both --domain and --external-api-domain are provided with different values, the command should fail.

Why?

A resource is identified by its complete Group, Version, Kind, and Domain.

Multiple external resources may legitimately share the same Group, Version, and Kind while having different domains. Kubebuilder should not silently fall back to the project domain or guess which resource is intended.

This change would:

  • allow a fresh resource to set its domain directly;
  • preserve full-GVK equality;
  • prevent incorrect domain selection;
  • make ambiguous resource resolution impossible without explicit input;
  • remove the remaining hard-coded project-domain behavior.

Example

bash
kubebuilder create api \
  --group example \
  --version v1 \
  --kind Widget \
  --domain vendor.io

Acceptance criteria

  • Add --domain to the common resource flags.
  • A fresh resource uses --domain when provided.
  • A fresh resource without --domain uses the project domain.
  • A unique existing G/V/K match uses its stored domain.
  • Multiple matching G/V/K resources produce an actionable error.
  • --domain disambiguates using the complete GVK.
  • Conflicting --domain and --external-api-domain values produce an error.
  • Full-GVK equality behavior remains unchanged.
  • Add unit and integration tests for these cases.

Related pull request

Follow-up to #5792.

Source: kubernetes-sigs/kubebuilder