What is "domain" in kubebuilder scaffolding?

Question

The kubebuilder scaffolding command includes a repo and domain e.g.

kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project

I found following text in kubebuilder book about "domain":

domain: Store the domain of the project. This information can be provided by the user when the project is generate with the init sub-command and the domain flag. And domain: domain for groups (default "my.domain")

I understand domain is usually to set boundaries to avoid naming conflicts e.g. different teams in a company can use different domains/sub-domains and have freedom of choosing names under that domain/sub-domain. But in the context of a kubebuilder project:

• What name conflicts are we avoiding here ? What if teams are different but still they deploy to a shared cluster ? What if domain name itself is duplicate ? When do you figure out there's a conflict ?
• What are the functional implications of a domain e.g. on CRDs, on APIs etc. ?
• Can you change it later and any gotchas ?
• Can you have no domain at all, not even default - my.domain ?

I'm aware that these answers could be much longer for a post if elaborated, any guidance or material in this context would help. Thanks.

Answer 1

The domain is the Kubernetes 'group', which as you describe is used for namespacing and avoiding naming conflicts. A 'group' along with a 'version' and a 'kind' uniquely identify a type of resource that the Kubernetes API server knows about.

To answer your questions:

• The name conflicts you are avoiding are generally if two separate groups have a concept they want to represent with a similar name. Generally, the friendly name of a resource goes in the 'kind' field, e.g. 'Bucket'. If you have two separate concepts of a bucket, then without the existence of the 'group', you might call one kind: AWSBucket and the other kind: GCPBucket. With groups, you can do the following:

  apiVersion: aws.amazon.com/v1
  kind: Bucket
  

  as separate from

  apiVersion: gcp.google.com/v1
  kind: Bucket
  

• The previous dot-point hints at this. Functionally, the 'domain'/'group' along with the version form the apiVersion field of any resources you provision against the CRD, and will form the group field of the Custom Resource Definition.

• You can change it later. There's the obvious gotcha that some other team might already be using your namespace. You'll also need to update and re-deploy any resources that use this domain as part of a custom resource. Practically, this might as well be a new API from the point of view of Kubernetes. You'll start again with no resources of that kind, and so you'll need to update and re-deploy any resources you've created against the old kind. This may cause issues, though it should be possible to handle these as part of a controller (e.g. migrate any controller state recorded against the old resource to the new resource).

• No, it's not possible to not define a domain. I'm not sure what Kubebuilder will do if you don't provide this flag. But practically, group is a required field on the CustomResourceDefinition resource that is used to register the custom resource with Kubernetes. See the API documentation for CustomResourceDefinition

Resources:

• Kubernetes docs on API groups and versioning
• Kubernetes docs on using API groups
• Kubebuilder docs on groups, versions and kinds