From d8c8f4d2aa28ed13da1e252741e3e86cec48fa01 Mon Sep 17 00:00:00 2001 From: semihbkgr Date: Tue, 12 Sep 2023 15:44:50 +0300 Subject: [PATCH] improvements and fixes in the documentation --- docs/README.md | 2 +- docs/book/src/faq.md | 2 +- docs/book/src/introduction.md | 4 ++-- docs/book/src/quick-start.md | 4 ++-- docs/book/src/reference/good-practices.md | 13 ++++++++----- docs/book/src/reference/raising-events.md | 7 +++++++ .../watching-resources/operator-managed.md | 3 ++- 7 files changed, 23 insertions(+), 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index 63c3996b1a5..ec9980fda5a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,7 @@ The kubebuilder book is served using [mdBook](https://github.com/rust-lang-nurse 1. Follow the instructions at [https://github.com/rust-lang-nursery/mdBook#installation](https://github.com/rust-lang-nursery/mdBook#installation) to install mdBook. -2. Make sure [controller-gen](https://pkg.go.dev/sigs.k8s.io/controller-tools/cmd/controller-gen) is install in `$GOPATH`. +2. Make sure [controller-gen](https://pkg.go.dev/sigs.k8s.io/controller-tools/cmd/controller-gen) is installed in `$GOPATH`. 3. cd into the `docs/book` directory 4. Run `mdbook serve` 5. Visit [http://localhost:3000](http://localhost:3000) diff --git a/docs/book/src/faq.md b/docs/book/src/faq.md index 0e8aa54c296..517a5a0d69b 100644 --- a/docs/book/src/faq.md +++ b/docs/book/src/faq.md @@ -55,7 +55,7 @@ environment variables to only add this option for development purposes, such as: ```go leaderElectionNS := "" - if os.Getenv("ENABLE_LEADER_ELECATION_NAMESPACE") != "false" { + if os.Getenv("ENABLE_LEADER_ELECTION_NAMESPACE") != "false" { leaderElectionNS = "-system" } diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md index 4db659d5f42..b245e8fa1f1 100644 --- a/docs/book/src/introduction.md +++ b/docs/book/src/introduction.md @@ -51,8 +51,8 @@ common tooling to manage the objects. Building services as Kubernetes APIs provides many advantages to plain old REST, including: * Hosted API endpoints, storage, and validation. -* Rich tooling and clis such as `kubectl` and `kustomize`. -* Support for Authn and granular Authz. +* Rich tooling and CLIs such as `kubectl` and `kustomize`. +* Support for AuthN and granular AuthZ. * Support for API evolution through API versioning and conversion. * Facilitation of adaptive / self-healing APIs that continuously respond to changes in the system state without user intervention. diff --git a/docs/book/src/quick-start.md b/docs/book/src/quick-start.md index 3b01a0b032b..e1cc22c8dbe 100644 --- a/docs/book/src/quick-start.md +++ b/docs/book/src/quick-start.md @@ -21,7 +21,7 @@ Projects created by Kubebuilder contain a Makefile that will install tools at ve - [kustomize](https://github.com/kubernetes-sigs/kustomize) - [controller-gen](https://github.com/kubernetes-sigs/controller-tools) -The versions which are defined in the `Makefile` and `go.mod` files are the versions tested and therefore is recommend to use the specified versions. +The versions which are defined in the `Makefile` and `go.mod` files are the versions tested and therefore is recommended to use the specified versions. @@ -91,7 +91,7 @@ and the `internal/controllers/guestbook_controller.go` where the reconciliation logic. For more info see [Designing an API](/cronjob-tutorial/api-design.md) and [What's in a Controller](cronjob-tutorial/controller-overview.md). -If you are editing the API definitions, generate the manifests such as Custom Resources (CRs) or Custom Resource Defintions (CRDs) using +If you are editing the API definitions, generate the manifests such as Custom Resources (CRs) or Custom Resource Definitions (CRDs) using ```bash make manifests ``` diff --git a/docs/book/src/reference/good-practices.md b/docs/book/src/reference/good-practices.md index eb7cedd802c..08def0b8128 100644 --- a/docs/book/src/reference/good-practices.md +++ b/docs/book/src/reference/good-practices.md @@ -18,9 +18,9 @@ Building your operator commonly involves extending the Kubernetes API itself. It Additionally, we recommend checking the documentation on [Operator patterns][operator-pattern] from Kubernetes to better understand the purpose of the standard solutions built with KubeBuilder. -## Why you should adhere to the k8s API conventions and standards +## Why you should adhere to the Kubernetes API conventions and standards -Embracing the [Kubernetes API conventions and standards][k8s-api-convetions] is crucial for maximizing the potential of your applications and deployments. By adhering to these established practices, you can benefit in several ways. +Embracing the [Kubernetes API conventions and standards][k8s-api-conventions] is crucial for maximizing the potential of your applications and deployments. By adhering to these established practices, you can benefit in several ways. Firstly, adherence ensures seamless interoperability within the Kubernetes ecosystem. Following conventions allows your applications to work harmoniously with other components, reducing compatibility issues and promoting a consistent user experience. @@ -57,7 +57,7 @@ These challenges underline the importance of assigning each controller the singl ## Why You Should Adopt Status Conditions -We recommend you manage your solutions using Status Conditionals following the [K8s Api conventions][k8s-aoi-convetions] because: +We recommend you manage your solutions using Status Conditionals following the [K8s Api conventions][k8s-api-conventions] because: - **Standardization**: Conditions provide a standardized way to represent the state of an Operator's custom resources, making it easier for users and tools to understand and interpret the resource's status. - **Readability**: Conditions can clearly express complex states by using a combination of multiple conditions, making it easier for users to understand the current state and progress of the resource. @@ -75,10 +75,13 @@ Therefore, you can check an example of Status Conditional usage by looking at it -[docs]: ./cronjob-tutorial/gvks.html +[docs]: /cronjob-tutorial/gvks.html [operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ [controllers]: https://kubernetes.io/docs/concepts/architecture/controller/ [controller-runtime-topic]: https://github.com/kubernetes-sigs/controller-runtime/blob/main/FAQ.md#q-how-do-i-have-different-logic-in-my-reconciler-for-different-types-of-events-eg-create-update-delete [controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime -[deploy-image]: ./plugins/deploy-image-plugin-v1-alpha.md +[deploy-image]: /plugins/deploy-image-plugin-v1-alpha.md [controller-runtime-manager]: https://github.com/kubernetes-sigs/controller-runtime/blob/304027bcbe4b3f6d582180aec5759eb4db3f17fd/pkg/manager/manager.go#L53 +[k8s-api-conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md +[k8s-control-loop]: https://kubernetes.io/docs/concepts/architecture/controller/ +[k8s-operator-pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ diff --git a/docs/book/src/reference/raising-events.md b/docs/book/src/reference/raising-events.md index 5633d43352a..7e22c5d4862 100644 --- a/docs/book/src/reference/raising-events.md +++ b/docs/book/src/reference/raising-events.md @@ -75,9 +75,13 @@ type MyKindReconciler struct { // See that we added the following code to allow us to pass the record.EventRecorder Recorder record.EventRecorder } +``` + ### Passing the EventRecorder to the Controller + Events are published from a Controller using an [EventRecorder]`type CorrelatorOptions struct`, which can be created for a Controller by calling `GetRecorder(name string)` on a Manager. See that we will change the implementation scaffolded in `cmd/main.go`: + ```go if err = (&controller.MyKindReconciler{ Client: mgr.GetClient(), @@ -89,15 +93,18 @@ which can be created for a Controller by calling `GetRecorder(name string)` on a os.Exit(1) } ``` + ### Granting the required permissions You must also grant the RBAC rules permissions to allow your project to create Events. Therefore, ensure that you add the [RBAC][rbac-markers] into your controller: + ```go ... //+kubebuilder:rbac:groups=core,resources=events,verbs=create;patch ... func (r *MyKindReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { ``` + And then, run `$ make manifests` to update the rules under `config/rbac/rule.yaml`. [Events]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#events diff --git a/docs/book/src/reference/watching-resources/operator-managed.md b/docs/book/src/reference/watching-resources/operator-managed.md index 3c4c69a86b2..6853ade2dba 100644 --- a/docs/book/src/reference/watching-resources/operator-managed.md +++ b/docs/book/src/reference/watching-resources/operator-managed.md @@ -10,10 +10,11 @@ Managing dependency resources is fundamental to a controller, and it's not possi - ReplicaSets must know when their Pods are deleted, or change from healthy to unhealthy. Through the `Owns()` functionality, Controller Runtime provides an easy way to watch dependency resources for changes. +A resource can be defined as dependent on another resource through the 'ownerReferences' field. As an example, we are going to create a `SimpleDeployment` resource. The `SimpleDeployment`'s purpose is to manage a `Deployment` that users can change certain aspects of, through the `SimpleDeployment` Spec. -The `SimpleDeployment` controller's purpose is to make sure that it's owned `Deployment` always uses the settings provided by the user. +The `SimpleDeployment` controller's purpose is to make sure that it's owned `Deployment` (has an ownerReference which points to `SimpleDeployment` resource) always uses the settings provided by the user. ### Provide basic templating in the `Spec`