diff --git a/designs/code-generate-image-plugin.md b/designs/code-generate-image-plugin.md index 6dbf78b7d52..9c512e9d050 100644 --- a/designs/code-generate-image-plugin.md +++ b/designs/code-generate-image-plugin.md @@ -6,7 +6,7 @@ ## Summary -This proposal defines a new plugin which allow users get the scaffold with the +This proposal defines a new plugin that allows users to 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 @@ -18,24 +18,24 @@ The biggest part of the Kubebuilder users looking for to create a project that w ### Goals - 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. +- Promote the best practices by giving examples of common implementations +- Make the process of developing operator's projects easier and more agile. - 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 +- Provide examples of code implementations and of the usage of the most common features 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 to 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; scaffolding the project using webhooks and the controller covered by tests. ## Proposal -Add the new plugin code generate which will scaffold code implementation to deploy the image informed which would like such as; `kubebuilder create api --group=crew --version=v1 --image=myexample:0.0.1 --kind=App --plugins=deploy-image.go.kubebuilder.io/v1beta1` which will: +Add the new plugin code generated which will scaffold code implementation to deploy the image informed which would like such as; `kubebuilder create api --group=crew --version=v1 --image=myexample:0.0.1 --kind=App --plugins=deploy-image.go.kubebuilder.io/v1beta1` which will: -- Add a code implementation which will do the Custom Resource reconciliation and create a Deployment resource for the `--image`; +- Add a code implementation that will do the Custom Resource reconciliation and create a Deployment resource for the `--image`; -- Add an EnvVar on the manager manifest (`config/manager/manager.yaml`) which will store the image informed and shows its possibility to users: +- Add an EnvVar on the manager manifest (`config/manager/manager.yaml`) which will store the image informed and show its possibility to users: ```yaml .. @@ -49,7 +49,7 @@ Add the new plugin code generate which will scaffold code implementation to depl ... ``` -- Add a check into reconcile to ensure that the replicas of the deployment on cluster are equals the size defined in the CR: +- Add a check into reconcile to ensure that the replicas of the deployment on the cluster are equal the size defined in the CR: ```go // Ensure the deployment size is the same as the spec @@ -83,7 +83,7 @@ func (r *{{ resource }}Reconciler) SetupWithManager(mgr ctrl.Manager) error { // +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete ``` -- A status [conditions][conditions] to allow users check that if the deployment occurred successfully or its errors +- A status [conditions][conditions] to allow users to check if the deployment occurred successfully or if its errors - Add a [marker][markers] in the spec definition to demonstrate how to use OpenAPI schemas validation such as `+kubebuilder:validation:Minimum=1` @@ -93,9 +93,9 @@ func (r *{{ resource }}Reconciler) SetupWithManager(mgr ctrl.Manager) error { ### 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 a user, who would like to use a command to scaffold my common need which is to 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 a user, would like to have a good example code base that uses the common features so that I can easily learn its concepts and have a good starting 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. @@ -251,12 +251,12 @@ type {{ resource }}Spec struct { ### Test Plan -To ensure this implementation a new project example should be generated in the [testdata](../testdata/) directory of the project. See the [test/testdata/generate.sh](../test/testadata/generate.sh). Also, we should use this scaffold in the [integration tests](../test/e2e/) to ensure that the data scaffolded with works on the cluster as expected. +To ensure this implementation a new project example should be generated in the [testdata](../testdata/) directory of the project. See the [test/testdata/generate.sh](../test/testadata/generate.sh). Also, we should use this scaffold in the [integration tests](../test/e2e/) to ensure that the data scaffold works on the cluster as expected. ### 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 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 gets done with the common basic code implementation: ```yaml plugins: @@ -279,22 +279,22 @@ 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? +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.` -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` +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 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 creating 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 does not have too many plugins yet. And then, the preliminary support for plugins was not indeed released. 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. 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) +The [Extensible CLI and Scaffolding Plugins - Phase 1.5](extensible-cli-and-scaffolding-plugins-phase-1-5.md) and issue #1941 are required to be implemented before this proposal. Also, to have a better idea of 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 [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 +[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md diff --git a/docs/book/src/cronjob-tutorial/gvks.md b/docs/book/src/cronjob-tutorial/gvks.md index 68ef756a63a..93fe17976b1 100644 --- a/docs/book/src/cronjob-tutorial/gvks.md +++ b/docs/book/src/cronjob-tutorial/gvks.md @@ -1,6 +1,6 @@ # Groups and Versions and Kinds, oh my! -Actually, before we get started with our API, we should talk terminology +Before we get started with our API, we should talk about terminology a bit. When we talk about APIs in Kubernetes, we often use 4 terms: *groups*, @@ -38,7 +38,7 @@ lowercase form of the Kind. ## So, how does that correspond to Go? -When we refer to a kind in a particular group-version, we'll call it +When we refer to a kind in a particular group version, we'll call it a *GroupVersionKind*, or GVK for short. Same with resources and GVR. As we'll see shortly, each GVK corresponds to a given root Go type in a package. @@ -51,7 +51,7 @@ API! In the next section, [Adding a new API](../cronjob-tutorial/new-api.html), we will check how the tool helps us to create our own APIs with the command `kubebuilder create api`. -The goal of this command is to create Custom Resource (CR) and Custom Resource Definition (CRD) for our Kind(s). To check it further see; [Extend the Kubernetes API with CustomResourceDefinitions][kubernetes-extend-api]. +The goal of this command is to create a Custom Resource (CR) and Custom Resource Definition (CRD) for our Kind(s). To check it further see; [Extend the Kubernetes API with CustomResourceDefinitions][kubernetes-extend-api]. ## But, why create APIs at all? @@ -87,7 +87,7 @@ API server that says } ``` -or properly look up the group-version when we go to submit a `&CronJob{}` +or properly look up the group version when we go to submit a `&CronJob{}` in an update. [kubernetes-extend-api]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/ diff --git a/docs/kubebuilder_annotation.md b/docs/kubebuilder_annotation.md index bd037d17cd6..785e6e7fbf8 100644 --- a/docs/kubebuilder_annotation.md +++ b/docs/kubebuilder_annotation.md @@ -1,20 +1,20 @@ # Kubebuilder Annotation -If you have been using Kubebuilder, you must have seen comments such as `// +kubebuilder:rbac: ....` , `// +kubebuilder:resource:...` in scaffolder Go files. These special comments are used by kubebuilder tools (controller-tools) to generate CRD, RBAC, webhook manifests. In kubebuilder, these special comments are `Kubebuilder Annotation`, a.k.a `annotation`. It is designed for this kind of use case: To use kubebuilder tools, all you have to do is focus on writing your code, and put instructions with parameters as annotations along with your code, so that everything will be handled based on these annotations instructions by kubebuilder. This document illustrates the syntax of these annotations. +If you have been using Kubebuilder, you must have seen comments such as `// +kubebuilder:rbac: ....` , `// +kubebuilder:resource:...` in the scaffolder Go files. These special comments are used by kubebuilder tools (controller tools) to generate CRD, RBAC, and webhook manifests. In kubebuilder, these special comments are `Kubebuilder Annotation`, a.k.a `annotation`. It is designed for this kind of use case: To use kubebuilder tools, all you have to do is focus on writing your code, and put instructions with parameters as annotations along with your code, so that everything will be handled based on these annotations instructions by kubebuilder. This document illustrates the syntax of these annotations. ## Kubebuilder Annotation Syntax -Kubebuilder Annotation has a series of tokens separated by colons into groups from left to right. Each **Token** is a string identifier in an annotation instance. It has meaning by its position in token slice, in the form of +Kubebuilder Annotation has a series of tokens separated by colons into groups from left to right. Each **Token** is a string identifier in an annotation instance. It has meaning by its position in a token slice, in the form of **+[header]:[module]:[submodule]:[key-value elements]** Go Annotation starts with `+` (e.g. `// +kubebuilder`) to differentiate from regular go comments. ## Token types -- **header** is the identifier of a group of annotations. It helps user know which project provides this annotation. For example, in Kubernetes project, headers like `kubebuilder`, `k8s`, `genclient`, etc. are all project identifiers. A header is required for all annotations, since you may use multiple annotations from different projects in the same codebase. +- **header** is the identifier of a group of annotations. It helps the user know which project provides this annotation. For example, in the Kubernetes project, headers like `kubebuilder`, `k8s`, `genclient`, etc. are all project identifiers. A header is required for all annotations, since you may use multiple annotations from different projects in the same codebase. -- **module** is the identifier of functional module in an annotation. An annotation may have a group of modules, each of which performs a particular function. +- **module** is the identifier of a functional module in an annotation. An annotation may have a group of modules, each of which performs a particular function. -- **submodule** (optional) In some cases, the module has a big functional scope, split into fine-grained sub modules, which provide the flexibility of extending module functionality. For example: **module:submodule1:submodule2:submodule3** submodule can be multiple following one by one. +- **submodule** (optional) In some cases, the module has a big functional scope, split into fine-grained sub-modules, which provide the flexibility of extending module functionality. For example: **module:submodule1:submodule2:submodule3** submodule can be multiple following one by one. ## Levels of symbols @@ -26,7 +26,7 @@ Delimiter symbols are distinguished to work in different levels from top-down fo - **Comma** - Comma `,` is the 2nd level delimiter (to annotation) for splitting key-value pairs in **key-value elements** which is normally the last token in annotation. e.g. `+kubebuilder:printcolumn:name=,type=,description=,JSONPath:<.spec.Name>,priority=,format=` It works within token which is the 2nd level of annotation, so it is called "2nd level delimiter" + Comma `,` is the 2nd level delimiter (to annotation) for splitting key-value pairs in **key-value elements** which is normally the last token in the annotation. e.g. `+kubebuilder:printcolumn:name=,type=,description=,JSONPath:<.spec.Name>,priority=,format=` It works within token which is the 2nd level of annotation, so it is called "2nd level delimiter" - **Equal sign** @@ -57,17 +57,17 @@ Delimiter symbols are distinguished to work in different levels from top-down fo **Notes:** 1. Separate two `submodule` (categories) under `webhook`: 1) `admission`and 2) `serveroption`, handling webhookTags and serverTags separately. -2. For each submodule, all key-values should put in the same comment line. -3. using `|` for splitting key-value of `lables` +2. For each submodule, all key values should put in the same comment line. +3. using `|` for splitting key value of `lables` #### RBAC Annotation examples **[header]** is `kubebuilder` **[module]** is `rbac` -No submodule at this moment, support annotations like : `// +rbac`, `// +kubebuilder:rbac` +No submodule at this moment, support annotations like: `// +rbac`, `// +kubebuilder:rbac` ```golang // +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;delete // +rbac:groups=apps,resources=deployments,verbs=get;list;watch;delete -``` \ No newline at end of file +``` diff --git a/docs/kubebuilder_v0_v1_difference.md b/docs/kubebuilder_v0_v1_difference.md index 5e3cf1800f1..896f411d44b 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 are 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 @@ -35,7 +35,7 @@ Kubebuilder 1.0 adds a new flag `--project-version`, it accepts two different va - v0 project contains a directory `pkg/client` while v1 project doesn't - 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 +- 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 @@ -51,6 +51,6 @@ Kubebuilder 1.0 adds a new flag `--project-version`, it accepts two different va - 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. - - 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 +Wiring refers to the mechanics of integrating controllers into controller-managers and injecting the dependencies in them. + - v0 projects have an `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 an `init` function inside _types.go file inside the apis directory. diff --git a/docs/migration_guide.md b/docs/migration_guide.md index 15de55cd227..b33450fcf8f 100644 --- a/docs/migration_guide.md +++ b/docs/migration_guide.md @@ -5,7 +5,7 @@ This document describes how to migrate a project created by kubebuilder v0 to a The recommended way of migrating a v0 project to a v1 project is to create a new v1 project and copy/modify the code from v0 project to it. ## Init a v1 project -Find project's domain name from the old project's pkg/apis/doc.go and use it to initiate a new project with +Find the project's domain name from the old project's pkg/apis/doc.go and use it to initiate a new project with `kubebuilder init --project-version v1 --domain ` ## Create api @@ -18,7 +18,7 @@ If there are several resources in the old project, repeat the `kubebuilder creat ## Copy types.go Copy the content of `_types.go` from the old project into the file `_types.go` in the new project. -Note that in the v1 project, there is a section containing `List` and `init` function. Please keep this section. +Note that in the v1 project, there is a section containing `List` and `init` functions. Please keep this section. ``` // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object // +genclient:nonNamespaced @@ -90,7 +90,7 @@ err = r.Client.List(context.TODO(), &client.ListOptions{LabelSelector: labelSele ### update add function -In a v0 project controller file, there is a `ProvideController` function creating a controller and adding some watches. In v1 projects, the corresponding function is `add`. For this part, you don't need to copy any code from v0 project to v1 project. You need to add some watchers in v1 project's `add` function based on what `watch` functions are called in v0 project's `ProvideController` function. +In a v0 project controller file, there is a `ProvideController` function creating a controller and adding some watches. In v1 projects, the corresponding function is `add`. For this part, you don't need to copy any code from the v0 project to v1 project. You need to add some watchers in the v1 project's `add` function based on what `watch` functions are called in the v0 project's `ProvideController` function. Here are several examples: @@ -112,14 +112,14 @@ c.Watch(&source.Kind{Type: &appsv1.Deployment{}}, &handler.EnqueueRequestForOwne ``` ### copy other functions -If `reconcile` function depends on some other user defined functions, copy those function as well into the v1 project. +If the `reconcile` function depends on some other user-defined functions, copy those functions as well into the v1 project. ## Copy user libraries -If there are some user defined libraries in the old project, make sure to copy them as well into the new project. +If there are some user-defined libraries in the old project, make sure to copy them as well into the new project. ## Update dependency -Open the Gopkg.toml file in the old project and find if there is user defined dependency in this block: +Open the Gopkg.toml file in the old project and find if there is user-defined dependency in this block: ``` # Users add deps lines here @@ -139,8 +139,8 @@ Copy those dependencies into the new project's Gopkg.toml file **before** the li ``` ## Copy other user files -If there are other user created files in the old project, such as any build scripts, README.md files. Copy those files into the new project. +If there are other user-created files in the old project, such as any build scripts, or README.md files. Copy those files into the new project. ## Confirmation -Run `make` to make sure the new project can build and pass all the tests. +Run `make` to make sure the new project can be built and pass all the tests. Run `make install` and `make run` to make sure the api and controller work well on cluster.