📖 Add crd-scope and operator-scope documentation

[camilamacedo86]

This PR add a required info to let users know what is API and Manager scope as how to manage them.

Closes; #3623

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bavarianbidi, camilamacedo86

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[fengshunli]

The --namespaced=false parameter is optional. The default value is false. You can set it to true only when you are trying it out.

[fengshunli]

The --namespaced=false parameter is optional. The default value is false. You can set it to true only when you are trying it out.

[camilamacedo86]

Hi @fengshunli,

By default, ALL APIs/Custom Resource Definitions (CRDs) are not Cluster scoped. When you use the flag --namespaced=false, it will be ClusterScoped.

• You can check its definition in:

kubebuilder/pkg/model/resource/api.go

Lines 28 to 29 in dcc031d

	// Namespaced is true if the API is namespaced.
	Namespaced bool `json:"namespaced,omitempty"`

• Then, you can see the condition to add the ClusterScope Marker, which is ONLY set if --namespaced is false:

kubebuilder/pkg/plugins/golang/v4/scaffolds/internal/templates/api/types.go

Lines 94 to 95 in dcc031d

	{{- else if not .Resource.API.Namespaced }}
	// +kubebuilder:resource:scope=Cluster

You can also test this behavior locally to validate it:

1. Run kubebuilder create api --help
   You will see:

--namespaced           resource is namespaced (default true) <- See HERE

• To see how it works, create a project with kubebuilder init and then:

kubebuilder create api --group ship --version v1beta1 --kind Frigate

Check the marker in the API:

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// Frigate is the Schema for the frigates API
type Frigate struct {
....

• Next, run with the namespaced flag only:

kubebuilder create api --group ship --version v1beta1 --kind FrigateNamespacedEmpty --namespaced

You will see it still lacks the ClusterScope marker:

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// FrigateNamespacedEmpty is the Schema for the frigatenamespacedempties API
type FrigateNamespacedEmpty struct {

• Run with --namespaced=true:

kubebuilder create api --group ship --version v1beta1 --kind FrigateNamespacedTrue --namespaced=true

It still lacks the ClusterScope marker (default behavior):

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// FrigateNamespacedTrue is the Schema for the frigatenamespacedtrues API
type FrigateNamespacedTrue struct {
....

• Finally, run with --namespaced=false:

kubebuilder create api --group ship --version v1beta1 --kind FrigateNamespacedFalse --namespaced=false

Now, it includes the ClusterScope marker:

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:scope=Cluster // SEE HERE

// FrigateNamespacedFalse is the Schema for the frigatenamespacedfalses API
type FrigateNamespacedFalse struct {
....

I hope this helps!

[camilamacedo86]

We have an approval already/lgtm
Also, we can always accept contributions for improvements in follow up PRs
So, moving forward with this one