Skip to content

Commit 4f8182c

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #4185 from camilamacedo86/cleanup-docs-plugin
📖 (doc) - refactory and clenup the Plugin section
2 parents 7d9ced5 + 3f1f568 commit 4f8182c

22 files changed

+1115
-917
lines changed

‎VERSIONING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,4 +59,4 @@ take care of building and publishing the artifacts.
5959
[envtest-ref]: https://book.kubebuilder.io/reference/artifacts.html
6060
[tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases
6161
[kb-releases]:https://github.com/kubernetes-sigs/kubebuilder/releases
62-
[cli-plugins-versioning]:docs/book/src/plugins/extending-cli.md#plugin-versioning
62+
[cli-plugins-versioning]:docs/book/src/plugins/extending#plugin-versioning

‎docs/book/src/SUMMARY.md

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -117,18 +117,16 @@
117117
- [Plugins][plugins]
118118

119119
- [Available Plugins](./plugins/available-plugins.md)
120-
- [To scaffold a project](./plugins/to-scaffold-project.md)
121-
- [go/v4 (Default init scaffold)](./plugins/go-v4-plugin.md)
122-
- [To add optional features](./plugins/to-add-optional-features.md)
123-
- [grafana/v1-alpha](./plugins/grafana-v1-alpha.md)
124-
- [deploy-image/v1-alpha](./plugins/deploy-image-plugin-v1-alpha.md)
125-
- [To be extended for others tools](./plugins/to-be-extended.md)
126-
- [kustomize/v2 (Default init scaffold with go/v4)](./plugins/kustomize-v2.md)
127-
- [Extending the CLI](./plugins/extending-cli.md)
128-
- [Creating your own plugins](./plugins/creating-plugins.md)
129-
- [Testing your own plugins](./plugins/testing-plugins.md)
120+
- [go/v4](./plugins/available/go-v4-plugin.md)
121+
- [grafana/v1-alpha](./plugins/available/grafana-v1-alpha.md)
122+
- [deploy-image/v1-alpha](./plugins/available/deploy-image-plugin-v1-alpha.md)
123+
- [kustomize/v2](./plugins/available/kustomize-v2.md)
124+
- [Extending](./plugins/extending.md)
125+
- [CLI and Plugins](./plugins/extending/extending_cli_features_and_plugins.md)
126+
- [External Plugins](./plugins/extending/external-plugins.md)
127+
- [E2E Tests](./plugins/extending/testing-plugins.md)
130128
- [Plugins Versioning](./plugins/plugins-versioning.md)
131-
- [Creating external plugins](./plugins/external-plugins.md)
129+
132130

133131
---
134132

‎docs/book/src/plugins/available-plugins.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,4 @@ This section describes the plugins supported and shipped in with the Kubebuilder
66
{{#include to-add-optional-features.md }}
77
{{#include to-be-extended.md }}
88

9-
<aside class="note">
10-
11-
<h1>Plugins Versioning</h1>
12-
13-
**ALPHA** plugins can introduce breaking changes. For further info see [Plugins Versioning](./plugins/plugins-versioning.md).
14-
15-
</aside>
9+
[plugin-versions]: plugins-versioning.md

‎docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Deploy Image Plugin (deploy-image/v1-alpha)
2+
3+
The `deploy-image` plugin allows users to create [controllers][controller-runtime] and custom resources that deploy and manage container images on the cluster, following Kubernetes best practices. It simplifies the complexities of deploying images while allowing users to customize their projects as needed.
4+
5+
By using this plugin, you will get:
6+
7+
- A controller implementation to deploy and manage an Operand (image) on the cluster.
8+
- Tests to verify the reconciliation logic, using [ENVTEST][envtest].
9+
- Custom resource samples updated with the necessary specifications.
10+
- Environment variable support for managing the Operand (image) within the manager.
11+
12+
<aside class="note">
13+
<h1>Examples</h1>
14+
15+
See the `project-v4-with-plugins` directory under the [testdata][testdata]
16+
directory in the Kubebuilder project to check an example
17+
of scaffolding created using this plugin.
18+
19+
The `Memcached` API and its controller was scaffolded
20+
using the command:
21+
22+
```shell
23+
kubebuilder create api \
24+
--group example.com \
25+
--version v1alpha1 \
26+
--kind Memcached \
27+
--image=memcached:memcached:1.6.26-alpine3.19 \
28+
--image-container-command="memcached,--memory-limit=64,-o,modern,-v" \
29+
--image-container-port="11211" \
30+
--run-as-user="1001" \
31+
--plugins="deploy-image/v1-alpha"
32+
```
33+
34+
The `Busybox` API was created with:
35+
36+
```shell
37+
kubebuilder create api \
38+
--group example.com \
39+
--version v1alpha1 \
40+
--kind Busybox \
41+
--image=busybox:1.36.1 \
42+
--plugins="deploy-image/v1-alpha"
43+
```
44+
</aside>
45+
46+
47+
## When to use it?
48+
49+
- This plugin is ideal for users who are just getting started with Kubernetes operators.
50+
- It helps users deploy and manage an image (Operand) using the [Operator pattern][operator-pattern].
51+
- If you're looking for a quick and efficient way to set up a custom controller and manage a container image, this plugin is a great choice.
52+
53+
## How to use it?
54+
55+
1. **Initialize your project**:
56+
After creating a new project with `kubebuilder init`, you can use this
57+
plugin to create APIs. Ensure that you've completed the
58+
[quick start][quick-start] guide before proceeding.
59+
60+
2. **Create APIs**:
61+
With this plugin, you can [create APIs][create-apis] to specify the image (Operand) you want to deploy on the cluster. You can also optionally specify the command, port, and security context using various flags:
62+
63+
Example command:
64+
```sh
65+
kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.6.15-alpine --image-container-command="memcached,--memory-limit=64,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha"
66+
```
67+
68+
<aside class="warning">
69+
<h1>Note on make run:</h1>
70+
71+
When running the project locally with `make run`, the Operand image
72+
provided will be stored as an environment variable in the
73+
`config/manager/manager.yaml` file.
74+
75+
Ensure you export the environment variable before running the project locally, such as:
76+
77+
```shell
78+
export MEMCACHED_IMAGE="memcached:1.4.36-alpine"
79+
```
80+
81+
</aside>
82+
83+
## Subcommands
84+
85+
The `deploy-image` plugin includes the following subcommand:
86+
87+
- `create api`: Use this command to scaffold the API and controller code to manage the container image.
88+
89+
## Affected files
90+
91+
When using the `create api` command with this plugin, the following
92+
files are affected, in addition to the existing Kubebuilder scaffolding:
93+
94+
- `controllers/*_controller_test.go`: Scaffolds tests for the controller.
95+
- `controllers/*_suite_test.go`: Scaffolds or updates the test suite.
96+
- `api/<version>/*_types.go`: Scaffolds the API specs.
97+
- `config/samples/*_.yaml`: Scaffolds default values for the custom resource.
98+
- `main.go`: Updates the file to add the controller setup.
99+
- `config/manager/manager.yaml`: Updates to include environment variables for storing the image.
100+
101+
## Further Resources:
102+
103+
- Check out this [video][video] to see how it works.
104+
105+
[video]: https://youtu.be/UwPuRjjnMjY
106+
[operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
107+
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
108+
[testdata]: ./.././../../../../testdata/project-v4-with-plugins
109+
[envtest]: ./../../reference/envtest.md
110+
[quick-start]: ./../../quick-start.md
111+
[create-apis]: ../../cronjob-tutorial/new-api.md

‎docs/book/src/plugins/available/go-v4-plugin.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# go/v4 (go.kubebuilder.io/v4)
2+
3+
**(Default Scaffold)**
4+
5+
Kubebuilder will scaffold using the `go/v4` plugin only if specified when initializing the project.
6+
This plugin is a composition of the `kustomize.common.kubebuilder.io/v2` and `base.go.kubebuilder.io/v4` plugins
7+
using the [Bundle Plugin][bundle]. It scaffolds a project template
8+
that helps in constructing sets of [controllers][controller-runtime].
9+
10+
By following the [quickstart][quickstart] and creating any project,
11+
you will be using this plugin by default.
12+
13+
<aside class="note">
14+
<h1>Examples</h1>
15+
16+
You can check samples using this plugin by looking at the `project-v4-<options>` projects under the [testdata][testdata]
17+
directory on the root directory of the Kubebuilder project.
18+
19+
</aside>
20+
21+
## How to use it ?
22+
23+
To create a new project with the `go/v4` plugin the following command can be used:
24+
25+
```sh
26+
kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project --plugins=go/v4
27+
```
28+
29+
## Subcommands supported by the plugin
30+
31+
- Init - `kubebuilder init [OPTIONS]`
32+
- Edit - `kubebuilder edit [OPTIONS]`
33+
- Create API - `kubebuilder create api [OPTIONS]`
34+
- Create Webhook - `kubebuilder create webhook [OPTIONS]`
35+
36+
## Further resources
37+
38+
- To see the composition of plugins, you can check the source code for the Kubebuilder [main.go][plugins-main].
39+
- Check the code implementation of the [base Golang plugin `base.go.kubebuilder.io/v4`][v4-plugin].
40+
- Check the code implementation of the [Kustomize/v2 plugin][kustomize-plugin].
41+
- Check [controller-runtime][controller-runtime] to know more about controllers.
42+
43+
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
44+
[quickstart]: ./../../quick-start.md
45+
[testdata]: ./../../../../../testdata
46+
[plugins-main]: ./../../../../../cmd/main.go
47+
[kustomize-plugin]: ./../../plugins/avaialable/kustomize-v2.md
48+
[kustomize]: https://github.com/kubernetes-sigs/kustomize
49+
[standard-go-project]: https://github.com/golang-standards/project-layout
50+
[v4-plugin]: ./../../../../../pkg/plugins/golang/v4
51+
[migration-guide-doc]: ./../../migration/migration_guide_gov3_to_gov4.md
52+
[project-doc]: ./../../reference/project-config.md
53+
[bundle]: ./../../../../../pkg/plugin/bundle.go

‎docs/book/src/plugins/grafana-v1-alpha.md renamed to ‎docs/book/src/plugins/available/grafana-v1-alpha.md

Lines changed: 29 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,23 @@
11
# Grafana Plugin (`grafana/v1-alpha`)
22

3-
The Grafana plugin is an optional plugin that can be used to scaffold Grafana Dashboards to allow you to check out the default metrics which are exported by projects using [controller-runtime][controller-runtime].
3+
The Grafana plugin is an optional plugin that can be used to
4+
scaffold Grafana Dashboards to allow you to check out the
5+
default metrics which are exported by projects
6+
using [controller-runtime][controller-runtime].
47

58
<aside class="note">
69
<h1>Examples</h1>
710

8-
You can check its default scaffold by looking at the `project-v3-with-metrics` projects under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
11+
You can check its default scaffold by looking at the `project-v4-with-plugins` projects
12+
under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
913

1014
</aside>
1115

1216
## When to use it ?
1317

14-
- If you are looking to observe the metrics exported by [controller metrics][controller-metrics] and collected by Prometheus via [Grafana][grafana].
18+
- If you are looking to observe the metrics
19+
exported by [controller metrics][controller-metrics] and
20+
collected by Prometheus via [Grafana][grafana].
1521

1622
## How to use it ?
1723

@@ -21,10 +27,10 @@ You can check its default scaffold by looking at the `project-v3-with-metrics` p
2127
- Access to [Prometheus][prometheus].
2228
- Prometheus should have an endpoint exposed. (For `prometheus-operator`, this is similar as: http://prometheus-k8s.monitoring.svc:9090 )
2329
- The endpoint is ready to/already become the datasource of your Grafana. See [Add a data source](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/)
24-
- Access to [Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/installation/). Make sure you have:
25-
- [Dashboard edit permission](https://grafana.com/docs/grafana/next/administration/roles-and-permissions/#dashboard-permissions)
30+
- Access to [Grafana][grafana-install]. Make sure you have:
31+
- [Dashboard edit permission][grafana-permissions]
2632
- Prometheus Data source
27-
![pre](https://user-images.githubusercontent.com/18136486/176119794-f6d69b0b-93f0-4f9e-a53c-daf9f77dadae.gif)
33+
![pre][prometheus-data-source]
2834

2935
<aside class="note">
3036

@@ -204,7 +210,7 @@ This time, the plugin will generate `grafana/custom-metrics/custom-metrics-dashb
204210

205211
See an example of how to visualize your custom metrics:
206212

207-
![output2](https://user-images.githubusercontent.com/18136486/186933170-d2e0de71-e079-4d1b-906a-99a549d66ebf.gif)
213+
![output2][show-case]
208214

209215
## Subcommands
210216

@@ -222,22 +228,29 @@ The following scaffolds will be created or updated by this plugin:
222228

223229
## Further resources
224230

225-
- Check out [video to show how it works](https://youtu.be/-w_JjcV8jXc)
226-
- Checkout the [video to show how the custom metrics feature works](https://youtu.be/x_0FHta2HXc)
227-
- Refer to a sample of `servicemonitor` provided by [kustomize plugin][kustomize-plugin]
231+
- Check out [video to show how it works][video]
232+
- Checkout the [video to show how the custom metrics feature works][video-custom-metrics]
233+
- Refer to a sample of `serviceMonitor` provided by [kustomize plugin][kustomize-plugin]
228234
- Check the [plugin implementation][plugin-implementation]
229235
- [Grafana Docs][grafana-docs] of importing JSON file
230-
- The usage of servicemonitor by [Prometheus Operator][servicemonitor]
236+
- The usage of serviceMonitor by [Prometheus Operator][servicemonitor]
231237

232-
[controller-metrics]: https://book.kubebuilder.io/reference/metrics-reference.html
233238
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
234239
[grafana]: https://grafana.com/docs/grafana/next/
235240
[grafana-docs]: https://grafana.com/docs/grafana/latest/dashboards/export-import/#import-dashboard
236-
[kustomize-plugin]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v3/config/prometheus/monitor.yaml
237241
[kube-prometheus]: https://github.com/prometheus-operator/kube-prometheus
238-
[plugin-implementation]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/optional/grafana/alphav1
239242
[prometheus]: https://prometheus.io/docs/introduction/overview/
240243
[prom-operator]: https://prometheus-operator.dev/docs/prologue/introduction/
241-
[reference-metrics-doc]: https://book.kubebuilder.io/reference/metrics.html#exporting-metrics-for-prometheus
242244
[servicemonitor]: https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md#related-resources
243-
[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata
245+
[grafana-install]: https://grafana.com/docs/grafana/latest/setup-grafana/installation/
246+
[grafana-permissions]: https://grafana.com/docs/grafana/next/administration/roles-and-permissions/#dashboard-permissions
247+
[prometheus-data-source]: https://user-images.githubusercontent.com/18136486/176119794-f6d69b0b-93f0-4f9e-a53c-daf9f77dadae.gif
248+
[video]: https://youtu.be/-w_JjcV8jXc
249+
[video-custom-metrics]: https://youtu.be/x_0FHta2HXc
250+
[show-case]: https://user-images.githubusercontent.com/18136486/186933170-d2e0de71-e079-4d1b-906a-99a549d66ebf.gif
251+
[controller-metrics]: ./../../reference/metrics-reference.md
252+
[kustomize-plugin]: ./../../../../../testdata/project-v4-with-plugins/config/prometheus/monitor.yaml
253+
[plugin-implementation]: ./../../../../../pkg/plugins/optional/grafana/
254+
[reference-metrics-doc]: ./../../reference/metrics.md#exporting-metrics-for-prometheus
255+
[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/project-v4-with-plugins
256+

0 commit comments

Comments
 (0)