You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Extending Kubebuilder can be accomplished in two primary ways:
3
+
Extending Kubebuilder can be achieved in two main ways:
17
4
18
-
`By re-using the existing plugins`: In this approach, you use Kubebuilder as a library.
5
+
1.**Re-using Existing Plugins**:
6
+
You can import and build upon existing Kubebuilder plugins to extend
7
+
their functionality. This is useful when you need to add specific
8
+
features to a tool that already benefits from Kubebuilder's scaffolding system.
9
+
For example, [Operator SDK][sdk] leverages the [kustomize plugin][kustomize-plugin]
10
+
to provide language support for tools like Ansible or Helm. So that the project
11
+
can be focused to keep maintained only what is specific language based.
19
12
20
-
This enables you to import existing Kubebuilder plugins and extend them, leveraging their features to build upon.
21
-
22
-
It is particularly useful if you want to add functionalities that are closely tied with the existing Kubebuilder features.
13
+
2.**Creating External Plugins**:
14
+
You can build standalone, independent plugins as binaries. These plugins can be written in any
15
+
language and should follow an execution pattern that Kubebuilder recognizes. For more information,
16
+
see [Creating external plugins][external-plugins].
23
17
18
+
<asideclass="note">
19
+
<h1>Why use the Kubebuilder style?</h1>
24
20
25
-
`By Creating an External Plugin`: This method allows you to create an independent, standalone plugin as a binary.
21
+
Kubebuilder and SDK are both broadly adopted projects which leverage the [controller-runtime][controller-runtime] project. They both allow users to build solutions using the [Operator Pattern][operator-pattern] and follow common standards.
26
22
27
-
The plugin can be written in any language and should implement an execution pattern that Kubebuilder knows how to interact with.
23
+
Adopting these standards can bring significant benefits, such as joining forces on maintaining the common standards as the features provided by Kubebuilder and take advantage of the contributions made by the community. This allows you to focus on the specific needs and requirements for your plugin and use-case.
28
24
29
-
You can see [Creating external plugins][creating-external-plugins] for more info.
25
+
And then, you will also be able to use custom plugins and options currently or in the future which might to be provided by these projects as any other which decides to persuade the same standards.
30
26
31
27
</aside>
32
28
33
29
## Overview
34
30
35
-
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.
31
+
You can extend the Kubebuilder API to create your own plugins. If [extending the CLI][extending-cli], your plugin will be
32
+
implemented in your project and registered to the CLI as has been done by the [SDK][sdk] project.
33
+
See its [CLI code][sdk-cli-pkg] as an example.
36
34
37
35
## When it is useful?
38
36
@@ -59,15 +57,6 @@ Another option implemented with the [Extensible CLI and Scaffolding Plugins - Ph
59
57
to extend Kibebuilder as a LIB to create only a specific plugin that can be called and used with
60
58
Kubebuilder as well.
61
59
62
-
<asideclass="note">
63
-
<H1> Plugins proposal docs</H1>
64
-
65
-
You can check the proposal documentation for better understanding its motivations. See the [Extensible CLI and Scaffolding Plugins: phase 1][plugins-phase1-design-doc],
66
-
the [Extensible CLI and Scaffolding Plugins: phase 1.5][plugins-phase1-design-doc-1.5] and the [Extensible CLI and Scaffolding Plugins - Phase 2][plugins-phase2-design-doc]
67
-
design docs. Also, you can check the [Plugins section][plugins-section].
68
-
69
-
</aside>
70
-
71
60
## Language-based Plugins
72
61
73
62
Kubebuilder offers the Golang-based operator plugins, which will help its CLI tool users create projects following the [Operator Pattern][operator-pattern].
Then you can, for example, create your implementations for the sub-commands `create api` and `create webhook` using your language of preference.
96
85
97
-
<asideclass="note">
98
-
<h1>Why use the Kubebuilder style?</h1>
99
-
100
-
Kubebuilder and SDK are both broadly adopted projects which leverage the [controller-runtime][controller-runtime] project. They both allow users to build solutions using the [Operator Pattern][operator-pattern] and follow common standards.
101
-
102
-
Adopting these standards can bring significant benefits, such as joining forces on maintaining the common standards as the features provided by Kubebuilder and take advantage of the contributions made by the community. This allows you to focus on the specific needs and requirements for your plugin and use-case.
103
-
104
-
And then, you will also be able to use custom plugins and options currently or in the future which might to be provided by these projects as any other which decides to persuade the same standards.
105
-
106
-
</aside>
107
-
108
86
## Custom Plugins
109
87
110
88
Note that users are also able to use plugins to customize their scaffolds and address specific needs.
@@ -211,12 +189,16 @@ Alternatively, you can create a plugin bundle to include the target plugins. For
Kubebuilder's functionality can be extended through the use of external plugins.
5
+
Kubebuilder's functionality can be extended through external plugins.
6
+
These plugins are executables (written in any language) that follow an
7
+
execution pattern recognized by Kubebuilder. Kubebuilder interacts with
8
+
these plugins via `stdin` and `stdout`, enabling seamless communication.
6
9
7
-
An external plugin is an executable (can be written in any language) that implements an execution pattern that Kubebuilder knows how to interact with.
10
+
## Why Use External Plugins?
8
11
9
-
The Kubebuilder CLI loads the external plugin in the specified path and interacts with it through `stdin` & `stdout`.
12
+
External plugins enable third-party solution maintainers to integrate their tools with Kubebuilder.
13
+
Much like Kubebuilder's own plugins, these can be opt-in, offering users
14
+
flexibility in tool selection. By developing plugins in their repositories,
15
+
maintainers ensure updates are aligned with their CI pipelines and can
16
+
manage any changes within their domain of responsibility.
10
17
11
-
## When is it useful?
18
+
If you are interested in this type of integration, collaborating with the
19
+
maintainers of the third-party solution is recommended. Kubebuilder's maintainers
20
+
is always willing to provide support in extending its capabilities.
12
21
13
-
- If you want to create helpers or addons on top of the scaffolds done by Kubebuilder's default scaffolding.
22
+
## How to Write an External Plugin
14
23
15
-
- If you design customized layouts and want to take advantage of functions from Kubebuilder library.
24
+
Communication between Kubebuilder and an external plugin occurs via
25
+
standard I/O. Any language can be used to create the plugin, as long
26
+
as it follows the [PluginRequest][PluginRequest] and [PluginResponse][PluginResponse]
27
+
structures.
16
28
17
-
- If you are looking for implementing plugins in a language other than `Go`.
29
+
### PluginRequest
18
30
19
-
## How to write it?
31
+
`PluginRequest` contains the data collected from the CLI and any previously executed plugins. Kubebuilder sends this data as a JSON object to the external plugin via `stdin`.
20
32
21
-
The inter-process communication between your external plugin and Kubebuilder is through the standard I/O.
33
+
**Example `PluginRequest` (triggered by `kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain`):**
22
34
23
-
Your external plugin can be written in any language, given it adheres to the [PluginRequest][PluginRequest] and [PluginResponse][PluginResponse] type structures.
24
-
25
-
`PluginRequest` encompasses all the data Kubebuilder collects from the CLI and previously executed plugins in the plugin chain.
26
-
Kubebuilder conveys the marshaled PluginRequest (a `JSON` object) to the external plugin over `stdin`.
27
-
28
-
Below is a sample JSON object of the `PluginRequest` type, triggered by `kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain`:
29
35
```json
30
36
{
31
-
"apiVersion": "v1alpha1",
32
-
"args": ["--domain", "my.domain"],
33
-
"command": "init",
34
-
"universe": {}
37
+
"apiVersion": "v1alpha1",
38
+
"args": ["--domain", "my.domain"],
39
+
"command": "init",
40
+
"universe": {}
35
41
}
36
42
```
37
43
38
-
`PluginResponse` represents the updated state of the project, as modified by the plugin. This data structure is serialized into `JSON` and sent back to Kubebuilder via `stdout`.
44
+
### PluginResponse
39
45
40
-
Here is a sample JSON representation of the `PluginResponse` type:
46
+
`PluginResponse` contains the modifications made by the plugin to the project. This data is serialized as JSON and returned to Kubebuilder through `stdout`.
47
+
48
+
**Example `PluginResponse`:**
41
49
```json
42
50
{
43
-
"apiVersion": "v1alpha1",
44
-
"command": "init",
45
-
"metadata": {
46
-
"description": "The `init` subcommand is meant to initialize a project via Kubebuilder. It scaffolds a single file: `initFile`",
"initFile": "A file created with the `init` subcommand."
59
+
},
60
+
"error": false,
61
+
"errorMsgs": []
54
62
}
55
63
```
56
64
57
-
In this example, the `init` command of the plugin has created a new file called `initFile`.
58
-
59
-
The content of this file is: `A simple file created with the init subcommand`, which is recorded in the `universe` field of the response.
60
-
61
-
This output is then sent back to Kubebuilder, allowing it to incorporate the changes made by the plugin into the project.
62
-
63
-
<asideclass="note">
64
-
<h1>Caution</h1>
65
-
66
-
When writing your own external plugin, you **should not** directly echo or print anything to the stdout.
65
+
<aside>
66
+
<H1> </H1>
67
67
68
-
This is because Kubebuilder and your plugin are communicating with each other via `stdin` and `stdout`using structured `JSON` data.
69
-
Any additional information sent to stdout (such as debug messages or logs) that's not part of the expected PluginResponse JSON structure may cause parsing errors when Kubebuilder tries to read and decode the response from your plugin.
70
-
71
-
If you need to include logs or debug messages while developing your plugin, consider writing these messages to a log file instead.
68
+
Avoid printing directly to `stdout`in your external plugin.
69
+
Since communication between Kubebuilder and the plugin occurs through
70
+
`stdin` and `stdout` using structured JSON, any unexpected output
71
+
(like debug logs) may cause errors. Write logs to a file if needed.
72
72
73
73
</aside>
74
74
75
-
## How to use it?
75
+
## How to Use an External Plugin
76
76
77
77
### Prerequisites
78
-
- kubebuilder CLI > 3.11.0
79
-
- An executable for the external plugin.
80
-
81
-
This could be a plugin that you've created yourself, or one from an external source.
82
-
- Configuration of the external plugin's path.
83
78
84
-
This can be done by setting the `${EXTERNAL_PLUGINS_PATH}` environment variable, or by placing the plugin in a path that follows a `group-like name and version` scheme:
As an example, if you're on Linux and you want to use `v2` of an external plugin called `foo.acme.io`, you'd place the executable in the folder `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/` with a file name that also matches the plugin name up to an (optional) file extension.
93
-
In other words, passing the flag `--plugins=foo.acme.io/v2` to `kubebuilder` would find the plugin at either of these locations
**Example:** For a plugin `foo.acme.io` version `v2` on Linux, the path would be `$HOME/.config/kubebuilder/plugins/foo.acme.io/v2/foo.acme.io`.
98
86
99
-
### Subcommands:
87
+
### Available Subcommands
100
88
101
-
The external plugin supports the same subcommands as kubebuilder already provides:
102
-
-`init`: project initialization.
103
-
-`create api`: scaffold Kubernetes API definitions.
104
-
-`create webhook`: scaffold Kubernetes webhooks.
105
-
-`edit`: update the project configuration.
89
+
External plugins can support the following Kubebuilder subcommands:
90
+
-`init`: Project initialization
91
+
-`create api`: Scaffold Kubernetes API definitions
92
+
-`create webhook`: Scaffold Kubernetes webhooks
93
+
-`edit`: Update project configuration
106
94
107
-
Also, there are **Optional** subcommands for a better user experience:
108
-
-`metadata`: add customized plugin description and examples when a`--help` flag is specified.
109
-
-`flags`: specify valid flags for Kubebuilder to pass to the external plugin.
95
+
**Optional subcommands for enhanced user experience:**
96
+
-`metadata`: Provide plugin descriptions and examples with the`--help` flag.
97
+
-`flags`: Inform Kubebuilder of supported flags, enabling early error detection.
110
98
111
99
<asideclass="note">
112
100
<h1>More about `flags` subcommand</h1>
@@ -116,16 +104,21 @@ If a plugin does not implement the `flags` subcommand, Kubebuilder will pass all
116
104
117
105
</aside>
118
106
119
-
### Configuration
107
+
### Configuring Plugin Path
108
+
109
+
Set the environment variable `$EXTERNAL_PLUGINS_PATH`
110
+
to specify a custom plugin binary path:
120
111
121
-
You can configure your plugin path with a ENV VAR `$EXTERNAL_PLUGINS_PATH` to tell Kubebuilder where to search for the plugin binary, such as:
122
112
```sh
123
-
export EXTERNAL_PLUGINS_PATH = <custom-path>
113
+
export EXTERNAL_PLUGINS_PATH=<custom-path>
124
114
```
125
115
126
116
Otherwise, Kubebuilder would search for the plugins in a default path based on your OS.
127
117
118
+
### Example CLI Commands
119
+
128
120
Now, you can using it by calling the CLI commands:
121
+
129
122
```sh
130
123
# Initialize a new project with the external plugin named `sampleplugin`
131
124
kubebuilder init --plugins sampleplugin/v1
@@ -149,14 +142,11 @@ kubebuilder create api --plugins sampleplugin/v1,sampleplugin/v2
149
142
kubebuilder create api --plugins go/v4,sampleplugin/v1
150
143
```
151
144
152
-
153
145
## Further resources
154
146
155
-
- Check the [design proposal of the external plugin](https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md)
156
-
- Check the [plugin implementation](https://github.com/kubernetes-sigs/kubebuilder/pull/2338)
157
147
- A [sample external plugin written in Go](https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1)
158
148
- A [sample external plugin written in Python](https://github.com/rashmigottipati/POC-Phase2-Plugins)
159
149
- A [sample external plugin written in JavaScript](https://github.com/Eileen-Yu/kb-js-plugin)
0 commit comments