Skip to content

Commit eb97367

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #4035 from camilamacedo86/pr-scope
📖 Add crd-scope and operator-scope documentation
2 parents dcc031d + c01fee0 commit eb97367

File tree

2 files changed

+120
-0
lines changed

2 files changed

+120
-0
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,8 @@
9696
- [Artifacts](./reference/artifacts.md)
9797
- [Platform Support](./reference/platform.md)
9898

99+
- [Manager and CRDs Scope](./reference/scopes)
100+
99101
- [Sub-Module Layouts](./reference/submodule-layouts.md)
100102
- [Using an external Type / API](./reference/using_an_external_type.md)
101103

‎docs/book/src/reference/scopes.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Understanding and Setting Scopes for Managers (Operators) and CRDs
2+
3+
This section covers the configuration of the operational and resource scopes
4+
within a Kubebuilder project. Managers("Operators") in Kubernetes can be scoped to either
5+
specific namespaces or the entire cluster, influencing how resources are watched and managed.
6+
7+
Additionally, CustomResourceDefinitions (CRDs) can be defined to be either
8+
namespace-scoped or cluster-scoped, affecting their availability
9+
across the cluster.
10+
11+
## Configuring Manager Scope
12+
13+
Managers can operate under different scopes depending on
14+
the resources they need to handle:
15+
16+
### (Default) Watching All Namespaces
17+
18+
By default, if no namespace is specified, the manager will observe all namespaces.
19+
This is configured as follows:
20+
21+
```go
22+
mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
23+
...
24+
})
25+
```
26+
27+
### Watching a Single Namespace
28+
29+
To constrain the manager to monitor resources within a specific namespace, set the Namespace option:
30+
31+
```go
32+
mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
33+
...
34+
Cache: cache.Options{
35+
DefaultNamespaces: map[string]cache.Config{"operator-namespace": cache.Config{}},
36+
},
37+
})
38+
```
39+
40+
### Watching Multiple Namespaces
41+
42+
A manager can also be configured to watch a specified set of namespaces using [Cache Config][CacheConfig]:
43+
44+
```go
45+
mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
46+
...
47+
Cache: cache.Options{
48+
DefaultNamespaces: map[string]cache.Config{
49+
"operator-namespace1": cache.Config{},
50+
"operator-namespace2": cache.Config{},
51+
},
52+
},
53+
})
54+
```
55+
56+
## Configuring CRD Scope
57+
58+
The scope of CRDs determines their visibility either within specific namespaces or across the entire cluster.
59+
60+
### Namespace-scoped CRDs
61+
62+
Namespace-scoped CRDs are suitable when resources need to be isolated to specific namespaces.
63+
This setting helps manage resources related to particular teams or applications.
64+
However, it is important to note that due to the unique definition of CRDs (Custom Resource Definitions) in Kubernetes, testing a new version of a CRD is not straightforward. Proper versioning and conversion strategies need to be implemented (example in our [kubebuilder tutorial][kubebuilder-multiversion-tutorial]), and coordination is required to manage which manager instance handles the conversion (see the official [kubernetes documentation][k8s-crd-conversion] about this).
65+
Additionally, the namespace scope must be taken into account for mutating and validating webhook configurations to ensure they are correctly applied within the intended scope. This facilitates a more controlled and phased rollout strategy.
66+
67+
### Cluster-scoped CRDs
68+
69+
For resources that need to be accessible and manageable across the entire cluster,
70+
such as shared configurations or global resources, cluster-scoped CRDs are used.
71+
72+
#### Configuring CRDs Scopes
73+
74+
**When the API is created**
75+
76+
The scope of a CRD is defined when generating its manifest.
77+
Kubebuilder facilitates this through its API creation command.
78+
79+
By default, APIs are created with CRD scope as namespaced. However,
80+
for cluster-wide you use `--namespaced=false`, i.e.:
81+
82+
```shell
83+
kubebuilder create api --group cache --version v1alpha1 --kind Memcached --resource=true --controller=true --namespaced=false
84+
```
85+
86+
This command generates the CRD with the Cluster scope,
87+
meaning it will be accessible and manageable across all
88+
namespaces in the cluster.
89+
90+
**By updating existing APIs**
91+
92+
After you create an API you are still able to change the scope.
93+
For example, to configure a CRD to be cluster-wide,
94+
add the `+kubebuilder:resource:scope=Cluster` marker
95+
above the API type definition in your Go file.
96+
Here is an example:
97+
98+
```go
99+
//+kubebuilder:object:root=true
100+
//+kubebuilder:subresource:status
101+
//+kubebuilder:resource:scope=Cluster,shortName=mc
102+
103+
...
104+
```
105+
106+
After setting the desired scope with markers,
107+
run `make manifests` to generate the files.
108+
This command invokes [`controller-gen`][controller-tools] to generate the CRD manifests
109+
according to the markers specified in your Go files.
110+
111+
The generated manifests will then correctly reflect
112+
the scope as either Cluster or Namespaced without
113+
needing manual adjustment in the YAML files.
114+
115+
[controller-tools]: https://sigs.k8s.io/controller-tools
116+
[CacheConfig]: https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/cache#Config
117+
[kubebuilder-multiversion-tutorial]: https://book.kubebuilder.io/multiversion-tutorial/tutorial
118+
[k8s-crd-conversion]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#webhook-conversion

0 commit comments

Comments
 (0)