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:
- Use
--domainwhen provided. - Use
--external-api-domainfor external APIs when provided. - If exactly one existing resource matches Group, Version, and Kind, use its stored domain.
- If no resource matches, use the project domain.
- 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 resourceIf 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
kubebuilder create api \
--group example \
--version v1 \
--kind Widget \
--domain vendor.ioAcceptance criteria
- Add
--domainto the common resource flags. - A fresh resource uses
--domainwhen provided. - A fresh resource without
--domainuses the project domain. - A unique existing G/V/K match uses its stored domain.
- Multiple matching G/V/K resources produce an actionable error.
--domaindisambiguates using the complete GVK.- Conflicting
--domainand--external-api-domainvalues 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