Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 28 additions & 22 deletions docs/book/src/plugins/extending/external-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,28 @@ structures.

`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`.

**Example `PluginRequest` (triggered by `kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain`):**
**Example `PluginRequest` (triggered by `kubebuilder init --plugins sampleexternalplugin/v1`):**

```json
{
"apiVersion": "v1alpha1",
"args": ["--domain", "my.domain"],
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should pass some arg here so that we can ilustrate how to use it

"args": [],
"command": "init",
"universe": {}
}
```

**Example `PluginRequest` (triggered by `kubebuilder edit --plugins sampleexternalplugin/v1`):**

```json
{
"apiVersion": "v1alpha1",
"args": [],
"command": "edit",
"universe": {}
}
```

### PluginResponse

`PluginResponse` contains the modifications made by the plugin to the project. This data is serialized as JSON and returned to Kubebuilder through `stdout`.
Expand All @@ -49,13 +60,14 @@ structures.
```json
{
"apiVersion": "v1alpha1",
"command": "init",
"command": "edit",
"metadata": {
"description": "The `init` subcommand initializes a project via Kubebuilder. It scaffolds a single file: `initFile`.",
"examples": "kubebuilder init --plugins sampleexternalplugin/v1 --domain my.domain"
"description": "The `edit` subcommand adds Prometheus instance configuration for monitoring your operator.",
"examples": "kubebuilder edit --plugins sampleexternalplugin/v1"
},
"universe": {
"initFile": "A file created with the `init` subcommand."
"config/prometheus/prometheus.yaml": "# Prometheus instance manifest...",
"config/prometheus/kustomization.yaml": "resources:\n - prometheus.yaml\n"
},
"error": false,
"errorMsgs": []
Expand Down Expand Up @@ -120,26 +132,20 @@ Otherwise, Kubebuilder would search for the plugins in a default path based on y
You can now use it by calling the CLI commands:

```sh
# Initialize a new project with the external plugin named `sampleplugin`
kubebuilder init --plugins sampleplugin/v1

# Display help information of the `init` subcommand of the external plugin
kubebuilder init --plugins sampleplugin/v1 --help

# Create a new API with the above external plugin with a customized flag `number`
kubebuilder create api --plugins sampleplugin/v1 --number 2
# Initialize a new project with Prometheus monitoring
kubebuilder init --plugins sampleexternalplugin/v1

# Create a webhook with the above external plugin with a customized flag `hooked`
kubebuilder create webhook --plugins sampleplugin/v1 --hooked
# Update an existing project with Prometheus monitoring
kubebuilder edit --plugins sampleexternalplugin/v1

# Update the project configuration with the above external plugin
kubebuilder edit --plugins sampleplugin/v1
# Display help information for the init subcommand
kubebuilder init --plugins sampleexternalplugin/v1 --help

# Create new APIs with external plugins v1 and v2 by respecting the plugin chaining order
kubebuilder create api --plugins sampleplugin/v1,sampleplugin/v2
# Display help information for the edit subcommand
kubebuilder edit --plugins sampleexternalplugin/v1 --help

# Create new APIs with the go/v4 plugin and then pass those files to the external plugin by respecting the plugin chaining order
kubebuilder create api --plugins go/v4,sampleplugin/v1
# Plugin chaining example: Use go/v4 plugin first, then apply external plugin
kubebuilder edit --plugins go/v4,sampleexternalplugin/v1
```

## Further resources
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Binaries for programs and plugins
*.exe
*.exe~
*.dll
*.so
*.dylib
sampleexternalplugin
bin/

# Test binary, built with `go test -c`
*.test

# Output of the go coverage tool, specifically when used with LiteIDE
*.out

# Go workspace file
go.work

# Temporary test directories
testdata/testplugin/
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,7 @@ install: build ## Build and install the binary with the current source code. Use
.PHONY: test-plugin
test-plugin: ## Run the plugin test.
./test/test.sh

.PHONY: clean
clean: ## Clean build artifacts.
rm -rf ./bin
Original file line number Diff line number Diff line change
Expand Up @@ -59,19 +59,13 @@ func Run() {

// Run logic depending on the command that is requested by Kubebuilder
switch pluginRequest.Command {
// the `init` subcommand is often used when initializing a new project
// the `init` subcommand is used to add features during project initialization
case "init":
response = scaffolds.InitCmd(pluginRequest)
// the `create api` subcommand is often used after initializing a project
// with the `init` subcommand to create a controller and CRDs for a
// provided group, version, and kind
case "create api":
response = scaffolds.ApiCmd(pluginRequest)
// the `create webhook` subcommand is often used after initializing a project
// with the `init` subcommand to create a webhook for a provided
// group, version, and kind
case "create webhook":
response = scaffolds.WebhookCmd(pluginRequest)
// the `edit` subcommand is used to add optional features to an existing project
// This is a realistic use case for external plugins - adding optional monitoring
case "edit":
response = scaffolds.EditCmd(pluginRequest)
// the `flags` subcommand is used to customize the flags that
// the Kubebuilder cli will bind for use with this plugin
case "flags":
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,17 +36,27 @@ func flagsCmd(pr *external.PluginRequest) external.PluginResponse {
Flags: []external.Flag{},
}

switch pr.Command {
// Parse args to determine which subcommand flags are being requested
var subcommand string
for _, arg := range pr.Args {
if arg == "--init" {
subcommand = "init"
break
} else if arg == "--edit" {
subcommand = "edit"
break
}
}

switch subcommand {
case "init":
pluginResponse.Flags = scaffolds.InitFlags
case "create api":
pluginResponse.Flags = scaffolds.ApiFlags
case "create webhook":
pluginResponse.Flags = scaffolds.WebhookFlags
case "edit":
pluginResponse.Flags = scaffolds.EditFlags
default:
pluginResponse.Error = true
pluginResponse.ErrorMsgs = []string{
"unrecognized command: " + pr.Command,
"unrecognized subcommand flag in args: " + string(rune(len(pr.Args))),
Copy link

Copilot AI Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Converting len(pr.Args) to a rune and then to a string produces a Unicode character, not a numeric string. This will result in confusing error messages. Use strconv.Itoa(len(pr.Args)) or fmt.Sprintf(\"%d\", len(pr.Args)) instead.

Copilot uses AI. Check for mistakes.
}
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,7 @@ func metadataCmd(pr *external.PluginRequest) external.PluginResponse {
// Here is an example of parsing multiple flags from a Kubebuilder external plugin request
flagsToParse := pflag.NewFlagSet("flagsFlags", pflag.ContinueOnError)
flagsToParse.Bool("init", false, "sets the init flag to true")
flagsToParse.Bool("api", false, "sets the api flag to true")
flagsToParse.Bool("webhook", false, "sets the webhook flag to true")
flagsToParse.Bool("edit", false, "sets the edit flag to true")

if err := flagsToParse.Parse(pr.Args); err != nil {
pluginResponse.Error = true
Expand All @@ -52,21 +51,18 @@ func metadataCmd(pr *external.PluginRequest) external.PluginResponse {
}

initFlag, _ := flagsToParse.GetBool("init")
apiFlag, _ := flagsToParse.GetBool("api")
webhookFlag, _ := flagsToParse.GetBool("webhook")
editFlag, _ := flagsToParse.GetBool("edit")

// The Phase 2 Plugins implementation will only ever pass a single boolean flag
// argument in the JSON request `args` field. The flag will be `--init` if it is
// attempting to get the flags for the `init` subcommand, `--api` for `create api`,
// `--webhook` for `create webhook`, and `--edit` for `edit`
// argument in the JSON request `args` field.
if initFlag {
// Populate the JSON response `metadata` field with a description
// and examples for the `init` subcommand
pluginResponse.Metadata = scaffolds.InitMeta
} else if apiFlag {
pluginResponse.Metadata = scaffolds.ApiMeta
} else if webhookFlag {
pluginResponse.Metadata = scaffolds.WebhookMeta
} else if editFlag {
// Populate the JSON response `metadata` field with a description
// and examples for the `edit` subcommand
pluginResponse.Metadata = scaffolds.EditMeta
} else {
pluginResponse.Error = true
pluginResponse.ErrorMsgs = []string{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,20 @@ module v1
go 1.24.5

require (
github.com/spf13/afero v1.15.0
github.com/spf13/pflag v1.0.10
sigs.k8s.io/kubebuilder/v4 v4.9.0
)

replace sigs.k8s.io/kubebuilder/v4 => ../../../../../../../

require (
github.com/gobuffalo/flect v1.0.3 // indirect
github.com/spf13/afero v1.15.0 // indirect
github.com/kr/text v0.2.0 // indirect
go.yaml.in/yaml/v2 v2.4.2 // indirect
golang.org/x/mod v0.28.0 // indirect
golang.org/x/sync v0.17.0 // indirect
golang.org/x/text v0.29.0 // indirect
golang.org/x/tools v0.37.0 // indirect
sigs.k8s.io/yaml v1.6.0 // indirect
)
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
Expand All @@ -13,12 +14,18 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
github.com/google/pprof v0.0.0-20250820193118-f64d9cf942d6 h1:EEHtgt9IwisQ2AZ4pIsMjahcegHh6rmhqxzIRQIyepY=
github.com/google/pprof v0.0.0-20250820193118-f64d9cf942d6/go.mod h1:I6V7YzU0XDpsHqbsyrghnFZLO1gwK6NPTNvmetQIk9U=
github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
github.com/onsi/ginkgo/v2 v2.25.3 h1:Ty8+Yi/ayDAGtk4XxmmfUy4GabvM+MegeB4cDLRi6nw=
github.com/onsi/ginkgo/v2 v2.25.3/go.mod h1:43uiyQC4Ed2tkOzLsEYm7hnrb7UJTWHYNsuy3bG/snE=
github.com/onsi/gomega v1.38.2 h1:eZCjf2xjZAqe+LeWvKb5weQ+NcPwX84kqJ0cZNxok2A=
github.com/onsi/gomega v1.38.2/go.mod h1:W2MJcYxRGV63b418Ai34Ud0hEdTVXq9NW9+Sx6uXf3k=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
Expand Down Expand Up @@ -49,10 +56,10 @@ golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
golang.org/x/tools v0.37.0 h1:DVSRzp7FwePZW356yEAChSdNcQo6Nsp+fex1SUW09lE=
golang.org/x/tools v0.37.0/go.mod h1:MBN5QPQtLMHVdvsbtarmTNukZDdgwdwlO5qGacAzF0w=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
sigs.k8s.io/kubebuilder/v4 v4.9.0 h1:9e9LnQy/wQ24IZDIqye6iZZFOB9aKNyNfjnfsy3S8cw=
sigs.k8s.io/kubebuilder/v4 v4.9.0/go.mod h1:Xql7wLeyXBQ4lJJdi1Pl8T/DeV4UXpA1kaOEumN0pzY=
sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=
sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
/*
Copyright 2022 The Kubernetes Authors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package prometheus

// PrometheusKustomization represents the kustomization.yaml for Prometheus resources
type PrometheusKustomization struct {
Path string
Content string
}

// NewPrometheusKustomization creates a new kustomization.yaml for Prometheus resources
func NewPrometheusKustomization() *PrometheusKustomization {
return &PrometheusKustomization{
Path: "config/prometheus/kustomization.yaml",
Content: prometheusKustomizationTemplate,
}
}

const prometheusKustomizationTemplate = `resources:
- prometheus.yaml
`

// DefaultKustomizationPatch represents a patch to config/default/kustomization.yaml
type DefaultKustomizationPatch struct {
Path string
Content string
}

// NewDefaultKustomizationPatch creates a patch comment for the default kustomization.yaml
func NewDefaultKustomizationPatch() *DefaultKustomizationPatch {
return &DefaultKustomizationPatch{
Path: "config/default/kustomization_prometheus_patch.yaml",
Content: defaultKustomizationPatchTemplate,
}
}

const defaultKustomizationPatchTemplate = `# [PROMETHEUS] To enable prometheus monitoring, uncomment the following line in config/default/kustomization.yaml:
#
# In the resources section, add:
# - ../prometheus
#
# This will include the Prometheus instance in your deployment.
# Make sure you have the Prometheus Operator installed in your cluster.
#
# For more information, see: https://github.com/prometheus-operator/prometheus-operator
Copy link
Member

@camilamacedo86 camilamacedo86 Nov 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only one that we have is: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v4/config/default/kustomization.yaml

So, we need to keep the config centralised there.
In this way, I am not sure if we should add it.
Why do we need it?

`
Loading