feat: Initialize the grafana plugin

Author: Kavinjsir

cmd/main.go

@@ -33,6 +33,7 @@ import (
 	deployimagev1alpha1 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/deploy-image/v1alpha1"
 	golangv2 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/v2"
 	golangv3 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/golang/v3"
+	grafanav1alpha1 "sigs.k8s.io/kubebuilder/v3/pkg/plugins/optional/grafana/v1alpha"
 )
 
 func main() {
@@ -62,6 +63,7 @@ func main() {
 			&kustomizecommonv2alpha.Plugin{},
 			&declarativev1.Plugin{},
 			&deployimagev1alpha1.Plugin{},
+			&grafanav1alpha1.Plugin{},
 		),
 		cli.WithPlugins(externalPlugins...),
 		cli.WithDefaultPlugins(cfgv2.Version, golangv2.Plugin{}),

docs/book/src/SUMMARY.md

@@ -112,6 +112,7 @@
     - [go/v2 plugin (Deprecated)](./plugins/go-v2-plugin.md)
     - [go/v3 plugin](./plugins/go-v3-plugin.md)
     - [Declarative V1](./plugins/declarative-v1.md)
+    - [grafana/v1-alpha](./plugins/grafana-v1-alpha.md)
     - [Kustomize V1](./plugins/kustomize-v1.md)
   - [Plugins Versioning](./plugins/plugins-versioning.md)
 

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

@@ -2,20 +2,21 @@
 
 This section describes the plugins supported and shipped in with the Kubebuilder project.
 
-| Plugin   | Key | Description | 
-|---|---|---|
-| [go.kubebuilder.io/v2 - (Deprecated)](go-v2-plugin.md)    | `go/v2` | Golang plugin responsible for scaffolding the legacy layout provided with Kubebuilder CLI >= `2.0.0` and < `3.0.0`.  |
-| [go.kubebuilder.io/v3 - (Default scaffold with Kubebuilder init)](go-v3-plugin.md)  | `go/v3` | Default scaffold used for creating a project when no plugin(s) are provided. Responsible for scaffolding Golang projects and its configurations. |
-| [declarative.go.kubebuilder.io/v1](declarative-v1.md)  | `declarative/v1`  | Optional plugin used to scaffold APIs/controllers using the [kubebuilder-declarative-pattern][kubebuilder-declarative-pattern] project. |
-| [kustomize.common.kubebuilder.io/v1](kustomize-v1.md)  | `kustomize/v1`  | Responsible for scaffold all manifests to configure the projects with [kustomize(v3)][kustomize]. (create and update the the `config/` directory). This plugin is used in the composition to create the plugin (`go/v3`). |
-| [kustomize.common.kubebuilder.io/v2-alpha](kustomize-v2-alpha.md)  | `kustomize/v2-alpha`  | It has the same purpose of  `kustomize/v1`. However, it works with [kustomize][kustomize] version `v4` and addresses the required changes for future kustomize configurations. It will probably be used with the future `go/v4-alpha` plugin. |
-| `base.go.kubebuilder.io/v3`  | `base/v3` | Responsible for scaffold all files which specific requires Golang. This plugin is used in the composition to create the plugin (`go/v3`) |
+| Plugin                                                                             | Key                  | Description                                                                                                                                                                                                                                  |
+| ---------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [go.kubebuilder.io/v2 - (Deprecated)](go-v2-plugin.md)                             | `go/v2`              | Golang plugin responsible for scaffolding the legacy layout provided with Kubebuilder CLI >= `2.0.0` and < `3.0.0`.                                                                                                                          |
+| [go.kubebuilder.io/v3 - (Default scaffold with Kubebuilder init)](go-v3-plugin.md) | `go/v3`              | Default scaffold used for creating a project when no plugin(s) are provided. Responsible for scaffolding Golang projects and its configurations.                                                                                             |
+| [declarative.go.kubebuilder.io/v1](declarative-v1.md)                              | `declarative/v1`     | Optional plugin used to scaffold APIs/controllers using the [kubebuilder-declarative-pattern][kubebuilder-declarative-pattern] project.                                                                                                      |
+| [kustomize.common.kubebuilder.io/v1](kustomize-v1.md)                              | `kustomize/v1`       | Responsible for scaffold all manifests to configure the projects with [kustomize(v3)][kustomize]. (create and update the the `config/` directory). This plugin is used in the composition to create the plugin (`go/v3`).                    |
+| [kustomize.common.kubebuilder.io/v2-alpha](kustomize-v2-alpha.md)                  | `kustomize/v2-alpha` | It has the same purpose of `kustomize/v1`. However, it works with [kustomize][kustomize] version `v4` and addresses the required changes for future kustomize configurations. It will probably be used with the future `go/v4-alpha` plugin. |
+| `base.go.kubebuilder.io/v3`                                                        | `base/v3`            | Responsible for scaffold all files which specific requires Golang. This plugin is used in the composition to create the plugin (`go/v3`)                                                                                                     |
+| [grafana.kubebuilder.io/v1-alpha](grafana-v1-alpha.md)                             | `grafana/v1-alpha`   | Optional plugin which can be used to scaffold Grafana Manifests Dashboards for the default metrics which are exported by controller-runtime.                                                                                                 |
 
 <aside class="note">
 
 <h1>You can also create your own plugins, see:</h1>
 
-- [Creating your own plugins][create-plugins]. 
+- [Creating your own plugins][create-plugins].
 
 </aside>
 

docs/book/src/plugins/grafana-v1-alpha.md

@@ -0,0 +1,115 @@
+# Grafana Plugin (`grafana/v1-alpha`)
+
+The Grafana plugin is an optional plugin that can be used to scaffold Grafana Dashboards to allow you to check out the default metrics which are exported by projects using [controller-runtime][controller-runtime].
+
+<aside class="note">
+<h1>Examples</h1>
+
+You can check its default scaffold by looking at the `project-v3-with-grafana` projects under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
+
+</aside>
+
+## When to use it ?
+
+- If you are looking to observe the metrics exported by [controller metrics][controller-metrics] and collected by Prometheus via [Grafana][grafana].
+
+## How to use it ?
+
+### Prerequisites:
+
+- Your project must be using [controller-runtime][controller-runtime] to expose the metrics via the [controller default metrics][controller-metrics] and they need to be collected by Prometheus.
+- Access to [Prometheus][prometheus].
+  - Prometheus should have an endpoint exposed. (For `prometheus-operator`, this is similar as: http://prometheus-k8s.monitoring.svc:9090 )
+  - The endpoint is ready to/already become the datasource of your Grafana. See [Add a data source](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/)
+- Access to [Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/installation/). Make sure you have:
+  - [Dashboard edit permission](https://grafana.com/docs/grafana/next/administration/roles-and-permissions/#dashboard-permissions)
+  - Prometheus Data source
+    ![pre](https://user-images.githubusercontent.com/18136486/176119794-f6d69b0b-93f0-4f9e-a53c-daf9f77dadae.gif)
+
+<aside class="note">
+
+Check the [metrics][reference-metrics-doc] to know how to enable the metrics for your projects scaffold with Kubebuilder.
+
+See that in the [config/prometheus][kustomize-plugin] you will find the ServiceMonitor to enable the metrics in the default endpoint `/metrics`.
+
+</aside>
+
+### Basic Usage
+
+The Grafana plugin is attached to the `init` subcommand and the `edit` subcommand:
+
+```sh
+# Initialize a new project with grafana plugin
+kubebuilder init --plugins grafana.kubebuilder.io/v1-alpha
+
+# Enable grafana plugin to an existing project
+kubebuilder edit --plugins grafana.kubebuilder.io/v1-alpha
+```
+
+The plugin will create a new directory and scaffold the JSON files under it (i.e. `grafana/controller-runtime-metrics.json`).
+
+#### Show case:
+
+See an example of how to use the plugin in your project:
+
+![output](https://user-images.githubusercontent.com/18136486/175382307-9a6c3b8b-6cc7-4339-b221-2539d0fec042.gif)
+
+#### Now, let's check how to use the Grafana dashboards
+
+1. Copy the JSON file
+2. Visit `<your-grafana-url>/dashboard/import` to [import a new dashboard](https://grafana.com/docs/grafana/latest/dashboards/export-import/#import-dashboard).
+3. Paste the JSON content to `Import via panel json`, then press `Load` button
+   <img width="644" alt="Screen Shot 2022-06-28 at 3 40 22 AM" src="https://user-images.githubusercontent.com/18136486/176121955-1c4aec9c-0ba4-4271-9767-e8d1726d9d9a.png">
+4. Select the data source for Prometheus metrics
+   <img width="633" alt="Screen Shot 2022-06-28 at 3 41 26 AM" src="https://user-images.githubusercontent.com/18136486/176122261-e3eab5b0-9fc4-45fc-a68c-d9ce1cfe96ee.png">
+5. Once the json is imported in Grafana, the dashboard is ready.
+
+### Grafana Dashboard
+
+#### Controller Runtime Reconciliation total & errors
+
+- Metrics:
+  - controller_runtime_reconcile_total
+  - controller_runtime_reconcile_errors_total
+- Query:
+  - sum(rate(controller_runtime_reconcile_total{job="$job"}[5m])) by (instance, pod)
+  - sum(rate(controller_runtime_reconcile_errors_total{job="$job"}[5m])) by (instance, pod)
+- Description:
+  - Per-second rate of total reconciliation as measured over the last 5 minutes
+  - Per-second rate of reconciliation errors as measured over the last 5 minutes
+
+<img width="1430" alt="Screen Shot 2022-06-28 at 3 43 10 AM" src="https://user-images.githubusercontent.com/18136486/176122555-f3493658-6c99-4ad6-a9b7-63d85620d370.png">
+
+## Subcommands
+
+The Grafana 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:
+
+- `grafana/*.json`
+
+## Further resources
+
+- Refer to a sample of `servicemonitor` provided by [kustomize plugin][kustomize-plugin]
+- Check the [plugin implementation][plugin-implementation]
+- [Grafana Docs][grafana-docs] of importing JSON file
+- The usage of servicemonitor by [Prometheus Operator][servicemonitor]
+
+[controller-metrics]: https://book.kubebuilder.io/reference/metrics-reference.html
+[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime
+[grafana]: https://grafana.com/docs/grafana/next/
+[grafana-docs]: https://grafana.com/docs/grafana/latest/dashboards/export-import/#import-dashboard
+[kustomize-plugin]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v3/config/prometheus/monitor.yaml
+[kube-prometheus]: https://github.com/prometheus-operator/kube-prometheus
+[plugin-implementation]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/optional/grafana/alphav1
+[prometheus]: https://prometheus.io/docs/introduction/overview/
+[prom-operator]: https://prometheus-operator.dev/docs/prologue/introduction/
+[reference-metrics-doc]: https://book.kubebuilder.io/reference/metrics.html#exporting-metrics-for-prometheus
+[servicemonitor]: https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md#related-resources
+[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata

pkg/plugins/optional/grafana/v1alpha/commons.go

@@ -0,0 +1,40 @@
+/*
+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 v1alpha
+
+import (
+	"errors"
+
+	"sigs.k8s.io/kubebuilder/v3/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
+}

pkg/plugins/optional/grafana/v1alpha/constants.go

@@ -0,0 +1,29 @@
+/*
+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 v1alpha
+
+// nolint: lll
+const MetaDataDescription = `This command will add Grafana manifests to the project:
+  - A JSON file includes dashboard manifest that can be directly copied to Grafana Web UI.
+	('grafana/controller-runtime-metrics.json')
+
+NOTE: This plugin requires:
+- Access to Prometheus
+- Your project must be using controller-runtime to expose the metrics via the controller metrics and they need to be collected by Prometheus.
+- Access to Grafana (https://grafana.com/docs/grafana/latest/setup-grafana/installation/)
+Check how to enable the metrics for your project by looking at the doc: https://book.kubebuilder.io/reference/metrics.html
+`

pkg/plugins/optional/grafana/v1alpha/edit.go

@@ -0,0 +1,55 @@
+/*
+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 v1alpha
+
+import (
+	"fmt"
+
+	"sigs.k8s.io/kubebuilder/v3/pkg/config"
+	"sigs.k8s.io/kubebuilder/v3/pkg/machinery"
+	"sigs.k8s.io/kubebuilder/v3/pkg/plugin"
+	"sigs.k8s.io/kubebuilder/v3/pkg/plugins/optional/grafana/v1alpha/scaffolds"
+)
+
+var _ plugin.EditSubcommand = &editSubcommand{}
+
+type editSubcommand struct {
+	config config.Config
+}
+
+func (p *editSubcommand) UpdateMetadata(cliMeta plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
+	subcmdMeta.Description = MetaDataDescription
+
+	subcmdMeta.Examples = fmt.Sprintf(`  # Edit a common project with this plugin
+  %[1]s edit --plugins=grafana.kubebuilder.io/v1-alpha
+`, cliMeta.CommandName)
+}
+
+func (p *editSubcommand) InjectConfig(c config.Config) error {
+	p.config = c
+	return nil
+}
+
+func (p *editSubcommand) Scaffold(fs machinery.Filesystem) error {
+	if err := InsertPluginMetaToConfig(p.config, pluginConfig{}); err != nil {
+		return err
+	}
+
+	scaffolder := scaffolds.NewEditScaffolder()
+	scaffolder.InjectFS(fs)
+	return scaffolder.Scaffold()
+}

pkg/plugins/optional/grafana/v1alpha/init.go

@@ -0,0 +1,55 @@
+/*
+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 v1alpha
+
+import (
+	"fmt"
+
+	"sigs.k8s.io/kubebuilder/v3/pkg/config"
+	"sigs.k8s.io/kubebuilder/v3/pkg/machinery"
+	"sigs.k8s.io/kubebuilder/v3/pkg/plugin"
+	"sigs.k8s.io/kubebuilder/v3/pkg/plugins/optional/grafana/v1alpha/scaffolds"
+)
+
+var _ plugin.InitSubcommand = &initSubcommand{}
+
+type initSubcommand struct {
+	config config.Config
+}
+
+func (p *initSubcommand) UpdateMetadata(cliMeta plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
+	subcmdMeta.Description = MetaDataDescription
+
+	subcmdMeta.Examples = fmt.Sprintf(`  # Initialize a common project with this plugin
+  %[1]s init --plugins=grafana.kubebuilder.io/v1-alpha
+`, cliMeta.CommandName)
+}
+
+func (p *initSubcommand) InjectConfig(c config.Config) error {
+	p.config = c
+	return nil
+}
+
+func (p *initSubcommand) Scaffold(fs machinery.Filesystem) error {
+	if err := InsertPluginMetaToConfig(p.config, pluginConfig{}); err != nil {
+		return err
+	}
+
+	scaffolder := scaffolds.NewInitScaffolder()
+	scaffolder.InjectFS(fs)
+	return scaffolder.Scaffold()
+}