From 2b3287b896d7e0a4d76ed87961b60d9618d57cfe Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Fri, 29 Mar 2024 20:12:35 +0000 Subject: [PATCH] :book: remove traling spaces of all docs --- README.md | 18 +-- RELEASE.md | 12 +- designs/code-generate-image-plugin.md | 70 ++++---- designs/crd_version_conversion.md | 6 +- ...e-cli-and-scaffolding-plugins-phase-1-5.md | 4 +- ...ble-cli-and-scaffolding-plugins-phase-2.md | 4 +- ...er_to_upgrade_projects_by_rescaffolding.md | 20 +-- docs/book/src/SUMMARY.md | 2 +- docs/book/src/architecture.md | 2 +- .../component-config-tutorial/api-changes.md | 6 +- .../component-config-tutorial/custom-type.md | 2 +- .../define-config.md | 2 +- .../define-custom-config.md | 2 +- .../src/component-config-tutorial/tutorial.md | 6 +- docs/book/src/cronjob-tutorial/epilogue.md | 2 +- docs/book/src/cronjob-tutorial/gvks.md | 4 +- docs/book/src/cronjob-tutorial/running.md | 6 +- docs/book/src/faq.md | 16 +- docs/book/src/getting-started.md | 12 +- docs/book/src/introduction.md | 2 +- docs/book/src/logos/README.md | 4 +- .../legacy/migration_guide_v1tov2.md | 2 +- .../legacy/migration_guide_v2tov3.md | 20 +-- docs/book/src/migration/legacy/v2vsv3.md | 28 ++-- .../manually_migration_guide_gov3_to_gov4.md | 12 +- .../migration/migration_guide_gov3_to_gov4.md | 8 +- docs/book/src/migration/v3-plugins.md | 4 +- docs/book/src/migration/v3vsv4.md | 2 +- .../testdata/project/README.md | 6 +- docs/book/src/plugins/creating-plugins.md | 4 +- docs/book/src/plugins/declarative-v1.md | 14 +- .../plugins/deploy-image-plugin-v1-alpha.md | 150 +++++++++--------- docs/book/src/plugins/extending-cli.md | 32 ++-- docs/book/src/plugins/external-plugins.md | 12 +- docs/book/src/plugins/go-v3-plugin.md | 8 +- docs/book/src/plugins/go-v4-plugin.md | 12 +- docs/book/src/plugins/kustomize-v1.md | 32 ++-- docs/book/src/plugins/kustomize-v2.md | 4 +- docs/book/src/plugins/plugins-versioning.md | 2 +- docs/book/src/quick-start.md | 2 +- docs/book/src/reference/admission-webhook.md | 32 ++-- docs/book/src/reference/completion.md | 6 +- docs/book/src/reference/good-practices.md | 8 +- docs/book/src/reference/platform.md | 46 +++--- docs/book/src/reference/project-config.md | 10 +- docs/book/src/reference/raising-events.md | 18 +-- docs/book/src/reference/rescaffold.md | 16 +- docs/book/src/reference/submodule-layouts.md | 6 +- docs/book/src/reference/using-finalizers.md | 2 +- .../src/reference/using_an_external_type.md | 10 +- docs/kubebuilder_v0_v1_difference.md | 22 +-- docs/migration_guide.md | 2 +- docs/testing/e2e.md | 6 +- 53 files changed, 370 insertions(+), 370 deletions(-) diff --git a/README.md b/README.md index 7ab2727e630..48c7bcdc175 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,10 @@ Kubebuilder is developed on top of the [controller-runtime][controller-runtime] ### Kubebuilder is also a library Kubebuilder is extensible and can be used as a library in other projects. -[Operator-SDK][operator-sdk] is a good example of a project that uses Kubebuilder as a library. +[Operator-SDK][operator-sdk] is a good example of a project that uses Kubebuilder as a library. [Operator-SDK][operator-sdk] uses the plugin feature to include non-Go operators _e.g. operator-sdk's Ansible and Helm-based language Operators_. -To learn more see [how to create your own plugins][your-own-plugins]. +To learn more see [how to create your own plugins][your-own-plugins]. ### Installation @@ -39,9 +39,9 @@ See the [Getting Started](https://book.kubebuilder.io/quick-start.html) document ![Quick Start](docs/gif/kb-demo.v3.11.1.svg) -Also, ensure that you check out the [Deploy Image](https://book.kubebuilder.io/plugins/deploy-image-plugin-v1-alpha.html) -Plugin. This plugin allows users to scaffold API/Controllers to deploy and manage an -Operand (image) on the cluster following the guidelines and best practices. It abstracts the +Also, ensure that you check out the [Deploy Image](https://book.kubebuilder.io/plugins/deploy-image-plugin-v1-alpha.html) +Plugin. This plugin allows users to scaffold API/Controllers to deploy and manage an +Operand (image) on the cluster following the guidelines and best practices. It abstracts the complexities of achieving this goal while allowing users to customize the generated code. ## Documentation @@ -121,8 +121,8 @@ Before starting any work, please either comment on an existing issue, or file a ## Supportability -Currently, Kubebuilder officially supports OSX and Linux platforms. -So, if you are using a Windows OS you may find issues. Contributions towards +Currently, Kubebuilder officially supports OSX and Linux platforms. +So, if you are using a Windows OS you may find issues. Contributions towards supporting Windows are welcome. ### Apple Silicon @@ -130,9 +130,9 @@ supporting Windows are welcome. Apple Silicon (`darwin/arm64`) support begins with the `go/v4` plugin. ## Community Meetings - + The following meetings happen biweekly: - + - Kubebuilder Meeting You are more than welcome to attend. For further info join to [kubebuilder@googlegroups.com](https://groups.google.com/g/kubebuilder). diff --git a/RELEASE.md b/RELEASE.md index f1329419e9d..3a746893ae7 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -25,14 +25,14 @@ process was done to ensure that we have an aligned process under the org (simila > **Note** > - You will need to have checkout locally from the remote repository the previous branch > - Also, ensure that you fetch all tags from the remote `git fetch --all --tags` -> - Also, if you face issues to generate the release notes you might want to able to sort it out by running i.e.: +> - Also, if you face issues to generate the release notes you might want to able to sort it out by running i.e.: > `go run sigs.k8s.io/kubebuilder-release-tools/notes --use-upstream=false --from=v3.11.0 --branch=release-X` ### Draft a new release from GitHub 1. Create a new tag with the correct version from the new `release-` branch -2. Verify the Release Github Action. It should build the assets and publish in the draft release +2. Verify the Release Github Action. It should build the assets and publish in the draft release 3. You also need to manually add the changelog generated above on the release page and publish it. Now, the code source is released ! ### Update the website docs (https://book.kubebuilder.io/quick-start.html) @@ -75,7 +75,7 @@ This action will caall the job [./build/.goreleaser.yml](./build/.goreleaser.yml Kubebuilder projects requires artifacts which are used to do test with ENV TEST (when we call `make test` target) These artifacts can be checked in the service page: https://storage.googleapis.com/kubebuilder-tools -The build is made from the branch [tools-releases](https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases) and the trigger will call the `build/cloudbuild_tools.yaml` passing +The build is made from the branch [tools-releases](https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases) and the trigger will call the `build/cloudbuild_tools.yaml` passing as argument the architecture and the SO that should be used, e.g: Screenshot 2022-04-30 at 10 15 41 @@ -91,7 +91,7 @@ These images are can be checked in the consolse, see [here](https://console.clou The project `kube-rbac-proxy` is in the process to be donated to the k8s org. However, it is going on for a long time and then, we have no ETA for that to occur. When that occurs we can automate this process. But until there we need to generate these images -by bumping the versions/tags released by `kube-rbac-proxy` on the branch +by bumping the versions/tags released by `kube-rbac-proxy` on the branch [kube-rbac-proxy-releases](https://github.com/kubernetes-sigs/kubebuilder/tree/kube-rbac-proxy-releases) then the `build/cloudbuild_kube-rbac-proxy.yaml` will generate the images. @@ -118,8 +118,8 @@ and not the image, see: github_token: ${{ secrets.GITHUB_TOKEN }} ``` -However, the image should still be built and maintained since other projects under the org might be using them. +However, the image should still be built and maintained since other projects under the org might be using them. [kubebuilder-release-tools]: https://github.com/kubernetes-sigs/kubebuilder-release-tools [release-notes-generation]: https://github.com/kubernetes-sigs/kubebuilder-release-tools/blob/master/README.md#release-notes-generation -[release-process]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/VERSIONING.md#releasing +[release-process]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/VERSIONING.md#releasing diff --git a/designs/code-generate-image-plugin.md b/designs/code-generate-image-plugin.md index 719eba97eac..dc0fe89948b 100644 --- a/designs/code-generate-image-plugin.md +++ b/designs/code-generate-image-plugin.md @@ -8,10 +8,10 @@ This proposal defines a new plugin which allow users get the scaffold with the required code to have a project that will deploy and manage an image on the cluster following the guidelines and what have been considered as good practices. - + ## Motivation -The biggest part of the Kubebuilder users looking for to create a project that will at the end only deploy an image. In this way, one of the mainly motivations of this proposal is to abstract the complexities to achieve this goal and still giving the possibility of users improve and customize their projects according to their requirements. +The biggest part of the Kubebuilder users looking for to create a project that will at the end only deploy an image. In this way, one of the mainly motivations of this proposal is to abstract the complexities to achieve this goal and still giving the possibility of users improve and customize their projects according to their requirements. **Note:** This plugin will address requests that has been raised for a while and for many users in the community. Check [here](https://github.com/operator-framework/operator-sdk/pull/2158), for example, a request done in the past for the SDK project which is integrated with Kubebuidler to address the same need. @@ -19,15 +19,15 @@ The biggest part of the Kubebuilder users looking for to create a project that w - Add a new plugin to generate the code required to deploy and manage an image on the cluster - Promote the best practices as give example of common implementations -- Make the process to develop operators projects easier and more agil. +- Make the process to develop operators projects easier and more agil. - Give flexibility to the users and allow them to change the code according to their needs - Provide examples of code implementations and of the most common features usage and reduce the learning curve - + ### Non-Goals -The idea of this proposal is provide a facility for the users. This plugin can be improved +The idea of this proposal is provide a facility for the users. This plugin can be improved in the future, however, this proposal just covers the basic requirements. In this way, is a non-goal -allow extra configurations such as; scaffold the project using webhooks and the controller covered by tests. +allow extra configurations such as; scaffold the project using webhooks and the controller covered by tests. ## Proposal @@ -38,12 +38,12 @@ Add the new plugin code generate which will scaffold code implementation to depl - Add an EnvVar on the manager manifest (`config/manager/manager.yaml`) which will store the image informed and shows its possibility to users: ```yaml - .. + .. spec: containers: - name: manager env: - - name: {{ resource}}-IMAGE + - name: {{ resource}}-IMAGE value: {{image:tag}} image: controller:latest ... @@ -66,9 +66,9 @@ Add the new plugin code generate which will scaffold code implementation to depl } ``` -- Add the watch feature for the Deployment managed by the controller: +- Add the watch feature for the Deployment managed by the controller: -```go +```go func (r *{{ resource }}Reconciler) SetupWithManager(mgr ctrl.Manager) error { return ctrl.NewControllerManagedBy(mgr). For(&cachev1alpha1.{{ resource }}{}). @@ -87,19 +87,19 @@ func (r *{{ resource }}Reconciler) SetupWithManager(mgr ctrl.Manager) error { - Add a [marker][markers] in the spec definition to demonstrate how to use OpenAPI schemas validation such as `+kubebuilder:validation:Minimum=1` -- Add the specs on the `_types.go` to generate the CRD/CR sample with default values for `ImagePullPolicy` (`Always`), `ContainerPort` (`80`) and the `Replicas Size` (`3`) +- Add the specs on the `_types.go` to generate the CRD/CR sample with default values for `ImagePullPolicy` (`Always`), `ContainerPort` (`80`) and the `Replicas Size` (`3`) + +- Add a finalizer implementation with TODO for the CR managed by the controller such as described in the SDK doc [Handle Cleanup on Deletion](https://sdk.operatorframework.io/docs/building-operators/golang/advanced-topics/#handle-cleanup-on-deletion) -- Add a finalizer implementation with TODO for the CR managed by the controller such as described in the SDK doc [Handle Cleanup on Deletion](https://sdk.operatorframework.io/docs/building-operators/golang/advanced-topics/#handle-cleanup-on-deletion) - ### User Stories -- I am as user, would like to use a command to scaffold my common need which is deploy an image of my application, so that I do not need to know exactly how to implement it +- I am as user, would like to use a command to scaffold my common need which is deploy an image of my application, so that I do not need to know exactly how to implement it -- I am as user, would like to have a good example code base which uses the common features, so that I can easily learn its concepts and have a good start point to address my needs. +- I am as user, would like to have a good example code base which uses the common features, so that I can easily learn its concepts and have a good start point to address my needs. - I am as maintainer, would like to have a good example to address the common questions, so that I can easily describe how to implement the projects and/or use the common features. - -### Implementation Details/Notes/Constraints + +### Implementation Details/Notes/Constraints **Example of the controller template** @@ -160,9 +160,9 @@ func (r *{{ resource }}.Reconciler) Reconcile(req ctrl.Request) (ctrl.Result, er // Spec updated - return and requeue return ctrl.Result{Requeue: true}, nil } - + // TODO: add here code implementation to update/manage the status - + return ctrl.Result{}, nil } @@ -214,7 +214,7 @@ func labelsFor{{ resource }}(name string) map[string]string { // imageFor{{ resource }} returns the image for the resources // belonging to the given {{ resource }} CR name. func imageFor{{ resource }}(name string) string { - // TODO: this method will return the value of the envvar create to store the image:tag informed + // TODO: this method will return the value of the envvar create to store the image:tag informed } func (r *{{ resource }}Reconciler) SetupWithManager(mgr ctrl.Manager) error { @@ -224,7 +224,7 @@ func (r *{{ resource }}Reconciler) SetupWithManager(mgr ctrl.Manager) error { Complete(r) } -``` +``` **Example of the spec for the _types.go template** @@ -241,7 +241,7 @@ type {{ resource }}Spec struct { // ImagePullPolicy defines the policy to pull the container images ImagePullPolicy string `json:"image-pull-policy,omitempty"` - // ContainerPort specifies the port which will be used by the image container + // ContainerPort specifies the port which will be used by the image container ContainerPort int `json:"container-port,omitempty"` } @@ -255,8 +255,8 @@ To ensure this implementation a new project example should be generated in the [ ### Graduation Criteria -- The new plugin will only be support `project-version=3` -- The attribute image with the value informed should be added to the resources model in the PROJECT file to let the tool know that the Resource get done with the common basic code implementation: +- The new plugin will only be support `project-version=3` +- The attribute image with the value informed should be added to the resources model in the PROJECT file to let the tool know that the Resource get done with the common basic code implementation: ```yaml plugins: @@ -267,34 +267,34 @@ plugins: kind: Captain version: v1 image: "/: -``` +``` -For further information check the definition agreement register in the comment https://github.com/kubernetes-sigs/kubebuilder/issues/1941#issuecomment-778649947. +For further information check the definition agreement register in the comment https://github.com/kubernetes-sigs/kubebuilder/issues/1941#issuecomment-778649947. -## Open Questions +## Open Questions -1. Should we allow to scaffold the code for an API that is already created for the project? -No, at least in the first moment to keep the simplicity. +1. Should we allow to scaffold the code for an API that is already created for the project? +No, at least in the first moment to keep the simplicity. 2. Should we support StatefulSet and Deployments? The idea is we start it by using a Deployment. However, we can improve the feature in follow-ups to support more default types of scaffolds which could be like `kubebuilder create api --group=crew --version=v1 --image=myexample:0.0.1 --kind=App --plugins=deploy-image.go.kubebuilder.io/v1beta1 --type=[deployment|statefulset|webhook]` 3. Could this feature be useful to other languages or is it just valid to Go based operators? -This plugin would is reponsable to scaffold content and files for Go-based operators. In a future, if other language-based operators starts to be supported (either officially or by the community) this plugin could be used as reference to create an equivalent one for their languages. Therefore, it should probably not to be a `subdomain` of `go.kubebuilder.io.` +This plugin would is reponsable to scaffold content and files for Go-based operators. In a future, if other language-based operators starts to be supported (either officially or by the community) this plugin could be used as reference to create an equivalent one for their languages. Therefore, it should probably not to be a `subdomain` of `go.kubebuilder.io.` For its integration with SDK, it might be valid for the Ansible-based operators where a new `playbook/role` could be generated as well. However, for example, for the Helm plugin it might to be useless. E.g `deploy-image.ansible.sdk.operatorframework.io/v1beta1` -4. Should we consider create a separate repo for plugins? +4. Should we consider create a separate repo for plugins? -In the long term yes. However, see that currently, Kubebuilder has not too many plugins yet. And then, and the preliminary support for plugins did not indeed release. For more info see the [Extensible CLI and Scaffolding Plugins][plugins-phase1-design-doc]. +In the long term yes. However, see that currently, Kubebuilder has not too many plugins yet. And then, and the preliminary support for plugins did not indeed release. For more info see the [Extensible CLI and Scaffolding Plugins][plugins-phase1-design-doc]. -In this way, at this moment, it shows to be a little Premature Optimization. Note that the issue [#2016](https://github.com/kubernetes-sigs/kubebuilder/issues/1378) will check the possibility of the plugins be as separate binaries that can be discovered by the Kubebuilder CLI binary via user-specified plugin file paths. Then, the discussion over the best approach to dealing with many plugins and if they should or not leave in the Kubebuilder repository would be better addressed after that. +In this way, at this moment, it shows to be a little Premature Optimization. Note that the issue [#2016](https://github.com/kubernetes-sigs/kubebuilder/issues/1378) will check the possibility of the plugins be as separate binaries that can be discovered by the Kubebuilder CLI binary via user-specified plugin file paths. Then, the discussion over the best approach to dealing with many plugins and if they should or not leave in the Kubebuilder repository would be better addressed after that. -5. Is Kubebuilder prepared to receive this implementation already? +5. Is Kubebuilder prepared to receive this implementation already? The [Extensible CLI and Scaffolding Plugins - Phase 1.5](extensible-cli-and-scaffolding-plugins-phase-1-5.md) and the issue #1941 requires to be implemented before this proposal. Also, to have a better idea over the proposed solutions made so for the Plugin Ecosystem see the meta issue [#2016](https://github.com/kubernetes-sigs/kubebuilder/issues/2016) -[markers]: ../docs/book/src/reference/markers.md +[markers]: ../docs/book/src/reference/markers.md [conditions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties [plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md \ No newline at end of file diff --git a/designs/crd_version_conversion.md b/designs/crd_version_conversion.md index e5358a0460d..72861318946 100644 --- a/designs/crd_version_conversion.md +++ b/designs/crd_version_conversion.md @@ -20,7 +20,7 @@ This document describes high level design and workflow for supporting multiple v ## Hub and Spoke -The basic concept is that all versions of an object share the storage. So say if you have versions v1, v2 and v3 of a Kind Toy, kubernetes will use one of the versions to persist the object in stable storage i.e. Etcd. User can specify the version to be used for storage in the Custom Resource definition for that API. +The basic concept is that all versions of an object share the storage. So say if you have versions v1, v2 and v3 of a Kind Toy, kubernetes will use one of the versions to persist the object in stable storage i.e. Etcd. User can specify the version to be used for storage in the Custom Resource definition for that API. One can think storage version as the hub and other versions as spoke to visualize the relationship between storage and other versions (as shown below in the diagram). The key thing to note is that conversion between storage and other version should be lossless (round trippable). As shown in the diagram below, v3 is the storage/hub version and v1, v2 and v4 are spoke version. The document uses storage version and hub interchangeably. @@ -58,7 +58,7 @@ func (ej *ExternalJob) ConvertTo(dst conversion.Hub) error { jobv3 := dst.(*v3.ExternalJob) jobv3.ObjectMeta = ej.ObjectMeta // conversion implementation - // + // return nil default: return fmt.Errorf("unsupported type %v", t) @@ -181,7 +181,7 @@ The tool that generates the CRD manifests lives under controller-tools repo. Cur ## Storage/Serve annotations: -The resource annotation will be extended to indicate storage/serve attributes as shown below. +The resource annotation will be extended to indicate storage/serve attributes as shown below. ```Go // ... diff --git a/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md b/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md index 463cecf3848..e71dfb6ced7 100644 --- a/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md +++ b/designs/extensible-cli-and-scaffolding-plugins-phase-1-5.md @@ -88,7 +88,7 @@ therefore, use this error to tell the CLI that no further execution step should ### Initialization hooks #### Update metadata -This hook will be used for two purposes. It provides CLI-related metadata to the Subcommand (e.g., +This hook will be used for two purposes. It provides CLI-related metadata to the Subcommand (e.g., command name) and update the subcommands metadata such as the description or examples. - Required/optional @@ -184,7 +184,7 @@ configuration at this hook will not be persisted. - [x] Edit - [x] Create API - [x] Create webhook - + ### Override plugins for single subcommand calls Defining plugins at initialization and using them for every command call will solve most of the cases. diff --git a/designs/extensible-cli-and-scaffolding-plugins-phase-2.md b/designs/extensible-cli-and-scaffolding-plugins-phase-2.md index 13da9089211..dfd17151311 100644 --- a/designs/extensible-cli-and-scaffolding-plugins-phase-2.md +++ b/designs/extensible-cli-and-scaffolding-plugins-phase-2.md @@ -129,7 +129,7 @@ Example `PROJECT` file: ```yaml version: "3" domain: testproject.org -layout: +layout: - go.kubebuilder.io/v3 - myexternalplugin/v2 plugins: @@ -278,7 +278,7 @@ What happens when the above is invoked? `PluginRequest JSON`: ```JSON -{ +{ "command":"init", "args":["--domain","example.com"], "universe":{} diff --git a/designs/helper_to_upgrade_projects_by_rescaffolding.md b/designs/helper_to_upgrade_projects_by_rescaffolding.md index 3ec6c329e5b..cef5554d858 100644 --- a/designs/helper_to_upgrade_projects_by_rescaffolding.md +++ b/designs/helper_to_upgrade_projects_by_rescaffolding.md @@ -94,8 +94,8 @@ in the example section above, see: ```shell kubebuilder alpha generate \ - --input-dir= - --output-dir= + --input-dir= + --output-dir= --no-backup --backup-path= --plugins= @@ -105,10 +105,10 @@ kubebuilder alpha generate \ - input-dir: [Optional] If not informed, then, by default, it is the current directory (project directory). If the `PROJECT` file does not exist, it will fail. - output-dir: [Optional] If not informed then, it should be the current repository. -- no-backup: [Optional] If not informed then, the current directory should be copied to the path `.backup/project-name` -- backup: [Optional] If not informed then, the backup will be copied to the path `.backup/project-name` +- no-backup: [Optional] If not informed then, the current directory should be copied to the path `.backup/project-name` +- backup: [Optional] If not informed then, the backup will be copied to the path `.backup/project-name` - plugins: [Optional] If not informed then, it is the same plugin chain available in the layout field -- binary: [Optional] If not informed then, the command will use KubeBuilder binary installed globaly. +- binary: [Optional] If not informed then, the command will use KubeBuilder binary installed globaly. > Note that the backup created in the current directory must be prefixed with `.`. Otherwise the tool will not able to perform the scaffold to create a new project from the scratch. @@ -118,26 +118,26 @@ This command would mainly perform the following operations: - 1. Check the flags - 2. If the backup flag be used, then check if is a valid path and make a backup of the current project - 3. Copy the whole current directory to `.backup/project-name` -- 4. Ensure that the output path is clean. By default it is the current directory project where the project was scaffolded previously and it should be cleaned up before to do the re-scaffold. +- 4. Ensure that the output path is clean. By default it is the current directory project where the project was scaffolded previously and it should be cleaned up before to do the re-scaffold. Only the content under `.backup/project-name` should be kept. - 4. Read the [PROJECT config][project-config] - 5. Re-run all commands using the KubeBuilder binary to recreate the project in the output directory -The command should also provide a comprensive help with examples of the proposed workflows. So that, users +The command should also provide a comprensive help with examples of the proposed workflows. So that, users are able to understand how to use it when run `--help`. ### User Stories **As an Operator author:** -- I can re-generate my project from scratch based on the proposed helper, which executes all the -commands according to my previous input to the project. That way, I can easily migrate my project to the new layout +- I can re-generate my project from scratch based on the proposed helper, which executes all the +commands according to my previous input to the project. That way, I can easily migrate my project to the new layout using the newer CLI/plugin versions, which support the latest changes, bug fixes, and features. - I can regenerate my project from the scratch based on all commands that I used the tool to build my project previously but informing a new init plugin chain, so that I could upgrade my current project to new layout versions and experiment alpha ones. - I would like to re-generate the project from the scratch using the same config provide in the PROJECT file and inform -a path to do a backup of my current directory so that I can also use the backup to compare with the new scaffold and add my custom code +a path to do a backup of my current directory so that I can also use the backup to compare with the new scaffold and add my custom code on top again without the need to compare my local directory and new scaffold with any outside source. **As a Kubebuiler maintainer:** diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index cb389867449..4806de043f9 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -71,7 +71,7 @@ - [Migration by updating the files](migration/legacy/manually_migration_guide_v2_v3.md) - [From v3.0.0 with plugins](./migration/v3-plugins.md) - [go/v3 vs go/v4](migration/v3vsv4.md) - + - [Migration Guide](migration/migration_guide_gov3_to_gov4.md) - [Migration by updating the files](migration/manually_migration_guide_gov3_to_gov4.md) - [Single Group to Multi-Group](./migration/multi-group.md) diff --git a/docs/book/src/architecture.md b/docs/book/src/architecture.md index ef12bd22fa2..bccb71898c1 100644 --- a/docs/book/src/architecture.md +++ b/docs/book/src/architecture.md @@ -1,6 +1,6 @@ # Architecture Concept Diagram -The following diagram will help you get a better idea over the Kubebuilder concepts and architecture. +The following diagram will help you get a better idea over the Kubebuilder concepts and architecture. {{#include ./kb_concept_diagram.svg}} diff --git a/docs/book/src/component-config-tutorial/api-changes.md b/docs/book/src/component-config-tutorial/api-changes.md index edd39223edd..cc01863346d 100644 --- a/docs/book/src/component-config-tutorial/api-changes.md +++ b/docs/book/src/component-config-tutorial/api-changes.md @@ -14,8 +14,8 @@ Please, be aware that it will force Kubebuilder remove this option soon in futur This tutorial will show you how to create a custom configuration file for your project by modifying a project generated with the `--component-config` flag -passed to the `init` command. The full tutorial's source can be found -[here][tutorial-source]. Make sure you've gone through the [installation +passed to the `init` command. The full tutorial's source can be found +[here][tutorial-source]. Make sure you've gone through the [installation steps](/quick-start.md#installation) before continuing. ## New project: @@ -63,7 +63,7 @@ if configFile != "" {

Your Options may have defaults from flags.

-If you have previously allowed other `flags` like `--metrics-bind-addr` or +If you have previously allowed other `flags` like `--metrics-bind-addr` or `--enable-leader-election`, you'll want to set those on the `Options` before loading the config from the file. diff --git a/docs/book/src/component-config-tutorial/custom-type.md b/docs/book/src/component-config-tutorial/custom-type.md index 55910168e48..a147b4f96a8 100644 --- a/docs/book/src/component-config-tutorial/custom-type.md +++ b/docs/book/src/component-config-tutorial/custom-type.md @@ -28,4 +28,4 @@ configurations, e.g. `ClusterName`, `Region` or anything serializable into updating your `main.go` to setup the new type for parsing. The rest of this tutorial will walk through implementing a custom component -config type. \ No newline at end of file +config type. \ No newline at end of file diff --git a/docs/book/src/component-config-tutorial/define-config.md b/docs/book/src/component-config-tutorial/define-config.md index aad23970c08..c337954d9b3 100644 --- a/docs/book/src/component-config-tutorial/define-config.md +++ b/docs/book/src/component-config-tutorial/define-config.md @@ -13,7 +13,7 @@ Please, be aware that it will force Kubebuilder remove this option soon in futur Now that you have a component config base project we need to customize the -values that are passed into the controller, to do this we can take a look at +values that are passed into the controller, to do this we can take a look at `config/manager/controller_manager_config.yaml`. {{#literatego ./testdata/controller_manager_config.yaml}} diff --git a/docs/book/src/component-config-tutorial/define-custom-config.md b/docs/book/src/component-config-tutorial/define-custom-config.md index 454b45b3c6a..13a65f2f4c5 100644 --- a/docs/book/src/component-config-tutorial/define-custom-config.md +++ b/docs/book/src/component-config-tutorial/define-custom-config.md @@ -12,7 +12,7 @@ Please, be aware that it will force Kubebuilder remove this option soon in futur -Now that you have a custom component config we change the +Now that you have a custom component config we change the `config/manager/controller_manager_config.yaml` to use the new GVK you defined. {{#literatego ./testdata/project/config/manager/controller_manager_config.yaml}} diff --git a/docs/book/src/component-config-tutorial/tutorial.md b/docs/book/src/component-config-tutorial/tutorial.md index 4482f686bb2..b388f653c41 100644 --- a/docs/book/src/component-config-tutorial/tutorial.md +++ b/docs/book/src/component-config-tutorial/tutorial.md @@ -3,9 +3,9 @@ @@ -133,7 +133,7 @@ the new version go/v4 uses Kustomize v5x and no longer Kustomize v4. Therefore, implementations in the config you need to ensure that them can work with Kustomize v5 and/if not update/upgrade any breaking change that you might face. -In v4, installation of Kustomize has been changed from bash script to `go get`. Change the `kustomize` dependency in Makefile to +In v4, installation of Kustomize has been changed from bash script to `go get`. Change the `kustomize` dependency in Makefile to ``` .PHONY: kustomize kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary. If wrong version is installed, it will be removed before downloading. diff --git a/docs/book/src/migration/v3-plugins.md b/docs/book/src/migration/v3-plugins.md index cefc5dabd3a..ea79b49be8e 100644 --- a/docs/book/src/migration/v3-plugins.md +++ b/docs/book/src/migration/v3-plugins.md @@ -1,10 +1,10 @@ # V3 - Plugins Layout Migration Guides -Following the migration guides from the plugins versions. Note that the plugins ecosystem +Following the migration guides from the plugins versions. Note that the plugins ecosystem was introduced with Kubebuilder v3.0.0 release where the go/v3 version is the default layout since `28 Apr 2021`. -Therefore, you can check here how to migrate the projects built from Kubebuilder 3.x with +Therefore, you can check here how to migrate the projects built from Kubebuilder 3.x with the plugin go/v3 to the latest. diff --git a/docs/book/src/migration/v3vsv4.md b/docs/book/src/migration/v3vsv4.md index 2f3af039f13..30cc3d4ca8d 100644 --- a/docs/book/src/migration/v3vsv4.md +++ b/docs/book/src/migration/v3vsv4.md @@ -20,7 +20,7 @@ The details of all changes (breaking or otherwise) can be found in: - no longer scaffold webhook test files with `"k8s.io/api/admission/v1beta1"` the k8s API which is no longer served since k8s `1.25`. By default webhooks test files are scaffolding using `"k8s.io/api/admission/v1"` which is support from k8s `1.20` - no longer provide backwards compatible support with k8s versions < `1.16` -- change the layout to accommodate the community request to follow the [Standard Go Project Layout][standard-go-project] +- change the layout to accommodate the community request to follow the [Standard Go Project Layout][standard-go-project] by moving the api(s) under a new directory called `api`, controller(s) under a new directory called `internal` and the `main.go` under a new directory named `cmd` ## Subcommands supported by the plugin diff --git a/docs/book/src/plugins/go-v4-plugin.md b/docs/book/src/plugins/go-v4-plugin.md index 6d7da044c21..b79d8a59562 100644 --- a/docs/book/src/plugins/go-v4-plugin.md +++ b/docs/book/src/plugins/go-v4-plugin.md @@ -1,16 +1,16 @@ -# [Default Scaffold] go/v4 (go.kubebuilder.io/v4) +# [Default Scaffold] go/v4 (go.kubebuilder.io/v4) -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]. +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]. -It scaffolds boilerplate code to create and design controllers. +It scaffolds boilerplate code to create and design controllers. Note that by following the [quickstart][quickstart] you will be using this plugin. diff --git a/docs/book/src/plugins/kustomize-v1.md b/docs/book/src/plugins/kustomize-v1.md index b8c4d41351f..6a1ab54bc8e 100644 --- a/docs/book/src/plugins/kustomize-v1.md +++ b/docs/book/src/plugins/kustomize-v1.md @@ -7,27 +7,27 @@ The kustomize/v1 plugin is deprecated. If you are using this plugin, it is recom to migrate to the kustomize/v2 plugin which uses Kustomize v5 and provides support for Apple Silicon (M1). -If you are using Golang projects scaffolded with `go/v3` which uses this version please, check +If you are using Golang projects scaffolded with `go/v3` which uses this version please, check the [Migration guide](../migration/v3vsv4.md) to learn how to upgrade your projects. -The kustomize plugin allows you to scaffold all kustomize manifests used to work with the language plugins such as `go/v2` and `go/v3`. -By using the kustomize plugin, you can create your own language plugins and ensure that you will have the same configurations -and features provided by it. +The kustomize plugin allows you to scaffold all kustomize manifests used to work with the language plugins such as `go/v2` and `go/v3`. +By using the kustomize plugin, you can create your own language plugins and ensure that you will have the same configurations +and features provided by it. + Note that projects such as [Operator-sdk][sdk] consume the Kubebuilder project as a lib and provide options to work with other languages like Ansible and Helm. The kustomize plugin allows them to easily keep a maintained configuration and ensure that all languages have @@ -42,24 +42,24 @@ able to create "helper" plugins which can work with many projects and languages. You can check the kustomize content by looking at the `config/` directory. Samples are provided under the [testdata][testdata] directory of the Kubebuilder project. - + ## When to use it ? -If you are looking to scaffold the kustomize configuration manifests for your own language plugin +If you are looking to scaffold the kustomize configuration manifests for your own language plugin ## How to use it ? If you are looking to define that your language plugin should use kustomize use the [Bundle Plugin][bundle] to specify that your language plugin is a composition with your plugin responsible for scaffold -all that is language specific and kustomize for its configuration, see: +all that is language specific and kustomize for its configuration, see: ```go // Bundle plugin which built the golang projects scaffold by Kubebuilder go/v3 // The follow code is creating a new plugin with its name and version via composition // You can define that one plugin is composite by 1 or Many others plugins - gov3Bundle, _ := plugin.NewBundle(plugin.WithName(golang.DefaultNameQualifier), + gov3Bundle, _ := plugin.NewBundle(plugin.WithName(golang.DefaultNameQualifier), plugin.WithVersion(plugin.Version{Number: 3}), plugin.WithPlugins(kustomizecommonv1.Plugin{}, golangv3.Plugin{}), // scaffold the config/ directory and all kustomize files // Scaffold the Golang files and all that specific for the language e.g. go.mod, apis, controllers @@ -69,8 +69,8 @@ all that is language specific and kustomize for its configuration, see: Also, with Kubebuilder, you can use kustomize alone via: ```sh -kubebuilder init --plugins=kustomize/v1 -$ ls -la +kubebuilder init --plugins=kustomize/v1 +$ ls -la total 24 drwxr-xr-x 6 camilamacedo86 staff 192 31 Mar 09:56 . drwxr-xr-x 11 camilamacedo86 staff 352 29 Mar 21:23 .. @@ -84,7 +84,7 @@ Or combined with the base language plugins: ```sh # Provides the same scaffold of go/v3 plugin which is a composition (kubebuilder init --plugins=go/v3) -kubebuilder init --plugins=kustomize/v1,base.go.kubebuilder.io/v3 --domain example.org --repo example.org/guestbook-operator +kubebuilder init --plugins=kustomize/v1,base.go.kubebuilder.io/v3 --domain example.org --repo example.org/guestbook-operator ``` ## Subcommands @@ -102,7 +102,7 @@ Its implementation for the subcommand create api will scaffold the kustomize man which are specific for each API, see [here][kustomize-create-api]. The same applies to its implementation for create webhook. - + ## Affected files @@ -112,7 +112,7 @@ The following scaffolds will be created or updated by this plugin: ## Further resources -* Check the kustomize [plugin implementation](https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/common/kustomize) +* Check the kustomize [plugin implementation](https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/common/kustomize) * Check the [kustomize documentation][kustomize-docs] * Check the [kustomize repository][kustomize-github] diff --git a/docs/book/src/plugins/kustomize-v2.md b/docs/book/src/plugins/kustomize-v2.md index b8ae3d9348d..f8709eb3df8 100644 --- a/docs/book/src/plugins/kustomize-v2.md +++ b/docs/book/src/plugins/kustomize-v2.md @@ -1,4 +1,4 @@ -# [Default Scaffold] Kustomize v2 +# [Default Scaffold] Kustomize v2 The kustomize plugin allows you to scaffold all kustomize manifests used to work with the language base plugin `base.go.kubebuilder.io/v4`. This plugin is used to generate the manifest under `config/` directory for the projects build within the go/v4 plugin (default scaffold). @@ -44,7 +44,7 @@ import ( // Bundle plugin which built the golang projects scaffold by Kubebuilder go/v3 // The follow code is creating a new plugin with its name and version via composition // You can define that one plugin is composite by 1 or Many others plugins - gov3Bundle, _ := plugin.NewBundle(plugin.WithName(golang.DefaultNameQualifier), + gov3Bundle, _ := plugin.NewBundle(plugin.WithName(golang.DefaultNameQualifier), plugin.WithVersion(plugin.Version{Number: 3}), plugin.WithPlugins(kustomizecommonv2.Plugin{}, golangv3.Plugin{}), // scaffold the config/ directory and all kustomize files // Scaffold the Golang files and all that specific for the language e.g. go.mod, apis, controllers diff --git a/docs/book/src/plugins/plugins-versioning.md b/docs/book/src/plugins/plugins-versioning.md index 8104a5ca31b..add3389f875 100644 --- a/docs/book/src/plugins/plugins-versioning.md +++ b/docs/book/src/plugins/plugins-versioning.md @@ -1,7 +1,7 @@ # Plugins Versioning | Name | Example | Description | -|----------|-------------|--------| +|----------|-------------|--------| | Kubebuilder version | `v2.2.0`, `v2.3.0`, `v2.3.1` | Tagged versions of the Kubebuilder project, representing changes to the source code in this repository. See the [releases][kb-releases] page for binary releases. | | Project version | `"1"`, `"2"`, `"3"` | Project version defines the scheme of a `PROJECT` configuration file. This version is defined in a `PROJECT` file's `version`. | | Plugin version | `v2`, `v3` | Represents the version of an individual plugin, as well as the corresponding scaffolding that it generates. This version is defined in a plugin key, ex. `go.kubebuilder.io/v2`. See the [design doc][cli-plugins-versioning] for more details. | diff --git a/docs/book/src/quick-start.md b/docs/book/src/quick-start.md index 2abb74fab1f..f6600c0b23a 100644 --- a/docs/book/src/quick-start.md +++ b/docs/book/src/quick-start.md @@ -230,7 +230,7 @@ make undeploy ## Next Step Now, see the [architecture concept diagram][architecture-concept-diagram] for a better overview and follow up the -[CronJob tutorial][cronjob-tutorial] to better understand how it works by developing a +[CronJob tutorial][cronjob-tutorial] to better understand how it works by developing a demo example project. diff --git a/docs/book/src/reference/platform.md b/docs/book/src/reference/platform.md index b8c93cfab68..1d2fcab8e00 100644 --- a/docs/book/src/reference/platform.md +++ b/docs/book/src/reference/platform.md @@ -1,12 +1,12 @@ # Platforms Supported -Kubebuilder produces solutions that by default can work on multiple platforms or specific ones, depending on how you +Kubebuilder produces solutions that by default can work on multiple platforms or specific ones, depending on how you build and configure your workloads. This guide aims to help you properly configure your projects according to your needs. ## Overview -To provide support on specific or multiple platforms, you must ensure that all images used in workloads are built to -support the desired platforms. Note that they may not be the same as the platform where you develop your solutions and use KubeBuilder, but instead the platform(s) where your solution should run and be distributed. +To provide support on specific or multiple platforms, you must ensure that all images used in workloads are built to +support the desired platforms. Note that they may not be the same as the platform where you develop your solutions and use KubeBuilder, but instead the platform(s) where your solution should run and be distributed. It is recommended to build solutions that work on multiple platforms so that your project works on any Kubernetes cluster regardless of the underlying operating system and architecture. @@ -16,8 +16,8 @@ The following covers what you need to do to provide the support for one or more ### 1) Build workload images to provide the support for other platform(s) -The images used in workloads such as in your Pods/Deployments will need to provide the support for this other platform. -You can inspect the images using a ManifestList of supported platforms using the command +The images used in workloads such as in your Pods/Deployments will need to provide the support for this other platform. +You can inspect the images using a ManifestList of supported platforms using the command [docker manifest inspect ][docker-manifest], i.e.: ```shell @@ -68,8 +68,8 @@ $ docker manifest inspect myresgystry/example/myimage:v0.0.1 ### 2) (Recommended as a Best Practice) Ensure that node affinity expressions are set to match the supported platforms -Kubernetes provides a mechanism called [nodeAffinity][node-affinity] which can be used to limit the possible node -targets where a pod can be scheduled. This is especially important to ensure correct scheduling behavior in clusters +Kubernetes provides a mechanism called [nodeAffinity][node-affinity] which can be used to limit the possible node +targets where a pod can be scheduled. This is especially important to ensure correct scheduling behavior in clusters with nodes that span across multiple platforms (i.e. heterogeneous clusters). **Kubernetes manifest example** @@ -95,7 +95,7 @@ affinity: **Golang Example** -```go +```go Template: corev1.PodTemplateSpec{ ... Spec: corev1.PodSpec{ @@ -133,7 +133,7 @@ Template: corev1.PodTemplateSpec{ @@ -149,7 +149,7 @@ See that projects scaffold with the latest versions of Kubebuilder have the Make $ make docker-buildx IMG=myregistry/myoperator:v0.0.1 ``` -Note that you need to ensure that all images and workloads required and used by your project will provide the same +Note that you need to ensure that all images and workloads required and used by your project will provide the same support as recommended above, and that you properly configure the [nodeAffinity][node-affinity] for all your workloads. Therefore, ensure that you uncomment the following code in the `config/manager/manager.yaml` file @@ -180,17 +180,17 @@ Therefore, ensure that you uncomment the following code in the `config/manager/m

Building images for releases

-You will probably want to automate the releases of your projects to ensure that the images are always built for the +You will probably want to automate the releases of your projects to ensure that the images are always built for the same platforms. Note that Goreleaser also supports [docker buildx][buildx]. See its [documentation][goreleaser-buildx] for more detail. -Also, you may want to configure GitHub Actions, Prow jobs, or any other solution that you use to build images to -provide multi-platform support. Note that you can also use other options like `docker manifest create` to customize +Also, you may want to configure GitHub Actions, Prow jobs, or any other solution that you use to build images to +provide multi-platform support. Note that you can also use other options like `docker manifest create` to customize your solutions to achieve the same goals with other tools. By using Docker and the target provided by default you should NOT change the Dockerfile to use any specific GOOS and GOARCH to build the manager binary. However, if you are looking for to customize the default scaffold and create your own implementations you might want to give -a look in the Golang [doc](https://go.dev/doc/install/source#environment) to knows +a look in the Golang [doc](https://go.dev/doc/install/source#environment) to knows its available options. @@ -201,12 +201,12 @@ Projects created with the Kubebuilder CLI have two workloads which are: ### Manager -The container to run the manager implementation is configured in the `config/manager/manager.yaml` file. +The container to run the manager implementation is configured in the `config/manager/manager.yaml` file. This image is built with the Dockerfile file scaffolded by default and contains the binary of the project \ which will be built via the command `go build -a -o manager main.go`. -Note that when you run `make docker-build` OR `make docker-build IMG=myregistry/myprojectname:` -an image will be built from the client host (local environment) and produce an image for +Note that when you run `make docker-build` OR `make docker-build IMG=myregistry/myprojectname:` +an image will be built from the client host (local environment) and produce an image for the client os/arch, which is commonly linux/amd64 or linux/arm64. + ## Overview @@ -41,7 +41,7 @@ You may also lose the ability to use some of the CLI features and helpers. For f ## Adjusting your Project -For a proper Sub-Module layout, we will use the generated APIs as a starting point. +For a proper Sub-Module layout, we will use the generated APIs as a starting point. For the steps below, we will assume you created your project in your `GOPATH` with @@ -105,7 +105,7 @@ go mod tidy go: finding module for package YOUR_GO_PATH/test-operator/api/v1alpha1 YOUR_GO_PATH/test-operator imports YOUR_GO_PATH/test-operator/api/v1alpha1: cannot find module providing package YOUR_GO_PATH/test-operator/api/v1alpha1: module YOUR_GO_PATH/test-operator/api/v1alpha1: git ls-remote -q origin in LOCALVCSPATH: exit status 128: - remote: Repository not found. + remote: Repository not found. fatal: repository 'https://YOUR_GO_PATH/test-operator/' not found ``` diff --git a/docs/book/src/reference/using-finalizers.md b/docs/book/src/reference/using-finalizers.md index 52c8f3cdbd8..ebcd464b430 100644 --- a/docs/book/src/reference/using-finalizers.md +++ b/docs/book/src/reference/using-finalizers.md @@ -8,7 +8,7 @@ on object's deletion from Kubernetes, you can use a finalizer to do that. You can read more about the finalizers in the [Kubernetes reference docs](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#finalizers). The section below demonstrates how to register and trigger pre-delete hooks in the `Reconcile` method of a controller. -The key point to note is that a finalizer causes "delete" on the object to become +The key point to note is that a finalizer causes "delete" on the object to become an "update" to set deletion timestamp. Presence of deletion timestamp on the object indicates that it is being deleted. Otherwise, without finalizers, a delete shows up as a reconcile where the object is missing from the cache. diff --git a/docs/book/src/reference/using_an_external_type.md b/docs/book/src/reference/using_an_external_type.md index 14fcd522048..10b2c93bc4f 100644 --- a/docs/book/src/reference/using_an_external_type.md +++ b/docs/book/src/reference/using_an_external_type.md @@ -11,7 +11,7 @@ Currently, kubebuilder handles the first two, CRDs and Core Resources, seamlessl In order to use a Kubernetes Custom Resource that has been defined in another project you will need to have several items of information. * The Domain of the CR -* The Group under the Domain +* The Group under the Domain * The Go import path of the CR Type definition * The Custom Resource Type you want to depend on. @@ -114,7 +114,7 @@ func init() { utilruntime.Must(clientgoscheme.AddToScheme(scheme)) utilruntime.Must(theirgroupv1alpha1.AddToScheme(scheme)) // this contains the external API types //+kubebuilder:scaffold:scheme -} +} ``` ## Edit the Controller `SetupWithManager` function @@ -169,7 +169,7 @@ go mod tidy ``` make manifests -``` +``` ## Prepare for testing @@ -216,7 +216,7 @@ var _ = BeforeSuite(func() { By("bootstrapping test environment") testEnv = &envtest.Environment{ CRDDirectoryPaths: []string{ - // if you are using vendoring and rely on a kubebuilder based project, you can simply rely on the vendored config directory + // if you are using vendoring and rely on a kubebuilder based project, you can simply rely on the vendored config directory filepath.Join("..", "..", "..", "vendor", "github.com", "theiruser", "theirproject", "config", "crds"), // otherwise you can simply download the CRD from any source and place it within the config/crd/bases directory, filepath.Join("..", "..", "config", "crd", "bases"), @@ -231,7 +231,7 @@ var _ = BeforeSuite(func() { BinaryAssetsDirectory: filepath.Join("..", "..", "bin", "k8s", fmt.Sprintf("1.28.3-%s-%s", runtime.GOOS, runtime.GOARCH)), } - + var err error // cfg is defined in this file globally. cfg, err = testEnv.Start() diff --git a/docs/kubebuilder_v0_v1_difference.md b/docs/kubebuilder_v0_v1_difference.md index dd8736322da..5e3cf1800f1 100644 --- a/docs/kubebuilder_v0_v1_difference.md +++ b/docs/kubebuilder_v0_v1_difference.md @@ -1,6 +1,6 @@ # Kubebuilder v0 v.s. v1 -Kubebuilder 1.0 adds a new flag `--project-version`, it accepts two different values, `v0` and `v1`. When `v0` is used, the kubebuilder behavior and workflow is the same as kubebuilder 0.*. When `v1` is specified, the generated v1 project layout is architecturally different from v0 project. v1 project uses [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) set of libraries for controller implementation and used tools under [controller-tools](https://github.com/kubernetes-sigs/controller-tools) for scaffolding and generation. +Kubebuilder 1.0 adds a new flag `--project-version`, it accepts two different values, `v0` and `v1`. When `v0` is used, the kubebuilder behavior and workflow is the same as kubebuilder 0.*. When `v1` is specified, the generated v1 project layout is architecturally different from v0 project. v1 project uses [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) set of libraries for controller implementation and used tools under [controller-tools](https://github.com/kubernetes-sigs/controller-tools) for scaffolding and generation. ## Command difference @@ -21,14 +21,14 @@ Kubebuilder 1.0 adds a new flag `--project-version`, it accepts two different va Every time the resource or controller is updated, users need to run `kubebuilder generate` to regenerate the project. - kubebuilder v1 has `init`, `create api` commands and the workflow is - + ``` kubebuilder init --domain example.com --license apache2 --owner "The Kubernetes authors" kubebuilder create api --group ship --version v1beta1 --kind Frigate make install make run ``` - + In a v1 project, there is no generate command. When the resource or controller is updated, users don't need to regenerate the project. ## Scaffolding difference @@ -37,20 +37,20 @@ Kubebuilder 1.0 adds a new flag `--project-version`, it accepts two different va - v0 project contains a directory `inject` while v1 project doesn't - v0 project layout follows predefined directory layout `pkg/apis` and `pkg/controller` while v1 project accepts user specified path - In v1 project, there is a `init()` function for every api and controller. - + ## Library difference ### Controller libraries - - v0 projects import the controller library from kubebuilder `kubebuilder/pkg/controller`. It provides a `GenericController` type with a list of functions. - + - v0 projects import the controller library from kubebuilder `kubebuilder/pkg/controller`. It provides a `GenericController` type with a list of functions. + - v1 projects import the controller libraries from controller-runtime, such as `controller-runtime/pkg/controller`, `controller-runtime/pkg/reconcile`. - + ### Client libraries - + - In v0 projects, the client libraries is generated by `kubebuilder generate` under directory `pkg/client` and imported wherever they are used in the project. - + - v1 projects import the dynamic client library from controller-runtime `controller-runtime/pkg/client`. - + ## Wiring difference -Wiring refers to the mechanics of integrating controllers to controller-manager and injecting the dependencies in them. +Wiring refers to the mechanics of integrating controllers to controller-manager and injecting the dependencies in them. - v0 projects have a `inject` package and it provides functions for adding the controller to controller-manager as well as registering CRDs. - v1 projects don't have a `inject` package, the controller is added to controller-manager by a `init` function inside add_.go file inside the controller directory. The types are registered by a `init` function inside _types.go file inside the apis directory. \ No newline at end of file diff --git a/docs/migration_guide.md b/docs/migration_guide.md index 0e59ff4421a..15de55cd227 100644 --- a/docs/migration_guide.md +++ b/docs/migration_guide.md @@ -9,7 +9,7 @@ Find project's domain name from the old project's pkg/apis/doc.go and use it to `kubebuilder init --project-version v1 --domain ` ## Create api -Find the group/version/kind names from the project's pkg/apis. The group and version names are directory names while the kind name can be found from *_types.go. Note that the kind name should be capitalized. +Find the group/version/kind names from the project's pkg/apis. The group and version names are directory names while the kind name can be found from *_types.go. Note that the kind name should be capitalized. Create api in the new project with `kubebuilder create api --group --version --kind ` diff --git a/docs/testing/e2e.md b/docs/testing/e2e.md index f4ba7840ff3..00ba8424aaa 100644 --- a/docs/testing/e2e.md +++ b/docs/testing/e2e.md @@ -13,7 +13,7 @@ import ( ...... ) -// Specify kubeconfig file +// Specify kubeconfig file func getClientConfig() (*rest.Config, error) { return clientcmd.BuildConfigFromFlags("", path.Join(os.Getenv("HOME"), "")) } @@ -46,7 +46,7 @@ var _ = Describe(" should work", func() { AfterEach(func() { // Delete all test-specific resources - ...... + ...... // Delete all environment-specific resources ...... @@ -57,7 +57,7 @@ var _ = Describe(" should work", func() { It("should do something", func() { testDoSomething(k8sClient, roClient) }) - + ...... ``` 2. Write some controller-specific e2e tests