CRD Scope

Overview

The CustomResourceDefinition (CRD) scope can also be changed for cluster-scoped operators so that there is only a single instance (for a given name) of the CRD to manage across the cluster.

The CRD manifests are generated in config/crd/bases. For each CRD that needs to be cluster-scoped, its manifest should specify spec.scope: Cluster.

To ensure that the CRD is always generated with scope: Cluster, add the marker // +kubebuilder:resource:path=<resource>,scope=Cluster, or if already present replace scope={Namespaced -> Cluster}, above the CRD’s Go type definition in api/<version>/<kind>_types.go or apis/<group>/<version>/<kind>_types.go if you are using the multigroup layout. Note that the <resource> element must be the same lower-case plural value of the CRD’s Kind, spec.names.plural.

CRD cluster-scoped usage

A cluster scope is ideal for operators that manage custom resources (CR’s) that can be created in more than one namespace in a cluster.

NOTE: When a Manager instance is created in the main.go file, it receives the namespace(s) as Options. These namespace(s) should be watched and cached for the Client which is provided by the Controllers. Only clients provided by cluster-scoped projects where the Namespace attribute is "" will be able to manage cluster-scoped CRD’s. For more information see the Manager topic in the user guide and the Manager Options.

Example for changing the CRD scope from Namespaced to Cluster

  • Check the spec.names.plural in the CRD’s Kind YAML file

  • /config/crd/bases/cache.example.com_memcacheds.yaml

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   annotations:
  5.     controller-gen.kubebuilder.io/version: v0.2.5
  6.   creationTimestamp: null
  7.   name: memcacheds.cache.example.com
  8. spec:
  9.   group: cache.example.com
  10.   names:
  11.     kind: Memcached
  12.     listKind: MemcachedList
  13.     plural: memcacheds
  14.     singular: memcached
  15.   scope: Namespaced
  16.   subresources:
  17.     status: {}
  18. ...

  • Update the apis/<version>/<kind>_types.go by adding the marker // +kubebuilder:resource:path=<resource>,scope=Cluster

  • api/v1alpha1/memcached_types.go

  1. // Memcached is the Schema for the memcacheds API
  2. // +kubebuilder:resource:path=memcacheds,scope=Cluster
  3. type Memcached struct {
  4.   metav1.TypeMeta   `json:",inline"`
  5.   metav1.ObjectMeta `json:"metadata,omitempty"`
  7.   Spec   MemcachedSpec   `json:"spec,omitempty"`
  8.   Status MemcachedStatus `json:"status,omitempty"`
  9. }

  • Run make manifests, to update the CRD manifest with the cluster scope setting, as in the following example:

  • /config/crd/bases/cache.example.com_memcacheds.yaml

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   annotations:
  5.     controller-gen.kubebuilder.io/version: v0.2.5
  6.   creationTimestamp: null
  7.   name: memcacheds.cache.example.com
  8. spec:
  9.   group: cache.example.com
  10.   names:
  11.     kind: Memcached
  12.     listKind: MemcachedList
  13.     plural: memcacheds
  14.     singular: memcached
  15.   scope: Cluster
  16.   subresources:
  17.     status: {}
  18. ...

Last modified August 5, 2020: doc: quickstart for Go projects (#3551) (7e029625)