Add Helm Plugin for Project Distribution

This PR introduces an optional Helm plugin, enabling users to scaffold Helm charts for Kubebuilder projects. - **Helm Chart Scaffolding**: Allows generation of a Helm chart under the `dist/chart` directory, providing an alternative for distributing and managing projects via Helm. - **Usage**: - **Initialize**: `kubebuilder init --plugins=helm/v1-alpha` for new projects. - **Update**: `kubebuilder edit --plugins=helm/v1-alpha` to add or update Helm charts for existing projects. - **Auto-sync Helm Chart**: Syncs the Helm chart with project manifests using the `edit` command, with `--force` required for updates after webhook or `DeployImage` plugin changes. - **Examples**: Usage samples can be found in `testdata/project-v4-with-plugins`. - **Testing**: Adds GitHub Actions workflows to validate Helm integration, including linting, installation, and e2e checks. **Note**: For details on the original proposal, see [PR kubernetes-sigs#3632](kubernetes-sigs#3632).
camilamacedo86 · Oct 25, 2024 · c4cd70f · c4cd70f
1 parent ce1a2c8
commit c4cd70f
Show file tree

Hide file tree

Showing 52 changed files with 2,907 additions and 17 deletions.
diff --git a/.github/workflows/test-helm-samples.yml b/.github/workflows/test-helm-samples.yml
@@ -0,0 +1,85 @@
+name: Helm Testdata Sample
+
+on:
+  push:
+    paths:
+      - 'testdata/project-v4-with-plugins/**'
+      - '.github/workflows/test-helm-samples.yml'
+  pull_request:
+    paths:
+      - 'testdata/project-v4-with-plugins/**'
+      - '.github/workflows/test-helm-samples.yml'
+
+jobs:
+  helm-test-project-v4-with-plugins:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '~1.22'
+
+      - name: Install the latest version of kind
+        run: |
+          curl -Lo ./kind https://kind.sigs.k8s.io/dl/latest/kind-linux-amd64
+          chmod +x ./kind
+          sudo mv ./kind /usr/local/bin/kind
+
+      - name: Verify kind installation
+        run: kind version
+
+      - name: Create kind cluster
+        run: kind create cluster
+
+      - name: Install cert-manager via Helm
+        run: |
+          helm repo add jetstack https://charts.jetstack.io
+          helm repo update
+          helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set installCRDs=true
+
+      - name: Wait for cert-manager to be ready
+        run: |
+          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager
+          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager-cainjector
+          kubectl wait --namespace cert-manager --for=condition=available --timeout=300s deployment/cert-manager-webhook
+
+      - name: Prepare project-v4-with-plugins
+        run: |
+          cd testdata/project-v4-with-plugins/
+          go mod tidy
+          make docker-build IMG=project-v4-with-plugins:v0.1.0
+          kind load docker-image project-v4-with-plugins:v0.1.0
+
+      - name: Install Helm
+        run: |
+          curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+
+      - name: Verify Helm installation
+        run: helm version
+
+      - name: Lint Helm chart for project-v4-with-plugins
+        run: |
+          helm lint testdata/project-v4-with-plugins/dist/chart
+
+      - name: Install Helm chart for project-v4-with-plugins
+        run: |
+          helm install my-release testdata/project-v4-with-plugins/dist/chart --create-namespace --namespace project-v4-with-plugins-system
+
+      - name: Check Helm release status
+        run: |
+          helm status my-release --namespace project-v4-with-plugins-system
+
+      - name: Wait for controller-manager pod to be running
+        run: |
+          kubectl wait --namespace project-v4-with-plugins-system --for=condition=Ready pod -l app.kubernetes.io/name=controller-manager --timeout=300s
+
+      - name: Verify controller-manager logs
+        if: ${{ always() }}
+        run: |
+          kubectl logs -n project-v4-with-plugins-system -l app.kubernetes.io/name=controller-manager
diff --git a/Makefile b/Makefile
@@ -97,7 +97,7 @@ lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes
 
 .PHONY: yamllint
 yamllint:
-	@files=$$(find testdata -name '*.yaml' ! -path 'testdata/*/dist/install.yaml'); \
+	@files=$$(find testdata -name '*.yaml' ! -path 'testdata/*/dist/*'); \
     	docker run --rm $$(tty -s && echo "-it" || echo) -v $(PWD):/data cytopia/yamllint:latest $$files -d "{extends: relaxed, rules: {line-length: {max: 120}}}" --no-warnings
 
 GOLANGCI_LINT = $(shell pwd)/bin/golangci-lint
@@ -171,3 +171,11 @@ test-spaces:  ## Run the trailing spaces check
 test-legacy:  ## Run the tests to validate legacy path for webhooks
 	rm -rf  ./testdata/**legacy**/
 	./test/testdata/legacy-webhook-path.sh
+
+.PHONY: install-helm
+install-helm: ## Install the latest version of Helm locally
+	@curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+
+.PHONY: helm-lint
+helm-lint: install-helm ## Lint the Helm chart in testdata
+	helm lint testdata/project-v4-with-plugins/dist/chart
diff --git a/cmd/main.go b/cmd/main.go
@@ -30,6 +30,7 @@ import (
 	deployimagev1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/deploy-image/v1alpha1"
 	golangv4 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/golang/v4"
 	grafanav1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/grafana/v1alpha"
+	helmv1alpha1 "sigs.k8s.io/kubebuilder/v4/pkg/plugins/optional/helm/v1alpha"
 )
 
 func init() {
@@ -61,6 +62,7 @@ func main() {
 			&kustomizecommonv2.Plugin{},
 			&deployimagev1alpha1.Plugin{},
 			&grafanav1alpha1.Plugin{},
+			&helmv1alpha1.Plugin{},
 		),
 		cli.WithPlugins(externalPlugins...),
 		cli.WithDefaultPlugins(cfgv3.Version, gov4Bundle),

diff --git a/docs/book/src/plugins/available/helm-v1-alpha.md b/docs/book/src/plugins/available/helm-v1-alpha.md
@@ -0,0 +1,92 @@
+# Helm Plugin (`helm/v1-alpha`)
+
+The Helm plugin is an optional plugin that can be used to scaffold a Helm chart, allowing you to distribute the project using Helm.
+
+By default, users can generate a bundle with all the manifests by running the following command:
+
+```bash
+make build-installer IMG=<some-registry>/<project-name:tag>
+```
+
+This allows the project consumer to install the solution by applying the bundle with:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/<org>/project-v4/<tag or branch>/dist/install.yaml
+```
+
+However, in many scenarios, you might prefer to provide a Helm chart to package your solution.
+If so, you can use this plugin to generate the Helm chart under the `dist` directory.
+
+<aside class="note">
+<h1>Examples</h1>
+
+You can check the plugin usage by looking at `project-v4-with-plugins` samples
+under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
+
+</aside>
+
+## When to use it
+
+- If you want to provide a Helm chart for users to install and manage your project.
+- If you need to update the Helm chart generated under `dist/chart/` with the latest project changes:
+  - After generating new manifests, use the `edit` option to sync the Helm chart.
+  - **IMPORTANT:** If you have created a webhook or an API using the [DeployImage][deployImage-plugin] plugin,
+  you must run the `edit` command with the `--force` flag to regenerate the Helm chart values based
+  on the latest manifests (_after running `make manifests`_) to ensure that the HelmChart values are
+  updated accordingly. In this case, if you have customized the files
+  under `dist/chart/values.yaml`, and the `templates/manager/manager.yaml`, you will need to manually reapply your customizations on top
+  of the latest changes after regenerating the Helm chart.
+
+## How to use it ?
+
+### Basic Usage
+
+The Helm plugin is attached to the `init` subcommand and the `edit` subcommand:
+
+```sh
+
+# Initialize a new project with helm chart
+kubebuilder init --plugins=helm/v1-alpha
+
+# Enable or Update the helm chart via the helm plugin to an existing project
+# Before run the edit command, run `make manifests` to generate the manifest under `config/`
+make manifests
+kubebuilder edit --plugins=helm/v1-alpha
+```
+<aside class="note">
+  <h1>Use the edit command to update the Helm Chart with the latest changes</h1>
+
+  After making changes to your project, ensure that you run `make manifests` and then
+  use the command `kubebuilder edit --plugins=helm/v1-alpha` to update the Helm Chart.
+
+  Note that the following files will **not** be updated unless you use the `--force` flag:
+
+  <pre>
+  dist/chart/
+  ├── values.yaml
+  └── templates/
+      └── manager/
+          └── manager.yaml
+  </pre>
+
+  The files `chart/Chart.yaml`, `chart/templates/_helpers.tpl`, and `chart/.helmignore` are never updated
+  after their initial creation unless you remove them.
+
+</aside>
+
+## Subcommands
+
+The Helm plugin implements the following subcommands:
+
+- edit (`$ kubebuilder edit [OPTIONS]`)
+
+- init (`$ kubebuilder init [OPTIONS]`)
+
+## Affected files
+
+The following scaffolds will be created or updated by this plugin:
+
+- `dist/chart/*`
+
+[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/project-v4-with-plugins
+[deployImage-plugin]: ./deploy-image-plugin-v1-alpha.md
diff --git a/docs/book/src/plugins/to-add-optional-features.md b/docs/book/src/plugins/to-add-optional-features.md
@@ -2,10 +2,12 @@
 
 The following plugins are useful to generate code and take advantage of optional features
 
-| Plugin                                            | Key                  | Description                                                                                                                                                                                                                                  |
-|---------------------------------------------------| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [grafana.kubebuilder.io/v1-alpha][grafana]        | `grafana/v1-alpha`   | Optional helper plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime.                                                                                                 |
-| [deploy-image.go.kubebuilder.io/v1-alpha][deploy] | `deploy-image/v1-alpha`   | Optional helper plugin which can be used to scaffold APIs and controller with code implementation to Deploy and Manage an Operand(image).                                                                                                 |
+| Plugin                                            | Key                     | Description                                                                                                                                         |
+|---------------------------------------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
+| [grafana.kubebuilder.io/v1-alpha][grafana]        | `grafana/v1-alpha`      | Optional helper plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime. |
+| [deploy-image.go.kubebuilder.io/v1-alpha][deploy] | `deploy-image/v1-alpha` | Optional helper plugin which can be used to scaffold APIs and controller with code implementation to Deploy and Manage an Operand(image).           |
+| [helm.kubebuilder.io/v1-alpha][helm]              | `helm/v1-alpha`         | Optional helper plugin which can be used to scaffold a Helm Chart to distribute the project under the `dist` directory                              |
 
 [grafana]: ./available/grafana-v1-alpha.md
-[deploy]: ./available/deploy-image-plugin-v1-alpha.md
+[deploy]: ./available/deploy-image-plugin-v1-alpha.md
+[helm]: ./available/helm-v1-alpha.md
diff --git a/pkg/cli/alpha/internal/generate.go b/pkg/cli/alpha/internal/generate.go
@@ -44,6 +44,7 @@ const (
 	defaultOutputDir     = "output-dir"
 	grafanaPluginKey     = "grafana.kubebuilder.io/v1-alpha"
 	deployImagePluginKey = "deploy-image.go.kubebuilder.io/v1-alpha"
+	helmPluginKey        = "helm.kubebuilder.io/v1-alpha"
 )
 
 // Generate handles the migration and scaffolding process.
@@ -77,6 +78,12 @@ func (opts *Generate) Generate() error {
 		return err
 	}
 
+	if hasHelmPlugin(config) {
+		if err := kubebuilderHelmEdit(); err != nil {
+			return err
+		}
+	}
+
 	if err := migrateDeployImagePlugin(config); err != nil {
 		return err
 	}
@@ -392,3 +399,32 @@ func kubebuilderGrafanaEdit() error {
 	}
 	return nil
 }
+
+// Edits the project to include the Grafana plugin.
+func kubebuilderHelmEdit() error {
+	args := []string{"edit", "--plugins", helmPluginKey}
+	if err := util.RunCmd("kubebuilder edit", "kubebuilder", args...); err != nil {
+		return fmt.Errorf("failed to run edit subcommand for Helm plugin: %w", err)
+	}
+	return nil
+}
+
+// hasHelmPlugin checks if the Helm plugin is present by inspecting the plugin chain or configuration.
+func hasHelmPlugin(cfg store.Store) bool {
+	var pluginConfig map[string]interface{}
+
+	// Decode the Helm plugin configuration to check if it's present
+	err := cfg.Config().DecodePluginConfig(helmPluginKey, &pluginConfig)
+	if err != nil {
+		// If the Helm plugin is not found, return false
+		if errors.As(err, &config.PluginKeyNotFoundError{}) {
+			return false
+		}
+		// Log other errors if needed
+		log.Errorf("Error decoding Helm plugin config: %v", err)
+		return false
+	}
+
+	// Helm plugin is present
+	return true
+}
diff --git a/pkg/plugins/optional/helm/v1alpha/commons.go b/pkg/plugins/optional/helm/v1alpha/commons.go
@@ -0,0 +1,37 @@
+/*
+Copyright 2024 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 v1alpha
+
+import (
+	"errors"
+
+	"sigs.k8s.io/kubebuilder/v4/pkg/config"
+)
+
+func insertPluginMetaToConfig(target config.Config, cfg pluginConfig) error {
+	err := target.DecodePluginConfig(pluginKey, cfg)
+	if !errors.As(err, &config.UnsupportedFieldError{}) {
+		if err != nil && !errors.As(err, &config.PluginKeyNotFoundError{}) {
+			return err
+		}
+		if err = target.EncodePluginConfig(pluginKey, cfg); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}