Skip to content

Commit 95dab95

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request kubernetes-sigs#4173 from camilamacedo86/add-doc-scaffold-marker
📖 : add documentation about kubebuilder:scaffold marker
2 parents 662f78f + 735b77c commit 95dab95

File tree

3 files changed

+122
-0
lines changed

3 files changed

+122
-0
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@
9090
- [Webhook](./reference/markers/webhook.md)
9191
- [Object/DeepCopy](./reference/markers/object.md)
9292
- [RBAC](./reference/markers/rbac.md)
93+
- [Scaffold](./reference/markers/scaffold.md)
9394

9495
- [controller-gen CLI](./reference/controller-gen.md)
9596
- [completion](./reference/completion.md)

‎docs/book/src/reference/markers/scaffold.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Scaffold
2+
3+
The `+kubebuilder:scaffold` marker is a key part of the Kubebuilder scaffolding system. It marks locations in generated
4+
files where additional code will be injected as new resources (such as controllers, webhooks, or APIs) are scaffolded.
5+
This enables Kubebuilder to seamlessly integrate newly generated components into the project without affecting
6+
user-defined code.
7+
8+
<aside class="note warning">
9+
<H1>If you delete or change the `+kubebuilder:scaffold` markers</H1>
10+
11+
The Kubebuilder CLI specifically looks for these markers in expected
12+
files during code generation. If the marker is moved or removed, the CLI will
13+
not be able to inject the necessary code, and the scaffolding process may
14+
fail or behave unexpectedly.
15+
16+
</aside>
17+
18+
## How It Works
19+
20+
When you scaffold a new resource using the Kubebuilder CLI (e.g., `kubebuilder create api`),
21+
the CLI identifies `+kubebuilder:scaffold` markers in key locations and uses them as placeholders
22+
to insert the required imports and registration code.
23+
24+
## Example Usage in `main.go`
25+
26+
Here is how the `+kubebuilder:scaffold` marker is used in a typical `main.go` file. To illustrate how it works, consider the following command to create a new API:
27+
28+
```shell
29+
kubebuilder create api --group crew --version v1 --kind Admiral --controller=true --resource=true
30+
```
31+
32+
### To Add New Imports
33+
34+
The `+kubebuilder:scaffold:imports` marker allows the Kubebuilder CLI to inject additional imports,
35+
such as for new controllers or webhooks. When we create a new API, the CLI automatically adds the required import paths
36+
in this section.
37+
38+
For example, after creating the `Admiral` API in a single-group layout,
39+
the CLI will add `crewv1 "<repo-path>/api/v1"` to the imports:
40+
41+
```go
42+
import (
43+
"crypto/tls"
44+
"flag"
45+
"os"
46+
47+
// Import all Kubernetes client auth plugins (e.g. Azure, GCP, OIDC, etc.)
48+
// to ensure that exec-entrypoint and run can make use of them.
49+
_ "k8s.io/client-go/plugin/pkg/client/auth"
50+
...
51+
crewv1 "sigs.k8s.io/kubebuilder/testdata/project-v4/api/v1"
52+
// +kubebuilder:scaffold:imports
53+
)
54+
```
55+
56+
### To Register a New Scheme
57+
58+
The `+kubebuilder:scaffold:scheme` marker is used to register newly created API versions with the runtime scheme,
59+
ensuring the API types are recognized by the manager.
60+
61+
For example, after creating the Admiral API, the CLI will inject the
62+
following code into the `init()` function to register the scheme:
63+
64+
65+
```go
66+
func init() {
67+
...
68+
utilruntime.Must(crewv1.AddToScheme(scheme))
69+
// +kubebuilder:scaffold:scheme
70+
}
71+
```
72+
73+
## To Set Up a Controller
74+
75+
When we create a new controller (e.g., for Admiral), the Kubebuilder CLI injects the controller
76+
setup code into the manager using the `+kubebuilder:scaffold:builder` marker. This marker indicates where
77+
the setup code for new controllers should be added.
78+
79+
For example, after creating the `AdmiralReconciler`, the CLI will add the following code
80+
to register the controller with the manager:
81+
82+
```go
83+
if err = (&crewv1.AdmiralReconciler{
84+
Client: mgr.GetClient(),
85+
Scheme: mgr.GetScheme(),
86+
}).SetupWithManager(mgr); err != nil {
87+
setupLog.Error(err, "unable to create controller", "controller", "Admiral")
88+
os.Exit(1)
89+
}
90+
// +kubebuilder:scaffold:builder
91+
```
92+
93+
The `+kubebuilder:scaffold:builder` marker ensures that newly scaffolded controllers are
94+
properly registered with the manager, so that the controller can reconcile the resource.
95+
96+
## List of `+kubebuilder:scaffold` Markers
97+
98+
| Marker | Usual Location | Function |
99+
|--------------------------------------------|------------------------------|---------------------------------------------------------------------------------|
100+
| `+kubebuilder:scaffold:imports` | `main.go` | Marks where imports for new controllers, webhooks, or APIs should be injected. |
101+
| `+kubebuilder:scaffold:scheme` | `init()` in `main.go` | Used to add API versions to the scheme for runtime. |
102+
| `+kubebuilder:scaffold:builder` | `main.go` | Marks where new controllers should be registered with the manager. |
103+
| `+kubebuilder:scaffold:webhook` | `webhooks suite tests` files | Marks where webhook setup functions are added. |
104+
| `+kubebuilder:scaffold:crdkustomizeresource`| `config/crd` | Marks where CRD custom resource patches are added. |
105+
| `+kubebuilder:scaffold:crdkustomizewebhookpatch` | `config/crd` | Marks where CRD webhook patches are added. |
106+
| `+kubebuilder:scaffold:crdkustomizecainjectionpatch` | `config/crd` | Marks where CA injection patches are added for the webhook. |
107+
| `+kubebuilder:scaffold:manifestskustomizesamples` | `config/samples` | Marks where Kustomize sample manifests are injected. |
108+
| `+kubebuilder:scaffold:e2e-webhooks-checks` | `test/e2e` | Adds e2e checks for webhooks depending on the types of webhooks scaffolded. |
109+
110+
<aside class="note">
111+
<h1>Creating Your Own Markers</h1>
112+
113+
If you are using Kubebuilder as a library to create [your own plugins](./../../plugins/creating-plugins.md) and extend its CLI functionalities,
114+
you have the flexibility to define and use your own markers. To implement your own markers, refer to the [kubebuilder/v4/pkg/machinery](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/machinery),
115+
which provides tools to create and manage markers effectively.
116+
117+
</aside>
118+
119+
120+

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
- [Webhook](markers/webhook.md)
2727
- [Object/DeepCopy](markers/object.md)
2828
- [RBAC](markers/rbac.md)
29+
- [Scaffold](markers/scaffold.md)
2930

3031
- [Monitoring with Pprof](pprof-tutorial.md)
3132
- [controller-gen CLI](controller-gen.md)

0 commit comments

Comments
 (0)