From be94061bcbef762931aabf314a7b2764f1ab630e Mon Sep 17 00:00:00 2001 From: Jonathan Ballet Date: Sun, 23 Oct 2022 18:28:07 +0200 Subject: [PATCH] Improve rendering of the documentation This fixes various rendering issues: * Wrong or uninterpreted formatting * Some missing links * Incorrect markup * Missing documentation pages This doesn't fix all the links but at least the initial ones. --- docs/book/src/SUMMARY.md | 8 +-- .../component-config-tutorial/api-changes.md | 10 ++-- .../src/cronjob-tutorial/basic-project.md | 6 +- .../book/src/cronjob-tutorial/cert-manager.md | 21 ++++--- .../src/cronjob-tutorial/cronjob-tutorial.md | 5 +- .../src/cronjob-tutorial/running-webhook.md | 4 +- .../cronjob-tutorial/testdata/emptymain.go | 15 ++--- .../src/multiversion-tutorial/tutorial.md | 2 +- docs/book/src/plugins/available-plugins.md | 58 +------------------ docs/book/src/plugins/creating-plugins.md | 22 ++++--- docs/book/src/plugins/extending-cli.md | 10 ++-- docs/book/src/plugins/go-v2-plugin.md | 29 ++++++---- .../src/plugins/to-add-optional-features.md | 9 +++ docs/book/src/plugins/to-be-extended.md | 35 +++++++++++ docs/book/src/plugins/to-scaffold-project.md | 9 +++ docs/book/src/reference/completion.md | 2 + docs/book/src/reference/controller-gen.md | 2 +- docs/book/src/reference/kind.md | 7 +-- docs/book/src/reference/markers.md | 10 ++-- docs/book/src/reference/metrics.md | 4 +- .../testdata/owned-resource/controller.go | 35 ++++++----- 21 files changed, 163 insertions(+), 140 deletions(-) create mode 100644 docs/book/src/plugins/to-add-optional-features.md create mode 100644 docs/book/src/plugins/to-be-extended.md create mode 100644 docs/book/src/plugins/to-scaffold-project.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 277cb55d18..852eebf3a4 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -26,7 +26,7 @@ - [Implementing defaulting/validating webhooks](./cronjob-tutorial/webhook-implementation.md) - [Running and deploying the controller](./cronjob-tutorial/running.md) - - [Deploying the cert manager](./cronjob-tutorial/cert-manager.md) + - [Deploying cert-manager](./cronjob-tutorial/cert-manager.md) - [Deploying webhooks](./cronjob-tutorial/running-webhook.md) - [Writing tests](./cronjob-tutorial/writing-tests.md) @@ -109,15 +109,15 @@ - [Plugins][plugins] - [Available Plugins](./plugins/available-plugins.md) - - [To create a project](./docs/invalid) + - [To scaffold a project](./plugins/to-scaffold-project.md) - [go/v2 (Deprecated)](./plugins/go-v2-plugin.md) - [go/v3 (Default init scaffold)](./plugins/go-v3-plugin.md) - [go/v4-alpha](./plugins/go-v4-plugin.md) - - [To add optional features](./docs/invalid) + - [To add optional features](./plugins/to-add-optional-features.md) - [declarative/v1](./plugins/declarative-v1.md) - [grafana/v1-alpha](./plugins/grafana-v1-alpha.md) - [deploy-image/v1-alpha](./plugins/deploy-image-plugin-v1-alpha.md) - - [To be extended for others tools](./docs/invalid) + - [To be extended for others tools](./plugins/to-be-extended.md) - [kustomize/v1](./plugins/kustomize-v1.md) - [kustomize/v2-alpha](./plugins/kustomize-v2-alpha.md) - [Extending the CLI](./plugins/extending-cli.md) diff --git a/docs/book/src/component-config-tutorial/api-changes.md b/docs/book/src/component-config-tutorial/api-changes.md index 850fb1411c..a762e43dca 100644 --- a/docs/book/src/component-config-tutorial/api-changes.md +++ b/docs/book/src/component-config-tutorial/api-changes.md @@ -57,7 +57,7 @@ loading the config from the file. -Lastly, we'll change the `NewManager` call to use the `options` varible we +Lastly, we'll change the `NewManager` call to use the `options` variable we defined above. ```go @@ -106,13 +106,16 @@ configMapGenerator: - controller_manager_config.yaml ``` -Update the file `default/kustomization.yaml` by adding under the patchesStrategicMerge: the following patch: +Update the file `default/kustomization.yaml` by adding under the [`patchesStrategicMerge:` key](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_patchesstrategicmerge_) the following patch: +```yaml +patchesStrategicMerge: # Mount the controller config file for loading manager configurations # through a ComponentConfig type - manager_config_patch.yaml +``` -Update the file `default/manager_config_patch.yaml` by adding under the spec: the following patch: +Update the file `default/manager_config_patch.yaml` by adding under the `spec:` key the following patch: ```yaml spec: @@ -131,4 +134,3 @@ spec: configMap: name: manager-config ``` - diff --git a/docs/book/src/cronjob-tutorial/basic-project.md b/docs/book/src/cronjob-tutorial/basic-project.md index b850834cc3..d333cecc3f 100644 --- a/docs/book/src/cronjob-tutorial/basic-project.md +++ b/docs/book/src/cronjob-tutorial/basic-project.md @@ -7,7 +7,7 @@ basic pieces of boilerplate. First up, basic infrastructure for building your project: -
`go.mod`: A new Go module matching our project, with +
go.mod: A new Go module matching our project, with basic dependencies ```go @@ -15,14 +15,14 @@ basic dependencies
 ```
-
`Makefile`: Make targets for building and deploying your controller +
Makefile: Make targets for building and deploying your controller ```makefile {{#include ./testdata/project/Makefile}} ```
-
`PROJECT`: Kubebuilder metadata for scaffolding new components +
PROJECT: Kubebuilder metadata for scaffolding new components ```yaml {{#include ./testdata/project/PROJECT}} diff --git a/docs/book/src/cronjob-tutorial/cert-manager.md b/docs/book/src/cronjob-tutorial/cert-manager.md index 48d84ef537..594cfd1eeb 100644 --- a/docs/book/src/cronjob-tutorial/cert-manager.md +++ b/docs/book/src/cronjob-tutorial/cert-manager.md @@ -1,24 +1,29 @@ -# Deploying the cert manager +# Deploying cert-manager -We suggest using [cert manager](https://github.com/jetstack/cert-manager) for +We suggest using [cert-manager](https://github.com/jetstack/cert-manager) for provisioning the certificates for the webhook server. Other solutions should also work as long as they put the certificates in the desired location. You can follow -[the cert manager documentation](https://cert-manager.io/docs/installation/) +[the cert-manager documentation](https://cert-manager.io/docs/installation/) to install it. -Cert manager also has a component called CA injector, which is responsible for -injecting the CA bundle into the Mutating|ValidatingWebhookConfiguration. +cert-manager also has a component called [CA +Injector](https://cert-manager.io/docs/concepts/ca-injector/), which is responsible for +injecting the CA bundle into the [`MutatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#MutatingWebhookConfiguration) +/ [`ValidatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#ValidatingWebhookConfiguration). To accomplish that, you need to use an annotation with key `cert-manager.io/inject-ca-from` -in the Mutating|ValidatingWebhookConfiguration objects. -The value of the annotation should point to an existing certificate CR instance +in the [`MutatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#MutatingWebhookConfiguration) +/ [`ValidatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#ValidatingWebhookConfiguration) objects. +The value of the annotation should point to an existing [certificate request instance](https://cert-manager.io/docs/concepts/certificaterequest/) in the format of `/`. This is the [kustomize](https://github.com/kubernetes-sigs/kustomize) patch we -used for annotating the Mutating|ValidatingWebhookConfiguration objects. +used for annotating the [`MutatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#MutatingWebhookConfiguration) +/ [`ValidatingWebhookConfiguration`](https://pkg.go.dev/k8s.io/api/admissionregistration/v1#ValidatingWebhookConfiguration) objects. + ```yaml {{#include ./testdata/project/config/default/webhookcainjection_patch.yaml}} ``` diff --git a/docs/book/src/cronjob-tutorial/cronjob-tutorial.md b/docs/book/src/cronjob-tutorial/cronjob-tutorial.md index 803ece8961..f87ae89d94 100644 --- a/docs/book/src/cronjob-tutorial/cronjob-tutorial.md +++ b/docs/book/src/cronjob-tutorial/cronjob-tutorial.md @@ -53,15 +53,18 @@ kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io ``` Now that we've got a project in place, let's take a look at what Kubebuilder has scaffolded for us so far... diff --git a/docs/book/src/plugins/available-plugins.md b/docs/book/src/plugins/available-plugins.md index 7807110067..62d39e0d03 100644 --- a/docs/book/src/plugins/available-plugins.md +++ b/docs/book/src/plugins/available-plugins.md @@ -2,58 +2,6 @@ This section describes the plugins supported and shipped in with the Kubebuilder project. -## To scaffold the projects - -The following plugins are useful to scaffold the whole project with the tool. - -| Plugin | Key | Description | -| ---------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [go.kubebuilder.io/v2 - (Deprecated)](go-v2-plugin.md) | `go/v2` | Golang plugin responsible for scaffolding the legacy layout provided with Kubebuilder CLI >= `2.0.0` and < `3.0.0`. | -| [go.kubebuilder.io/v3 - (Default scaffold with Kubebuilder init)](go-v3-plugin.md) | `go/v3` | Default scaffold used for creating a project when no plugin(s) are provided. Responsible for scaffolding Golang projects and its configurations. | -| [go.kubebuilder.io/v4-alpha - (Add Apple Sillicom Support)](go-v4-plugin.md) | `go/v4` | Scaffold composite by `base.go.kubebuilder.io/v3` and [kustomize.common.kubebuilder.io/v2-alpha](kustomize-v2-alpha.md). Responsible for scaffolding Golang projects and its configurations. | - -## To add optional features - -The following plugins are useful to generate code and take advantage of optional features - -| Plugin | Key | Description | -| ---------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [declarative.go.kubebuilder.io/v1](declarative-v1.md) | `declarative/v1` | Optional plugin used to scaffold APIs/controllers using the [kubebuilder-declarative-pattern][kubebuilder-declarative-pattern] project. | -| [grafana.kubebuilder.io/v1-alpha](grafana-v1-alpha.md) | `grafana/v1-alpha` | Optional helper plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime. | -| [deploy-image.go.kubebuilder.io/v1-alpha](deploy-image-plugin-v1-alpha) | `deploy-image/v1-alpha` | Optional helper plugin which can be used to scaffold APIs and controller with code implementation to Deploy and Manage an Operand(image). | - -## To help projects using Kubebuilder as Lib to composite new solutions and plugins - - - -Then, see that you can use the kustomize plugin, which is responsible for to scaffold the kustomize files under `config/`, as -the base language plugins which are responsible for to scaffold the Golang files to create your own plugins to work with -another languages (i.e. [Operator-SDK][sdk] does to allow users work with Ansible/Helm) or to add -helpers on top, such as [Operator-SDK][sdk] does to add their features to integrate the projects with [OLM][olm]. - -| Plugin | Key | Description | -| ---------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [kustomize.common.kubebuilder.io/v1](kustomize-v1.md) | `kustomize/v1` | Responsible for scaffold all manifests to configure the projects with [kustomize(v3)][kustomize]. (create and update the `config/` directory). This plugin is used in the composition to create the plugin (`go/v3`). | -| [kustomize.common.kubebuilder.io/v2-alpha](kustomize-v2-alpha.md) | `kustomize/v2-alpha` | It has the same purpose of `kustomize/v1`. However, it works with [kustomize][kustomize] version `v4` and addresses the required changes for future kustomize configurations. It will probably be used with the future `go/v4-alpha` plugin. | -| `base.go.kubebuilder.io/v3` | `base/v3` | Responsible for scaffold all files which specific requires Golang. This plugin is used in the composition to create the plugin (`go/v3`) | - - - -[create-plugins]: creating-plugins.md -[kubebuilder-declarative-pattern]: https://github.com/kubernetes-sigs/kubebuilder-declarative-pattern -[kustomize]: https://kustomize.io/ -[sdk]: https://github.com/operator-framework/operator-sdk -[olm]: https://olm.operatorframework.io/ - +{{#include to-scaffold-project.md }} +{{#include to-add-optional-features.md }} +{{#include to-be-extended.md }} diff --git a/docs/book/src/plugins/creating-plugins.md b/docs/book/src/plugins/creating-plugins.md index 4d0b770207..26b28065ff 100644 --- a/docs/book/src/plugins/creating-plugins.md +++ b/docs/book/src/plugins/creating-plugins.md @@ -1,8 +1,16 @@ # Creating your own plugins +[extending-cli]: extending-cli.md +[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime +[operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator +[sdk-ansible]: https://sdk.operatorframework.io/docs/building-operators/ansible/ +[sdk-cli-pkg]: https://pkg.go.dev/github.com/operator-framework/operator-sdk/internal/cmd/operator-sdk/cli +[sdk-helm]: https://sdk.operatorframework.io/docs/building-operators/helm/ +[sdk]: https://github.com/operator-framework/operator-sdk + ## Overview -You can extend the Kubebuilder API to create your own plugins. If [extending the CLI][extending-cli], your plugin will be implemented in your project and registered to the CLI as has been done by the [SDK][sdk] project. See its [cli code][sdk-cli-pkg] as an example. +You can extend the Kubebuilder API to create your own plugins. If [extending the CLI][extending-cli], your plugin will be implemented in your project and registered to the CLI as has been done by the [SDK][sdk] project. See its [CLI code][sdk-cli-pkg] as an example. ## Language-based Plugins @@ -44,15 +52,15 @@ And then, you will also be able to use custom plugins and options currently or i Note that users are also able to use plugins to customize their scaffolds and address specific needs. -See that Kubebuilder provides the [deploy-image][deploy-image] plugin that allows the user to create the controller & CRs which will deploy and manage an image on the cluster: +See that Kubebuilder provides the [`deploy-image`][deploy-image] plugin that allows the user to create the controller & CRs which will deploy and manage an image on the cluster: ```sh kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.6.15-alpine --image-container-command="memcached,-m=64,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha" ``` -This plugin will perform a custom scaffold following the [Operator Pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator). +This plugin will perform a custom scaffold following the [Operator Pattern][operator-pattern]. -Another example is the [grafana][grafana] plugin that scaffolds a new folder container manifests to visualize operator status on Grafana Web UI: +Another example is the [`grafana`][grafana] plugin that scaffolds a new folder container manifests to visualize operator status on Grafana Web UI: ```sh kubebuilder edit --plugins="grafana.kubebuilder.io/v1-alpha" @@ -60,7 +68,5 @@ kubebuilder edit --plugins="grafana.kubebuilder.io/v1-alpha" In this way, by [Extending the Kubebuilder CLI][extending-cli], you can also create custom plugins such this one. -Feel free to check the implementation under: - -- deploy-image: -- grafana: +[grafana]: https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/pkg/plugins/optional/grafana/v1alpha +[deploy-image]: https://github.com/kubernetes-sigs/kubebuilder/tree/v3.7.0/pkg/plugins/golang/deploy-image/v1alpha1 diff --git a/docs/book/src/plugins/extending-cli.md b/docs/book/src/plugins/extending-cli.md index 953f98c99e..7a9f0e89b1 100644 --- a/docs/book/src/plugins/extending-cli.md +++ b/docs/book/src/plugins/extending-cli.md @@ -186,7 +186,7 @@ Once a plugin is deprecated, have it implement a [Deprecated][deprecate-plugin-d Note that it means that when a user of your CLI calls this plugin, the execution of the sub-commands will be sorted by the order to which they were added in a chain: -> sub-command of plugin A -> sub-command of plugin B -> sub-command of plugin C +> `sub-command` of plugin A ➔ `sub-command` of plugin B ➔ `sub-command` of plugin C Then, to initialize using this "Plugin Bundle" which will run the chain of plugins: @@ -194,9 +194,9 @@ Then, to initialize using this "Plugin Bundle" which will run the chain of plugi kubebuider init --plugins=myplugin.example/v1 ``` -- Runs init sub-command of the plugin A -- And then, runs init sub-command of the plugin B -- And then, runs init sub-command of the plugin C +- Runs init `sub-command` of the plugin A +- And then, runs init `sub-command` of the plugin B +- And then, runs init `sub-command` of the plugin C [project-file-config]: ../reference/project-config.md [plugin-interface]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/pkg/plugin#Plugin @@ -210,4 +210,4 @@ kubebuider init --plugins=myplugin.example/v1 [deprecate-plugin-doc]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/pkg/plugin#Deprecated [plugin-update-meta]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/pkg/plugin#UpdatesMetadata [cli]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/pkg/cli -[plugin-version-type]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/pkg/plugin#Version \ No newline at end of file +[plugin-version-type]: https://pkg.go.dev/sigs.k8s.io/kubebuilder/v3/pkg/plugin#Version diff --git a/docs/book/src/plugins/go-v2-plugin.md b/docs/book/src/plugins/go-v2-plugin.md index aea3b38db1..63b8c27841 100644 --- a/docs/book/src/plugins/go-v2-plugin.md +++ b/docs/book/src/plugins/go-v2-plugin.md @@ -3,22 +3,22 @@ -The `go/v2` plugin has the purpose to scaffold Golang projects to help users -to build projects with [controllers][controller-runtime] and keep the backwards compatibility +The `go/v2` plugin has the purpose to scaffold Golang projects to help users +to build projects with [controllers][controller-runtime] and keep the backwards compatibility with the default scaffold made using Kubebuilder CLI `2.x.z` releases.