From fda7fcdc3fa591862f24feb45c9bd3604f38184a Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Sun, 22 Sep 2024 11:00:56 +0100 Subject: [PATCH] cleanup/refactory plugins section --- VERSIONING.md | 2 +- docs/book/src/SUMMARY.md | 23 +- docs/book/src/plugins/available-plugins.md | 11 +- .../available/deploy-image-plugin-v1-alpha.md | 101 +++++ .../plugins/{ => available}/go-v4-plugin.md | 46 +-- .../{ => available}/grafana-v1-alpha.md | 45 ++- .../src/plugins/available/kustomize-v2.md | 105 ++++++ docs/book/src/plugins/creating-plugins.md | 222 ----------- .../plugins/deploy-image-plugin-v1-alpha.md | 75 ---- docs/book/src/plugins/extending-cli.md | 212 ----------- docs/book/src/plugins/extending.md | 48 +++ .../extending_cli_features_and_plugins.md | 354 ++++++++++++++++++ .../src/plugins/extending/external-plugins.md | 151 ++++++++ .../src/plugins/extending/testing-plugins.md | 108 ++++++ docs/book/src/plugins/external-plugins.md | 162 -------- docs/book/src/plugins/kustomize-v2.md | 116 ------ docs/book/src/plugins/plugins-versioning.md | 33 +- docs/book/src/plugins/plugins.md | 28 +- docs/book/src/plugins/testing-plugins.md | 83 ---- .../src/plugins/to-add-optional-features.md | 11 +- docs/book/src/plugins/to-be-extended.md | 33 +- docs/book/src/plugins/to-scaffold-project.md | 9 +- 22 files changed, 994 insertions(+), 984 deletions(-) create mode 100644 docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md rename docs/book/src/plugins/{ => available}/go-v4-plugin.md (53%) rename docs/book/src/plugins/{ => available}/grafana-v1-alpha.md (82%) create mode 100644 docs/book/src/plugins/available/kustomize-v2.md delete mode 100644 docs/book/src/plugins/creating-plugins.md delete mode 100644 docs/book/src/plugins/deploy-image-plugin-v1-alpha.md delete mode 100644 docs/book/src/plugins/extending-cli.md create mode 100644 docs/book/src/plugins/extending.md create mode 100644 docs/book/src/plugins/extending/extending_cli_features_and_plugins.md create mode 100644 docs/book/src/plugins/extending/external-plugins.md create mode 100644 docs/book/src/plugins/extending/testing-plugins.md delete mode 100644 docs/book/src/plugins/external-plugins.md delete mode 100644 docs/book/src/plugins/kustomize-v2.md delete mode 100644 docs/book/src/plugins/testing-plugins.md diff --git a/VERSIONING.md b/VERSIONING.md index d26a8552434..8d5e7e2a971 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -59,4 +59,4 @@ take care of building and publishing the artifacts. [envtest-ref]: https://book.kubebuilder.io/reference/artifacts.html [tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases [kb-releases]:https://github.com/kubernetes-sigs/kubebuilder/releases -[cli-plugins-versioning]:docs/book/src/plugins/extending-cli.md#plugin-versioning +[cli-plugins-versioning]:docs/book/src/plugins/extending#plugin-versioning diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 67590e84a28..069002af3f4 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -118,18 +118,19 @@ - [Plugins][plugins] - [Available Plugins](./plugins/available-plugins.md) - - [To scaffold a project](./plugins/to-scaffold-project.md) - - [go/v4 (Default init scaffold)](./plugins/go-v4-plugin.md) - - [To add optional features](./plugins/to-add-optional-features.md) - - [grafana/v1-alpha](./plugins/grafana-v1-alpha.md) - - [deploy-image/v1-alpha](./plugins/deploy-image-plugin-v1-alpha.md) - - [To be extended for others tools](./plugins/to-be-extended.md) - - [kustomize/v2 (Default init scaffold with go/v4)](./plugins/kustomize-v2.md) - - [Extending the CLI](./plugins/extending-cli.md) - - [Creating your own plugins](./plugins/creating-plugins.md) - - [Testing your own plugins](./plugins/testing-plugins.md) + - [Create a Project](./plugins/to-scaffold-project.md) + - [go/v4](./plugins/available/go-v4-plugin.md) + - [Optional Features](./plugins/to-add-optional-features.md) + - [grafana/v1-alpha](./plugins/available/grafana-v1-alpha.md) + - [deploy-image/v1-alpha](./plugins/available/deploy-image-plugin-v1-alpha.md) + - [To Extend](./plugins/to-be-extended.md) + - [kustomize/v2](./plugins/available/kustomize-v2.md) + - [Extending](./plugins/extending.md) + - [CLI and Plugins](./plugins/extending/extending_cli_features_and_plugins.md) + - [External Plugins](./plugins/extending/external-plugins.md) + - [E2E Tests](./plugins/extending/testing-plugins.md) - [Plugins Versioning](./plugins/plugins-versioning.md) - - [Creating external plugins](./plugins/external-plugins.md) + --- diff --git a/docs/book/src/plugins/available-plugins.md b/docs/book/src/plugins/available-plugins.md index 3f723d05274..0e8db9c85d3 100644 --- a/docs/book/src/plugins/available-plugins.md +++ b/docs/book/src/plugins/available-plugins.md @@ -6,10 +6,13 @@ This section describes the plugins supported and shipped in with the Kubebuilder {{#include to-add-optional-features.md }} {{#include to-be-extended.md }} - + +[plugin-versions]: plugins-versioning.md \ No newline at end of file diff --git a/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md b/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md new file mode 100644 index 00000000000..6b71ff87867 --- /dev/null +++ b/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md @@ -0,0 +1,101 @@ +# Deploy Image Plugin (deploy-image/v1-alpha) + +The `deploy-image` plugin allows users to create [controllers][controller-runtime] and custom resources that deploy and manage container images on the cluster, following Kubernetes best practices. It simplifies the complexities of deploying images while allowing users to customize their projects as needed. + +By using this plugin, you will get: + +- A controller implementation to deploy and manage an Operand (image) on the cluster. +- Tests to verify the reconciliation logic, using [ENVTEST][envtest]. +- Custom resource samples updated with the necessary specifications. +- Environment variable support for managing the Operand (image) within the manager. + + + + +## When to use it? + +- This plugin is ideal for users who are just getting started with Kubernetes operators. +- It helps users deploy and manage an image (Operand) using the [Operator pattern][operator-pattern]. +- If you're looking for a quick and efficient way to set up a custom controller and manage a container image, this plugin is a great choice. + +## How to use it ? + +## How to use it? + +1. **Initialize your project**: + After creating a new project with `kubebuilder init`, you can use this + plugin to create APIs. Ensure that you've completed the + [quick start][quick-start] guide before proceeding. + +2. **Create APIs**: + With this plugin, you can [create APIs][create-apis] to specify the image (Operand) you want to deploy on the cluster. You can also optionally specify the command, port, and security context using various flags: + + Example command: + ```sh + kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.6.15-alpine --image-container-command="memcached,--memory-limit=64,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha" + ``` + + + +## Subcommands + +The `deploy-image` plugin includes the following subcommand: + +- `create api`: Use this command to scaffold the API and controller code to manage the container image. + +## Affected files + +When using the `create api` command with this plugin, the following +files are affected, in addition to the existing Kubebuilder scaffolding: + +- `controllers/*_controller_test.go`: Scaffolds tests for the controller. +- `controllers/*_suite_test.go`: Scaffolds or updates the test suite. +- `api//*_types.go`: Scaffolds the API specs. +- `config/samples/*_.yaml`: Scaffolds default values for the custom resource. +- `main.go`: Updates the file to add the controller setup. +- `config/manager/manager.yaml`: Updates to include environment variables for storing the image. + +## Further Resources: + +- Check out this [video][video] to see how it works. + +[video]: https://youtu.be/UwPuRjjnMjY +[operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ +[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime +[testdata]: ./.././../../../../testdata/project-v4-with-plugins +[envtest]: ./../../reference/envtest.md +[quick-start]: ./../../quick-start.md \ No newline at end of file diff --git a/docs/book/src/plugins/go-v4-plugin.md b/docs/book/src/plugins/available/go-v4-plugin.md similarity index 53% rename from docs/book/src/plugins/go-v4-plugin.md rename to docs/book/src/plugins/available/go-v4-plugin.md index b79d8a59562..23bcbfa9f53 100644 --- a/docs/book/src/plugins/go-v4-plugin.md +++ b/docs/book/src/plugins/available/go-v4-plugin.md @@ -1,30 +1,31 @@ -# [Default Scaffold] go/v4 (go.kubebuilder.io/v4) +# go/v4 (go.kubebuilder.io/v4) + +**(Default Scaffold)** Kubebuilder will scaffold using the `go/v4` plugin only if specified when initializing the project. -This plugin is a composition of the plugins ` kustomize.common.kubebuilder.io/v2` and `base.go.kubebuilder.io/v4`. -It scaffolds a project template that helps in constructing sets of [controllers][controller-runtime]. +This plugin is a composition of the `kustomize.common.kubebuilder.io/v2` and `base.go.kubebuilder.io/v4` plugins +using the [Bundle Plugin][bundle]. It scaffolds a project template +that helps in constructing sets of [controllers][controller-runtime]. -It scaffolds boilerplate code to create and design controllers. -Note that by following the [quickstart][quickstart] you will be using this plugin. -