Add support to scaffold controllers for External Types

Introduces the option to allow users scaffold controllers for external types by running: kubebuilder create api --group certmanager --version v1 --kind Certificate --controller=true --resource=false --make=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1
kubernetes-sigs · Sep 21, 2024 · 12a030c · 12a030c
1 parent c00db6e
commit 12a030c
Show file tree

Hide file tree

Showing 34 changed files with 798 additions and 332 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 .idea/
 .vscode/
 WORKSPACE
+.DS_Store
 # don't check in the build output of the book
 docs/book/book/
 

diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -102,7 +102,7 @@
   - [Manager and CRDs Scope](./reference/scopes.md)
 
   - [Sub-Module Layouts](./reference/submodule-layouts.md)
-  - [Using an external Type / API](./reference/using_an_external_type.md)
+  - [Using an external Resource / API](./reference/using_an_external_resource.md)
 
   - [Configuring EnvTest](./reference/envtest.md)
 

diff --git a/docs/book/src/cronjob-tutorial/testdata/project/cmd/main.go b/docs/book/src/cronjob-tutorial/testdata/project/cmd/main.go
@@ -190,6 +190,8 @@ func main() {
 	}
 	// +kubebuilder:scaffold:builder
 
+	// +kubebuilder:scaffold:check-external-api
+
 	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
 		setupLog.Error(err, "unable to set up health check")
 		os.Exit(1)
@@ -206,3 +208,5 @@ func main() {
 	}
 	// +kubebuilder:docs-gen:collapse=old stuff
 }
+
+// +kubebuilder:scaffold:add-method-check-external-api
diff --git a/docs/book/src/getting-started/testdata/project/cmd/main.go b/docs/book/src/getting-started/testdata/project/cmd/main.go
@@ -153,6 +153,8 @@ func main() {
 	}
 	// +kubebuilder:scaffold:builder
 
+	// +kubebuilder:scaffold:check-external-api
+
 	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
 		setupLog.Error(err, "unable to set up health check")
 		os.Exit(1)
@@ -168,3 +170,5 @@ func main() {
 		os.Exit(1)
 	}
 }
+
+// +kubebuilder:scaffold:add-method-check-external-api
diff --git a/docs/book/src/multiversion-tutorial/testdata/project/cmd/main.go b/docs/book/src/multiversion-tutorial/testdata/project/cmd/main.go
@@ -192,6 +192,8 @@ func main() {
 	/*
 	 */
 
+	// +kubebuilder:scaffold:check-external-api
+
 	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
 		setupLog.Error(err, "unable to set up health check")
 		os.Exit(1)
@@ -208,3 +210,5 @@ func main() {
 	}
 	// +kubebuilder:docs-gen:collapse=existing setup
 }
+
+// +kubebuilder:scaffold:add-method-check-external-api
diff --git a/docs/book/src/reference/markers/scaffold.md b/docs/book/src/reference/markers/scaffold.md
@@ -95,17 +95,19 @@ properly registered with the manager, so that the controller can reconcile the r
 
 ## 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.      |
+| 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.                                                       |
+| `+kubebuilder:scaffold:check-external-api` | `main.go`                    | If an controller be scaffolded for an External Type then, adds a new check for the API to ensure that the api and version exists. |
+| `+kubebuilder:scaffold:add-method-check-external-api` | `main.go`                    | If an controller be scaffolded for an External Type then, adds the method to do verify if the API/version exist on the cluster.   |
 
 <aside class="note">
 <h1>Creating Your Own Markers</h1>

diff --git a/docs/book/src/reference/reference.md b/docs/book/src/reference/reference.md
@@ -35,7 +35,7 @@
   - [Platform Support](platform.md)
 
   - [Sub-Module Layouts](submodule-layouts.md)
-  - [Using an external Type / API](using_an_external_type.md)
+  - [Using an external Resource / API](using_an_external_resource.md)
 
   - [Metrics](metrics.md)
       - [Reference](metrics-reference.md)

diff --git a/docs/book/src/reference/submodule-layouts.md b/docs/book/src/reference/submodule-layouts.md
@@ -5,9 +5,11 @@ This part describes how to modify a scaffolded project for use with multiple `go
 Sub-Module Layouts (in a way you could call them a special form of [Monorepo's][monorepo]) are a special use case and can help in scenarios that involve reuse of APIs without introducing indirect dependencies that should not be available in the project consuming the API externally.
 
 <aside class="note">
-<h1>Using external Types</h1>
+<h1>Using External Resources/APIs</h1>
 
-If you are looking to do operations and reconcile via a controller a Type(CRD) which are owned by another project then, please see [Using an external Type](/reference/using_an_external_type.md) for more info.
+If you are looking to do operations and reconcile via a controller a Type(CRD) which are owned by another project
+or By Kubernetes API then, please see [Using an external Resources/API](/reference/using_an_external_type.md)
+for more info.
 
 </aside>
 

diff --git a/docs/book/src/reference/using_an_external_resource.md b/docs/book/src/reference/using_an_external_resource.md
@@ -0,0 +1,101 @@
+
+# Using External Resources
+
+In some cases, your project may need to work with resources that aren't defined by your own APIs. These external resources fall into two main categories:
+
+- **Core Types**: API types defined by Kubernetes itself, such as `Pods`, `Services`, and `Deployments`.
+- **External Types**: API types defined in other projects, such as CRDs defined by another solution.
+
+## Managing External Types
+
+### Creating a Controller for External Types
+
+To create a controller for an external type without scaffolding a resource, use the `create api` command with the `--resource=false` option and specify the path to the external API type using the `--external-api-path` option. This generates a controller for types defined outside your project, such as CRDs managed by other operators.
+
+The command looks like this:
+
+```shell
+kubebuilder create api --group <theirgroup> --version v1alpha1 --kind <ExternalTypeKind> --controller --resource=false --external-api-path=<Golang Import Path>
+```
+
+- `--external-api-path`: Provide the Go import path where the external types are defined.
+
+For example, if you're managing Certificates from Cert Manager:
+
+```shell
+kubebuilder create api --group certmanager --version v1 --kind Certificate --controller=true --resource=false --make=false --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1
+```
+
+This scaffolds a controller for the external type but skips creating new resource definitions since the type is defined in an external project.
+
+### Creating a Webhook to Manage an External Type
+
+<aside>
+<H1> Support </H1>
+
+Webhook support for external types is not currently automated by the tool. However, you can still use the tool to scaffold the webhook setup and make manual adjustments as needed. For guidance, you can follow a similar approach as described in the section [Webhooks for Core Types][webhook-for-core-types].
+
+</aside>
+
+## Managing Core Types
+
+Core Kubernetes API types, such as `Pods`, `Services`, and `Deployments`, are predefined by Kubernetes.
+To create a controller for these core types without scaffolding the resource,
+use the Kubernetes group name described in the following
+table and specify the version and kind.
+
+| Group                    | K8s API Group Full Path            |
+|---------------------------|------------------------------------|
+| admission                 | k8s.io/admission                  |
+| admissionregistration      | k8s.io/admissionregistration      |
+| apps                      | apps                              |
+| auditregistration          | k8s.io/auditregistration          |
+| apiextensions              | k8s.io/apiextensions              |
+| authentication             | k8s.io/authentication             |
+| authorization              | k8s.io/authorization              |
+| autoscaling                | autoscaling                       |
+| batch                     | batch                             |
+| certificates               | k8s.io/certificates               |
+| coordination               | k8s.io/coordination               |
+| core                      | core                              |
+| events                    | k8s.io/events                     |
+| extensions                | extensions                        |
+| imagepolicy               | k8s.io/imagepolicy                |
+| networking                | k8s.io/networking                 |
+| node                      | k8s.io/node                       |
+| metrics                   | k8s.io/metrics                    |
+| policy                    | policy                            |
+| rbac.authorization        | k8s.io/rbac.authorization         |
+| scheduling                | k8s.io/scheduling                 |
+| setting                   | k8s.io/setting                    |
+| storage                   | k8s.io/storage                    |
+
+The command to create a controller to manage `Pods` looks like this:
+
+```shell
+kubebuilder create api --group core --version v1 --kind Pod --controller=true --resource=false
+```
+
+This scaffolds a controller for the Core type `corev1.Pod` but skips creating new resource
+definitions since the type is already defined in the Kubernetes API.
+
+
+<aside class="note">
+<h1>Scheme Registry</h1>
+
+The CLI will not automatically register or add schemes for Core Types because these types are already included by default in Kubernetes. Therefore, you don't need to manually register the scheme for core types, as they are inherently supported.
+
+For External Types, the schemas will be added during scaffolding when you create a controller for an external type. The import path provided during scaffolding will be used to register the external type's schema in your project’s `main.go` file and in the `suite_test.go` file.
+
+</aside>
+
+### Creating a Webhook to Manage a Core Type
+
+<aside>
+<H1> Support </H1>
+
+Webhook support for Core Types is not currently automated by the tool. However, you can still use the tool to scaffold the webhook setup and make manual adjustments as needed. For guidance, you can follow [Webhooks for Core Types][webhook-for-core-types].
+
+</aside>
+
+[webhook-for-core-types]: ./webhook-for-core-types.md