You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Example for changing the CRD scope from namespace to cluster](#example-for-changing-the-crd-scope-from-namespace-to-cluster)
11
+
12
+
## Overview
2
13
3
14
A namespace-scoped operator watches and manages resources in a single namespace, whereas a cluster-scoped operator watches and manages resources cluster-wide. Namespace-scoped operators are preferred because of their flexibility. They enable decoupled upgrades, namespace isolation for failures and monitoring, and differing API definitions.
4
15
5
16
However, there are use cases where a cluster-scoped operator may make sense. For example, the [cert-manager](https://github.com/jetstack/cert-manager) operator is often deployed with cluster-scoped permissions and watches so that it can manage issuing certificates for an entire cluster.
6
17
18
+
## Namespace-scoped operator usage
19
+
20
+
This scope is ideal for operator projects which will control resources just in one namespace, which is where the operator is deployed.
21
+
22
+
> **NOTE:** Initial projects created by `operator-sdk` are namespace-scoped by default which means that it will NOT have a `ClusterRole` defined in the `deploy/role_binding.yaml`.
23
+
24
+
## Cluster-scoped operator usage
25
+
26
+
This scope is ideal for operator projects which will control resources in more than one namespace.
27
+
28
+
### Changed required for a cluster-scoped operator
29
+
7
30
The SDK scaffolds operators to be namespaced by default but with a few modifications to the default manifests the operator can be run as cluster-scoped.
8
31
9
32
*`deploy/operator.yaml`:
@@ -15,21 +38,7 @@ The SDK scaffolds operators to be namespaced by default but with a few modificat
15
38
* Use `ClusterRole` instead of `Role` for `roleRef`
16
39
* Set the subject namespace to the namespace in which the operator is deployed.
17
40
18
-
## CRD scope
19
-
20
-
Additionally 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.
21
-
22
-
> **NOTE**: Cluster-scoped CRDs are **NOT** supported with the Helm operator. While Helm releases can create cluster-scoped resources, Helm's design requires the release itself to be created in a specific namespace. Since the Helm operator uses a 1-to-1 mapping between a CR and a Helm release, Helm's namespace-scoped release requirement extends to Helm operator's namespace-scoped CR requirement.
23
-
24
-
For each CRD that needs to be cluster-scoped, update its manifest to be cluster-scoped.
25
-
26
-
*`deploy/crds/<full group>_<resource>_crd.yaml`
27
-
* Set `spec.scope: Cluster`
28
-
29
-
To ensure that the CRD is always generated with `scope: Cluster`, add the tag `// +kubebuilder:resource:path=<resource>,scope=Cluster`, or if already present replace `scope={Namespaced -> Cluster}`, above the CRD's Go type defintion in `pkg/apis/<group>/<version>/<kind>_types.go`. The `<resource>` element must be the lower-case plural of the CRD's Kind, `spec.names.plural`.
30
-
31
-
32
-
## Example for cluster scoped operator
41
+
### Example for cluster-scoped operator
33
42
34
43
With the above changes the specified manifests should look as follows:
35
44
@@ -75,17 +84,48 @@ With the above changes the specified manifests should look as follows:
Additionally 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.
91
+
92
+
> **NOTE**: Cluster-scoped CRDs are **NOT** supported with the Helm operator. While Helm releases can create cluster-scoped resources, Helm's design requires the release itself to be created in a specific namespace. Since the Helm operator uses a 1-to-1 mapping between a CR and a Helm release, Helm's namespace-scoped release requirement extends to Helm operator's namespace-scoped CR requirement.
93
+
94
+
For each CRD that needs to be cluster-scoped, update its manifest to be cluster-scoped.
95
+
96
+
* `deploy/crds/<full group>_<resource>_crd.yaml`
97
+
* Set `spec.scope: Cluster`
98
+
99
+
To ensure that the CRD is always generated with `scope: Cluster`, add the tag `// +kubebuilder:resource:path=<resource>,scope=Cluster`, or if already present replace `scope={Namespaced -> Cluster}`, above the CRD's Go type definition in `pkg/apis/<group>/<version>/<kind>_types.go`. Note that the `<resource>` element must be the same lower-case plural value of the CRD's Kind, `spec.names.plural`.
100
+
101
+
### CRD cluster-scoped usage
102
+
103
+
This scope is ideal for the cases where an instance(CR) of some Kind(CRD) will be used in more than one namespace instead of a specific one.
104
+
105
+
> **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][manager_user_guide] topic in the user guide and the [Manager Options][manager_options].
106
+
107
+
### Example for changing the CRD scope from namespace to cluster
108
+
109
+
- Check the `spec.names.plural` in the CRD's Kind YAML file
110
+
111
+
* `deploy/crds/cache_v1alpha1_memcached_crd.yaml`
79
112
```YAML
80
113
apiVersion: apiextensions.k8s.io/v1beta1
81
114
kind: CustomResourceDefinition
82
115
metadata:
83
116
name: memcacheds.cache.example.com
84
117
spec:
85
118
group: cache.example.com
86
-
...
87
-
scope: Cluster
88
-
```
119
+
names:
120
+
kind: Memcached
121
+
listKind: MemcachedList
122
+
plural: memcacheds
123
+
singular: memcached
124
+
scope: Namespaced
125
+
```
126
+
127
+
- Update the `pkg/apis/<group>/<version>/<kind>_types.go` by adding the tag `// +kubebuilder:resource:path=<resource>,scope=Cluster`
@@ -100,4 +140,21 @@ With the above changes the specified manifests should look as follows:
100
140
Spec MemcachedSpec `json:"spec,omitempty"`
101
141
Status MemcachedStatus `json:"status,omitempty"`
102
142
}
143
+
```
144
+
- Execute the command `operator-sdk generate openapi`, then you should be able to check that the CRD was updated with the cluster scope as in the following example:
0 commit comments