Skip to content

Commit 7b901ca

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #2569 from Ashwin901/2542-plugin-docs
📖 Documentation for go/v2 and go/v3 plugin
2 parents 92e29e8 + 90df9b9 commit 7b901ca

File tree

5 files changed

+124
-4
lines changed

5 files changed

+124
-4
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,8 @@
109109
- [Extending the CLI](./plugins/extending-cli.md)
110110
- [Creating your own plugins](./plugins/creating-plugins.md)
111111
- [Available Plugins](./plugins/available-plugins.md)
112+
- [go/v3 plugin](./plugins/go-v3-plugin.md)
113+
- [go/v2 plugin](./plugins/go-v2-plugin.md)
112114
- [Declarative V1](./plugins/declarative-v1.md)
113115
- [Plugins Versioning](./plugins/plugins-versioning.md)
114116

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

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
1-
# Available Plugins
1+
# Available plugins
22

3-
This section details how to use the currently available plugins in Kubebuilder.
3+
This section describes the plugins supported and shipped in with the Kubebuilder project.
44

5-
- [Declarative V1](declarative-v1.md)
5+
<aside class="note">
6+
7+
<h1>But you can create your own plugins, see:</h1>
8+
9+
- [Creating your own plugins][create-plugins].
10+
- [Plugins Phase 2][plugins-phase-2] - will allow users to use these external options as helpers to perform the scaffolds with the tool.
11+
12+
</aside>
13+
14+
[create-plugins]: creating-plugins.md
15+
[plugins-phase-2]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md

‎docs/book/src/plugins/declarative-v1.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ The following scaffolds will be created or updated by this plugin:
4848
* `channels/stable`
4949
* `Dockerfile`
5050

51-
## Further ressources
51+
## Further resources
5252

5353
* Read more about the [declarative pattern][kubebuilder-declarative-pattern]
5454
* Watch the KubeCon 2018 Video [Managing Addons with Operators][kubecon-video]

‎docs/book/src/plugins/go-v2-plugin.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# go/v2 plugin
2+
3+
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.
4+
5+
<node>
6+
7+
You can check samples using this plugin by looking at the `project-v2-<options>` directories under the [testdata][testdata] projects on the root directory of the Kubebuilder project.
8+
9+
</node>
10+
11+
## When should I use this plugin
12+
13+
Only if you are looking to scaffold a project with the legacy layout. Otherwise, it is recommended you to use the default Golang version plugin.
14+
15+
<aside class="note warning">
16+
17+
<h1> Note </h1>
18+
19+
Be aware that this plugin version does not provide a scaffold compatible with the latest versions of the dependencies used in order to keep its backwards compatibility.
20+
21+
</aside>
22+
23+
## How to use it ?
24+
25+
To initialize a Golang project using the legacy layout and with this plugin run, e.g.:
26+
27+
```sh
28+
kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project --plugins=go/v2
29+
```
30+
<aside class="note">
31+
32+
<h1> Note </h1>
33+
34+
By creating a project with this plugin, the PROJECT file scaffold will be using the previous schema (_project version 2_). So that Kubebuilder CLI knows what plugin version was used and will call its subcommands such as `create api` and `create webhooks`. Note that further Golang plugins versions use the new Project file schema, which tracks the information about what plugins and versions have been used so far.
35+
36+
</aside>
37+
38+
## Subcommands supported by the plugin
39+
40+
- Init - `kubebuilder init [OPTIONS]`
41+
- Edit - `kubebuilder edit [OPTIONS]`
42+
- Create API - `kubebuilder create api [OPTIONS]`
43+
- Create Webhook - `kubebuilder create webhook [OPTIONS]`
44+
45+
## Further resources
46+
47+
- Check the code implementation of the [go/v2 plugin][v2-plugin].
48+
49+
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
50+
[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata
51+
[v2-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/golang/v2

‎docs/book/src/plugins/go-v3-plugin.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# go/v3
2+
3+
Kubebuilder tool will scaffold the go/v3 plugin by default. This plugin is a composition of the plugins ` kustomize.common.kubebuilder.io/v1` and `base.go.kubebuilder.io/v3`. By using you can scaffold the default project which is a helper to construct sets of [controllers][controller-runtime].
4+
5+
It basically scaffolds all the boilerplate code required to create and design controllers. Note that by following the [quickstart][quickstart] you will be using this plugin.
6+
7+
<aside class="note">
8+
9+
<h1>Examples</h1>
10+
11+
Samples are provided under the [testdata][testdata] directory of the Kubebuilder project. You can check samples using this plugin by looking at the `project-v3-<options>` projects under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
12+
13+
</aside>
14+
15+
## When to use it
16+
17+
- If you are looking to scaffold Golang projects to develop projects using [controllers][controller-runtime]
18+
19+
## How to use it ?
20+
21+
As `go/v3` is the default plugin there is no need to explicitly mention to Kubebuilder to use this plugin.
22+
23+
To create a new project with the `go/v3` plugin the following command can be used:
24+
25+
```sh
26+
kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project
27+
```
28+
All the other subcommands supported by the go/v3 plugin can be executed similarly.
29+
30+
<aside class="note">
31+
32+
<h1>Note</h1>
33+
34+
Also, if you need you can explicitly inform the plugin via the option provided `--plugins=go/v3`.
35+
36+
</aside>
37+
38+
## Subcommands supported by the plugin
39+
40+
- Init - `kubebuilder init [OPTIONS]`
41+
- Edit - `kubebuilder edit [OPTIONS]`
42+
- Create API - `kubebuilder create api [OPTIONS]`
43+
- Create Webhook - `kubebuilder create webhook [OPTIONS]`
44+
45+
## Further resources
46+
47+
- To check how plugins are composited by looking at this definition in the [main.go][plugins-main].
48+
- Check the code implementation of the [base Golang plugin `base.go.kubebuilder.io/v3`][v3-plugin].
49+
- Check the code implementation of the [Kustomize/v1 plugin][kustomize-plugin].
50+
- Check [controller-runtime][controller-runtime] to know more about controllers.
51+
52+
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
53+
[quickstart]: ../quick-start.md
54+
[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata
55+
[plugins-main]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/cmd/main.go
56+
[v3-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/golang/v3
57+
[kustomize-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/common/kustomize/v1

0 commit comments

Comments
 (0)