From c980b867082b7fc63d60fa81a4dfca31a8eb5a97 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Sun, 15 Sep 2024 18:05:10 +0100 Subject: [PATCH] doc: add documenation about marker --- docs/book/src/SUMMARY.md | 1 + docs/book/src/reference/markers/scaffold.md | 123 ++++++++++++++++++++ docs/book/src/reference/reference.md | 1 + 3 files changed, 125 insertions(+) create mode 100644 docs/book/src/reference/markers/scaffold.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index cbb5a7a5697..1918230ec13 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -90,6 +90,7 @@ - [Webhook](./reference/markers/webhook.md) - [Object/DeepCopy](./reference/markers/object.md) - [RBAC](./reference/markers/rbac.md) + - [Scaffold](./reference/markers/scaffold.md) - [controller-gen CLI](./reference/controller-gen.md) - [completion](./reference/completion.md) diff --git a/docs/book/src/reference/markers/scaffold.md b/docs/book/src/reference/markers/scaffold.md new file mode 100644 index 00000000000..3116e6e1fbe --- /dev/null +++ b/docs/book/src/reference/markers/scaffold.md @@ -0,0 +1,123 @@ +# Scaffold + +The `+kubebuilder:scaffold` marker is a key part of the Kubebuilder scaffolding system. It marks locations in generated +files where additional code will be injected as new resources (such as controllers, webhooks, or APIs) are scaffolded. +This enables Kubebuilder to seamlessly integrate newly generated components into the project without affecting +user-defined code. + + + +## How It Works + +When you scaffold a new resource using the Kubebuilder CLI (e.g., `kubebuilder create api`), +the CLI identifies `+kubebuilder:scaffold` markers in key locations and uses them as placeholders +to insert the required imports and registration code. + +## Example Usage in `main.go` + +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: + +```shell +kubebuilder create api --group crew --version v1 --kind Admiral --controller=true --resource=true +``` + +### To Add New Imports + +The `+kubebuilder:scaffold:imports` marker allows the Kubebuilder CLI to inject additional imports, +such as for new controllers or webhooks. When we create a new API, the CLI automatically adds the required import paths +in this section. + +For example, after creating the `Admiral` API in a single-group layout, +the CLI will add `crewv1 "/api/v1"` to the imports: + +```go +import ( + "crypto/tls" + "flag" + "os" + + // Import all Kubernetes client auth plugins (e.g. Azure, GCP, OIDC, etc.) + // to ensure that exec-entrypoint and run can make use of them. + _ "k8s.io/client-go/plugin/pkg/client/auth" + ... + crewv1 "sigs.k8s.io/kubebuilder/testdata/project-v4/api/v1" + // +kubebuilder:scaffold:imports +) +``` + +### To Register a New Scheme + +The `+kubebuilder:scaffold:scheme` marker is used to register newly created API versions with the runtime scheme, +ensuring the API types are recognized by the manager. + +For example, after creating the Admiral API, the CLI will inject the +following code into the `init()` function to register the scheme: + + +```go +func init() { + ... + utilruntime.Must(crewv1.AddToScheme(scheme)) + // +kubebuilder:scaffold:scheme +} +``` + +## To Set Up a Controller + +When we create a new controller (e.g., for Admiral), the Kubebuilder CLI injects the controller +setup code into the manager using the `+kubebuilder:scaffold:builder` marker. This marker indicates where +the setup code for new controllers should be added. + +For example, after creating the `AdmiralReconciler`, the CLI will add the following code +to register the controller with the manager: + +```go +if err = (&crewv1.AdmiralReconciler{ + Client: mgr.GetClient(), + Scheme: mgr.GetScheme(), +}).SetupWithManager(mgr); err != nil { + setupLog.Error(err, "unable to create controller", "controller", "Admiral") + os.Exit(1) +} +// +kubebuilder:scaffold:builder +``` + +The `+kubebuilder:scaffold:builder` marker ensures that newly scaffolded controllers are +properly registered with the manager, so that the controller can reconcile the resource. + +## List of `+kubebuilder:scaffold` Markers + +| Marker | Usual Location | Function | +|--------------------------------------------|------------------------------|---------------------------------------------------------------------------------| +| `+kubebuilder:scaffold:imports` | `main.go` | Marks where imports for new controllers, webhooks, or APIs should be injected. | +| `+kubebuilder:scaffold:scheme` | `init()` in `main.go` | Used to add API versions to the scheme for runtime. | +| `+kubebuilder:scaffold:builder` | `main.go` | Marks where new controllers should be registered with the manager. | +| `+kubebuilder:scaffold:webhook` | `webhooks suite tests` files | Marks where webhook setup functions are added. | +| `+kubebuilder:scaffold:crdkustomizeresource`| `config/crd` | Marks where CRD custom resource patches are added. | +| `+kubebuilder:scaffold:crdkustomizewebhookpatch` | `config/crd` | Marks where CRD webhook patches are added. | +| `+kubebuilder:scaffold:crdkustomizecainjectionpatch` | `config/crd` | Marks where CA injection patches are added for the webhook. | +| `+kubebuilder:scaffold:manifestskustomizesamples` | `config/samples` | Marks where Kustomize sample manifests are injected. | +| `+kubebuilder:scaffold:e2e-webhooks-checks` | `test/e2e` | Adds e2e checks for webhooks depending on the types of webhooks scaffolded. | + + + + + diff --git a/docs/book/src/reference/reference.md b/docs/book/src/reference/reference.md index 18b5fe39ad1..d88637e58ba 100644 --- a/docs/book/src/reference/reference.md +++ b/docs/book/src/reference/reference.md @@ -26,6 +26,7 @@ - [Webhook](markers/webhook.md) - [Object/DeepCopy](markers/object.md) - [RBAC](markers/rbac.md) + - [Scaffold](markers/scaffold.md) - [Monitoring with Pprof](pprof-tutorial.md) - [controller-gen CLI](controller-gen.md)