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 · 040ae31 · 040ae31
1 parent c00db6e
commit 040ae31
Show file tree

Hide file tree

Showing 34 changed files with 798 additions and 330 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,88 @@
+# 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 managed by another operator.
+
+## Managing External Types
+
+### Creating a Controller for External Types
+
+To create a controller for an external type without scaffolding a resource, you can 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 allows you to generate a controller that operates on types defined outside of 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`: This is the import path for the external API type in your Go modules.
+You should 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 Webhooks to manage an external type
+
+> Webhook support for external types is not currently available. (TODO)
+
+## 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 appropriate group for the type.
+
+The following table lists the core groups and their corresponding API group paths.
+Use this information when defining controllers for core Kubernetes resources.
+
+| Group                   | API Group               |
+|--------------------------|-------------------------|
+| admission                | `k8s.io`                |
+| admissionregistration     | `k8s.io`                |
+| apps                     | *(none)*                |
+| auditregistration         | `k8s.io`                |
+| apiextensions             | `k8s.io`                |
+| authentication            | `k8s.io`                |
+| authorization             | `k8s.io`                |
+| autoscaling               | *(none)*                |
+| batch                    | *(none)*                |
+| certificates              | `k8s.io`                |
+| coordination              | `k8s.io`                |
+| core                     | *(none)*                |
+| events                   | `k8s.io`                |
+| extensions               | *(none)*                |
+| imagepolicy              | `k8s.io`                |
+| networking               | `k8s.io`                |
+| node                     | `k8s.io`                |
+| metrics                  | `k8s.io`                |
+| policy                   | *(none)*                |
+| rbac.authorization       | `k8s.io`                |
+| scheduling               | `k8s.io`                |
+| setting                  | `k8s.io`                |
+| storage                  | `k8s.io`                |
+
+Use the group and API version specific to the type you're
+managing when creating a controller for a core type.
+
+The command for managing a core type 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 defined in the Kubernetes API.
+
+### Creating a Webhooks to manage a Core Type
+
+> Webhook support for Core Types is not currently available. (TODO)