forked from kubernetes-sigs/kubebuilder
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
(doc) - refactory and clenup the Plugin section
Over time, this section has grown incrementally, leading to content duplication and outdated or irrelevant information. To address this, we are now: - Re-organizing the structure for better clarity. - Fixing broken or outdated links. - Removing duplicated and obsolete content. - Re-writing and refining parts of the sections to ensure accuracy and relevance. - Ensuring the Kubebuilder layout doc's standards
- Loading branch information
1 parent
820b71d
commit 3f1f568
Showing
22 changed files
with
1,115 additions
and
917 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
111 changes: 111 additions & 0 deletions
111
docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,111 @@ | ||
| # 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. | ||
|
|
||
| <aside class="note"> | ||
| <h1>Examples</h1> | ||
|
|
||
| See the `project-v4-with-plugins` directory under the [testdata][testdata] | ||
| directory in the Kubebuilder project to check an example | ||
| of scaffolding created using this plugin. | ||
|
|
||
| The `Memcached` API and its controller was scaffolded | ||
| using the command: | ||
|
|
||
| ```shell | ||
| kubebuilder create api \ | ||
| --group example.com \ | ||
| --version v1alpha1 \ | ||
| --kind Memcached \ | ||
| --image=memcached:memcached:1.6.26-alpine3.19 \ | ||
| --image-container-command="memcached,--memory-limit=64,-o,modern,-v" \ | ||
| --image-container-port="11211" \ | ||
| --run-as-user="1001" \ | ||
| --plugins="deploy-image/v1-alpha" | ||
| ``` | ||
|
|
||
| The `Busybox` API was created with: | ||
|
|
||
| ```shell | ||
| kubebuilder create api \ | ||
| --group example.com \ | ||
| --version v1alpha1 \ | ||
| --kind Busybox \ | ||
| --image=busybox:1.36.1 \ | ||
| --plugins="deploy-image/v1-alpha" | ||
| ``` | ||
| </aside> | ||
|
|
||
|
|
||
| ## 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? | ||
|
|
||
| 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" | ||
| ``` | ||
|
|
||
| <aside class="warning"> | ||
| <h1>Note on make run:</h1> | ||
|
|
||
| When running the project locally with `make run`, the Operand image | ||
| provided will be stored as an environment variable in the | ||
| `config/manager/manager.yaml` file. | ||
|
|
||
| Ensure you export the environment variable before running the project locally, such as: | ||
|
|
||
| ```shell | ||
| export MEMCACHED_IMAGE="memcached:1.4.36-alpine" | ||
| ``` | ||
|
|
||
| </aside> | ||
|
|
||
| ## 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/<version>/*_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 | ||
| [create-apis]: ../../cronjob-tutorial/new-api.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # 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 `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]. | ||
|
|
||
| By following the [quickstart][quickstart] and creating any project, | ||
| you will be using this plugin by default. | ||
|
|
||
| <aside class="note"> | ||
| <h1>Examples</h1> | ||
|
|
||
| You can check samples using this plugin by looking at the `project-v4-<options>` projects under the [testdata][testdata] | ||
| directory on the root directory of the Kubebuilder project. | ||
|
|
||
| </aside> | ||
|
|
||
| ## How to use it ? | ||
|
|
||
| To create a new project with the `go/v4` plugin the following command can be used: | ||
|
|
||
| ```sh | ||
| kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project --plugins=go/v4 | ||
| ``` | ||
|
|
||
| ## Subcommands supported by the plugin | ||
|
|
||
| - Init - `kubebuilder init [OPTIONS]` | ||
| - Edit - `kubebuilder edit [OPTIONS]` | ||
| - Create API - `kubebuilder create api [OPTIONS]` | ||
| - Create Webhook - `kubebuilder create webhook [OPTIONS]` | ||
|
|
||
| ## Further resources | ||
|
|
||
| - To see the composition of plugins, you can check the source code for the Kubebuilder [main.go][plugins-main]. | ||
| - Check the code implementation of the [base Golang plugin `base.go.kubebuilder.io/v4`][v4-plugin]. | ||
| - Check the code implementation of the [Kustomize/v2 plugin][kustomize-plugin]. | ||
| - Check [controller-runtime][controller-runtime] to know more about controllers. | ||
|
|
||
| [controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime | ||
| [quickstart]: ./../../quick-start.md | ||
| [testdata]: ./../../../../../testdata | ||
| [plugins-main]: ./../../../../../cmd/main.go | ||
| [kustomize-plugin]: ./../../plugins/avaialable/kustomize-v2.md | ||
| [kustomize]: https://github.com/kubernetes-sigs/kustomize | ||
| [standard-go-project]: https://github.com/golang-standards/project-layout | ||
| [v4-plugin]: ./../../../../../pkg/plugins/golang/v4 | ||
| [migration-guide-doc]: ./../../migration/migration_guide_gov3_to_gov4.md | ||
| [project-doc]: ./../../reference/project-config.md | ||
| [bundle]: ./../../../../../pkg/plugin/bundle.go |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.