[external-plugin] fix(ci): use Make targets for CLI install and expose plugin failures

Previously, CI used inlined shell commands that produced an invalid `kubebuilder` binary,
causing cryptic errors like:
  `/home/runner/.../kubebuilder: line 1: '!<arch>'`

This commit switches to official Makefile targets to correctly build and install
the Kubebuilder CLI. It also improves local testability and ensures plugin command
failures are no longer silently skipped.

Author: camilamacedo86

.github/workflows/external-plugin.yml

@@ -18,57 +18,14 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
     steps:
-      - name: Clone the code
+      - name: Checkout repository
         uses: actions/checkout@v4
-        with:
-          fetch-depth: 1  # Minimal history to avoid .git permissions issues
 
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version-file: docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/go.mod
-
-      - name: Build Sample External Plugin
-        working-directory: docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1
-        run: |
-          mkdir -p ./bin
-          make build
-
-      - name: Move Plugin Binary to Plugin Path
-        run: |
-          # Define the plugin destination for Linux (XDG_CONFIG_HOME path)
-          XDG_CONFIG_HOME="${HOME}/.config"
-          PLUGIN_DEST="$XDG_CONFIG_HOME/kubebuilder/plugins/sampleexternalplugin/v1"
-
-          # Ensure destination exists and move the built binary
-          mkdir -p "$PLUGIN_DEST"
-          mv docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/bin/sampleexternalplugin "$PLUGIN_DEST/sampleexternalplugin"
-          chmod +x "$PLUGIN_DEST/sampleexternalplugin"  # Ensure the binary is executable
-
-      - name: Build Kubebuilder Binary and Setup Environment
-        env:
-          KUBEBUILDER_ASSETS: $GITHUB_WORKSPACE/bin
-        run: |
-          # Build Kubebuilder Binary
-          export kb_root_dir=$(pwd)
-          go build -o "${kb_root_dir}/bin/kubebuilder" ./cmd
-          chmod +x "${kb_root_dir}/bin/kubebuilder"  # Ensure kubebuilder binary is executable
-          echo "${kb_root_dir}/bin" >> $GITHUB_PATH  # Add to PATH
+          go-version-file: go.mod
 
-      - name: Create Directory, Run Kubebuilder Commands, and Validate Results
-        env:
-          KUBEBUILDER_ASSETS: $GITHUB_WORKSPACE/bin
-        run: |
-          # Create a directory named testplugin for running kubebuilder commands
-          mkdir testplugin
-          cd testplugin
-          
-          # Run Kubebuilder commands inside the testplugin directory
-          kubebuilder init --plugins sampleexternalplugin/v1 --domain sample.domain.com
-          kubebuilder create api --plugins sampleexternalplugin/v1 --number=2 --group=example --version=v1alpha1 --kind=ExampleKind
-          kubebuilder create webhook --plugins sampleexternalplugin/v1 --hooked --group=example --version=v1alpha1 --kind=ExampleKind
+      - name: Run tests
+        run: make test-external-plugin
 
-          # Validate generated file contents
-          grep "DOMAIN: sample.domain.com" ./initFile.txt || exit 1
-          grep "NUMBER: 2" ./apiFile.txt || exit 1
-          grep "HOOKED!" ./webhookFile.txt || exit 1

Makefile

@@ -184,6 +184,11 @@ test-book: ## Run the cronjob tutorial's unit tests to make sure we don't break
 test-license:  ## Run the license check
 	./test/check-license.sh
 
+.PHONY: test-external-plugin
+test-external-plugin: install  ## Run tests for external plugin
+	make -C docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1 install
+	make -C docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1 test-plugin
+
 .PHONY: test-spaces
 test-spaces:  ## Run the trailing spaces check
 	./test/check_spaces.sh

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/Makefile

@@ -35,6 +35,10 @@ help: ## Display this help.
 
 ##@ Development
 
+.PHONY: tidy
+tidy: ## Run go mod tidy against code.
+	go mod tidy
+
 .PHONY: fmt
 fmt: ## Run go fmt against code.
 	go fmt ./...
@@ -46,5 +50,16 @@ vet: ## Run go vet against code.
 ##@ Build
 
 .PHONY: build
-build: fmt vet ## Build manager binary.
+build: tidy fmt vet ## Build manager binary.
 	go build -o ./bin/sampleexternalplugin
+
+.PHONY: install
+install: build ## Build and install the binary with the current source code. Use it to test your changes locally.
+	rm -f $(GOBIN)/sampleexternalplugin
+	cp ./bin/sampleexternalplugin $(GOBIN)/sampleexternalplugin
+	# Make the binary discoverable for kubebuilder
+	./install.sh
+
+.PHONY: test-plugin
+test-plugin: ## Run the plugin test.
+	./test/test.sh

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/cmd/flags.go

@@ -16,11 +16,8 @@ limitations under the License.
 package cmd
 
 import (
-	"fmt"
-
 	"v1/scaffolds"
 
-	"github.com/spf13/pflag"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin/external"
 )
 
@@ -39,40 +36,17 @@ func flagsCmd(pr *external.PluginRequest) external.PluginResponse {
 		Flags:      []external.Flag{},
 	}
 
-	// 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")
-
-	if err := flagsToParse.Parse(pr.Args); err != nil {
-		pluginResponse.Error = true
-		pluginResponse.ErrorMsgs = []string{
-			fmt.Sprintf("failed to parse flags: %s", err.Error()),
-		}
-		return pluginResponse
-	}
-
-	initFlag, _ := flagsToParse.GetBool("init")
-	apiFlag, _ := flagsToParse.GetBool("api")
-	webhookFlag, _ := flagsToParse.GetBool("webhook")
-
-	// 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`
-	if initFlag {
-		// Add a flag to the JSON response `flags` field that Kubebuilder reads
-		// to ensure it binds to the flags given in the response.
+	switch pr.Command {
+	case "init":
 		pluginResponse.Flags = scaffolds.InitFlags
-	} else if apiFlag {
+	case "create api":
 		pluginResponse.Flags = scaffolds.ApiFlags
-	} else if webhookFlag {
+	case "create webhook":
 		pluginResponse.Flags = scaffolds.WebhookFlags
-	} else {
+	default:
 		pluginResponse.Error = true
 		pluginResponse.ErrorMsgs = []string{
-			"unrecognized flag",
+			"unrecognized command: " + pr.Command,
 		}
 	}
 

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/go.mod

@@ -1,6 +1,6 @@
 module v1
 
-go 1.23.0
+go 1.24.0
 
 require (
 	github.com/spf13/pflag v1.0.6
@@ -11,7 +11,7 @@ require (
 	github.com/gobuffalo/flect v1.0.3 // indirect
 	github.com/spf13/afero v1.14.0 // indirect
 	golang.org/x/mod v0.24.0 // indirect
-	golang.org/x/sync v0.12.0 // indirect
-	golang.org/x/text v0.23.0 // indirect
-	golang.org/x/tools v0.31.0 // indirect
+	golang.org/x/sync v0.14.0 // indirect
+	golang.org/x/text v0.25.0 // indirect
+	golang.org/x/tools v0.33.0 // indirect
 )

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/go.sum

@@ -33,16 +33,16 @@ github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsT
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 golang.org/x/mod v0.24.0 h1:ZfthKaKaT4NrhGVZHO1/WDTwGES4De8KtWO0SIbNJMU=
 golang.org/x/mod v0.24.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=
-golang.org/x/net v0.37.0 h1:1zLorHbz+LYj7MQlSf1+2tPIIgibq2eL5xkrGk6f+2c=
-golang.org/x/net v0.37.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=
-golang.org/x/sync v0.12.0 h1:MHc5BpPuC30uJk597Ri8TV3CNZcTLu6B6z4lJy+g6Jw=
-golang.org/x/sync v0.12.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
-golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
-golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
-golang.org/x/text v0.23.0 h1:D71I7dUrlY+VX0gQShAThNGHFxZ13dGLBHQLVl1mJlY=
-golang.org/x/text v0.23.0/go.mod h1:/BLNzu4aZCJ1+kcD0DNRotWKage4q2rGVAg4o22unh4=
-golang.org/x/tools v0.31.0 h1:0EedkvKDbh+qistFTd0Bcwe/YLh4vHwWEkiI0toFIBU=
-golang.org/x/tools v0.31.0/go.mod h1:naFTU+Cev749tSJRXJlna0T3WxKvb1kWEx15xA4SdmQ=
+golang.org/x/net v0.40.0 h1:79Xs7wF06Gbdcg4kdCCIQArK11Z1hr5POQ6+fIYHNuY=
+golang.org/x/net v0.40.0/go.mod h1:y0hY0exeL2Pku80/zKK7tpntoX23cqL3Oa6njdgRtds=
+golang.org/x/sync v0.14.0 h1:woo0S4Yywslg6hp4eUFjTVOyKt0RookbpAHG4c1HmhQ=
+golang.org/x/sync v0.14.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw=
+golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/text v0.25.0 h1:qVyWApTSYLk/drJRO5mDlNYskwQznZmkpV2c8q9zls4=
+golang.org/x/text v0.25.0/go.mod h1:WEdwpYrmk1qmdHvhkSTNPm3app7v4rsT8F2UD6+VHIA=
+golang.org/x/tools v0.33.0 h1:4qz2S3zmRxbGIhDIAgjxvFutSvH5EfnsYrRBj0UI0bc=
+golang.org/x/tools v0.33.0/go.mod h1:CIJMaWEY88juyUfo7UbgPqbC8rU2OqfAV1h2Qp0oMYI=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 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=

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/install.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# Copyright 2021 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.
+
+PLUGIN_NAME="sampleexternalplugin"
+PLUGIN_VERSION="v1"
+PLUGIN_BINARY="./bin/${PLUGIN_NAME}"
+
+if [[ ! -f "${PLUGIN_BINARY}" ]]; then
+  echo "Plugin binary not found at ${PLUGIN_BINARY}"
+  echo "Make sure you run: make build"
+  exit 1
+fi
+
+# Detect OS and set plugin destination path
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  PLUGIN_DEST="$HOME/Library/Application Support/kubebuilder/plugins/${PLUGIN_NAME}/${PLUGIN_VERSION}"
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+  PLUGIN_DEST="$HOME/.config/kubebuilder/plugins/${PLUGIN_NAME}/${PLUGIN_VERSION}"
+else
+  echo "Unsupported OS: $OSTYPE"
+  exit 1
+fi
+
+mkdir -p "${PLUGIN_DEST}"
+
+cp "${PLUGIN_BINARY}" "${PLUGIN_DEST}/${PLUGIN_NAME}"
+chmod +x "${PLUGIN_DEST}/${PLUGIN_NAME}"
+
+echo "Plugin installed at:"
+echo "${PLUGIN_DEST}/${PLUGIN_NAME}"

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/main.go

@@ -16,7 +16,9 @@ limitations under the License.
 
 package main
 
-import "v1/cmd"
+import (
+	"v1/cmd"
+)
 
 func main() {
 	cmd.Run()

docs/book/src/simple-external-plugin-tutorial/testdata/sampleexternalplugin/v1/scaffolds/api.go

@@ -32,16 +32,34 @@ var ApiFlags = []external.Flag{
 		Type:    "int",
 		Usage:   "set a number to be added to the scaffolded apiFile.txt",
 	},
+	{
+		Name:    "group",
+		Default: "",
+		Type:    "string",
+		Usage:   "API group name (e.g., 'example')",
+	},
+	{
+		Name:    "version",
+		Default: "",
+		Type:    "string",
+		Usage:   "API version (e.g., 'v1alpha1')",
+	},
+	{
+		Name:    "kind",
+		Default: "",
+		Type:    "string",
+		Usage:   "API kind (e.g., 'ExampleKind')",
+	},
 }
 
 var ApiMeta = plugin.SubcommandMetadata{
 	Description: "The `create api` subcommand of the sampleexternalplugin is meant to create an api for a project via Kubebuilder. It scaffolds a single file: `apiFile.txt`",
 	Examples: `
 	Scaffold with the defaults:
-	$ kubebuilder create api --plugins sampleexternalplugin/v1
+	$ kubebuilder create api --plugins sampleexternalplugin/v1 --group samplegroup --version v1 --kind SampleKind
 
 	Scaffold with a specific number in the apiFile.txt file:
-	$ kubebuilder create api --plugins sampleexternalplugin/v1 --number 2
+	$ kubebuilder create api --plugins sampleexternalplugin/v1 --number 2 --group samplegroup --version v1 --kind SampleKind
 	`,
 }
 
@@ -53,25 +71,46 @@ func ApiCmd(pr *external.PluginRequest) external.PluginResponse {
 		Universe:   pr.Universe,
 	}
 
-	// Here is an example of parsing a flag from a Kubebuilder external plugin request
 	flags := pflag.NewFlagSet("apiFlags", pflag.ContinueOnError)
 	flags.Int("number", 1, "set a number to be added in the scaffolded apiFile.txt")
+	flags.String("group", "", "API group name")
+	flags.String("version", "", "API version")
+	flags.String("kind", "", "API kind")
+
 	if err := flags.Parse(pr.Args); err != nil {
 		pluginResponse.Error = true
 		pluginResponse.ErrorMsgs = []string{
 			fmt.Sprintf("failed to parse flags: %s", err.Error()),
 		}
 		return pluginResponse
 	}
+
 	number, _ := flags.GetInt("number")
+	group, _ := flags.GetString("group")
+	version, _ := flags.GetString("version")
+	kind, _ := flags.GetString("kind")
 
-	apiFile := api.NewApiFile(api.WithNumber(number))
+	// Validate GVK inputs
+	if group == "" || version == "" || kind == "" {
+		pluginResponse.Error = true
+		pluginResponse.ErrorMsgs = []string{
+			"--group, --version, and --kind are required flags",
+		}
+		return pluginResponse
+	}
+
+	// Scaffold API file using all values
+	apiFile := api.NewApiFile(
+		api.WithNumber(number),
+		api.WithGroup(group),
+		api.WithVersion(version),
+		api.WithKind(kind),
+	)
 
 	// Phase 2 Plugins uses the concept of a "universe" to represent the filesystem for a plugin.
 	// This universe is a key:value mapping of filename:contents. Here we are adding the file
 	// "apiFile.txt" to the universe with some content. When this is returned Kubebuilder will
 	// take all values within the "universe" and write them to the user's filesystem.
 	pluginResponse.Universe[apiFile.Name] = apiFile.Contents
-
 	return pluginResponse
 }