Merge pull request #79 from buraksekili/fix/stale-links

(fix): update typos in `docs/controllers`

Author: clux

docs/controllers/application.md

@@ -1,8 +1,8 @@
 # The Application
 
-The **application** is a Rust application manages a [Controller]. It needs a [[reconciler]] that will be called with entries of your chosen [[object]], and a few dependencies to deal with async streams, error handling, and upstream Kubernetes structs.
+The **application** is a Rust application that manages a [Controller]. It needs a [[reconciler]] that will be called with entries of your chosen [[object]], and a few dependencies to deal with async streams, error handling, and upstream Kubernetes structs.
 
-This document shows how to create a __minimal__ application, with the builtin `Pod` type as the main object, and a no-op reconciler.
+This document shows how to create a __minimal__ application, with the built-in `Pod` type as the main object, and a no-op reconciler.
 
 ## Requirements
 
@@ -75,7 +75,7 @@ For the purposes of this demo we will import [Pod]:
 use k8s_openapi::api::core::v1::Pod;
 ```
 
-### Seting up the controller
+### Setting up the controller
 
 This is where we will start defining our `main` and glue everything together:
 
@@ -121,7 +121,7 @@ To make this reconciler useful, we can reuse the one created in the [[reconciler
 
 ## Checkpoint
 
-If you copy-pasted everything above, and fixed imports, you should have a `main.rs` with this:
+If you copy-pasted everything above and fixed imports, you should have a `main.rs` with this:
 
 ```rust
 use std::{sync::Arc, time::Duration};
@@ -202,7 +202,7 @@ If you now edit a pod (via `kubectl edit pod traefik-xxx` and make a change), or
 
 !!! note "Where to Go From Here"
 
-    You have created the [[application]] using a trivial reconciler and a builtin object. See the [[object]] and [[reconciler]] chapters to change it into something more useful. The documents under __Concepts__ on the left navigation menu shows the core concepts that are instrumental to help create the right abstraction.
+    You have created the [[application]] using a trivial reconciler and a built-in object. See the [[object]] and [[reconciler]] chapters to change it into something more useful. The documents under __Concepts__ on the left navigation menu shows the core concepts that are instrumental to help create the right abstraction.
 
 ### Useful Dependencies
 

docs/controllers/gc.md

@@ -48,10 +48,10 @@ This is explained in more detail in [Kubernetes.io :: Finalizers](https://kubern
 
     You should mark objects with a finalizer if it needs external cleanup to run in the event it is deleted.
 
-The main way to use finalizers with controllers is to define a unique finalizer name (many controllers can finalize an object) and make the [finalizer] helper manage it. The finalizer helper is desingned to be used within a reconciler and split the work depending on the state we are in:
+The main way to use finalizers with controllers is to define a unique finalizer name (many controllers can finalize an object) and make the [finalizer] helper manage it. The finalizer helper is designed to be used within a reconciler and split the work depending on the state we are in:
 
-- have a deletion happened, and we need to cleanup? we are in the `Event::Cleanup` arm
-- no deletion has been recorded? we are in the normal `Event::Apply` arm
+- Has a deletion occurred, and do we need to clean up? If so, we are in the `Event::Cleanup` arm
+- Has no deletion been recorded? Then we are in the normal `Event::Apply` arm
 
 !!! warning "Finalizers can prevent objects from being deleted"
 
@@ -61,7 +61,7 @@ The main way to use finalizers with controllers is to define a unique finalizer
 
 In the [secret_syncer example](https://github.com/kube-rs/kube/blob/main/examples/secret_syncer.rs), the controller manages an artificially external secret resource (in reality the example puts it in Kubernetes, but please ignore that) on changes to a `ConfigMap`.
 
-Because we cannot normally watch external resources through Kubernetes watches, we have not setup any [[relations]] for the secret. Instead we use the [finalizer] helper in a reconciler (here as a lambda), and delegate to two more specific reconcilers:
+Because we cannot normally watch external resources through Kubernetes watches, we have not setup any [[relations]] for the secret. Instead, we use the [finalizer] helper in a reconciler (here as a lambda), and delegate to two more specific reconcilers:
 
 ```rust
 |cm, _| {

docs/controllers/object.md

@@ -14,7 +14,7 @@ We will outline how they interact with controllers and the basics of how to set
 
 ## Typed Resource
 
-This is the most common, and simplest case. Your source of truth is an existing [Kubernetes object found in the openapi spec](https://arnavion.github.io/k8s-openapi/v0.14.x/k8s_openapi/trait.Resource.html#implementors).
+This is the most common, and simplest case. Your source of truth is an existing [Kubernetes object found in the openapi spec](https://docs.rs/k8s-openapi/latest/k8s_openapi/trait.Resource.html#implementors).
 
 To use a typed Kubernetes resource as a source of truth in a [Controller], import it from [k8s-openapi], and create an [Api] from it, then pass it to the [Controller].
 
@@ -110,7 +110,7 @@ Here, a separate `crdgen` bin entry would install your custom resource using `ca
 
 !!! warning "CRD Installation"
 
-    Be careful with installing CRDs inside a controller at starup. It is customary to provide a generated yaml file so consumers can install a CRD out of band to better support [gitops](https://fluxcd.io/flux/components/helm/helmreleases/#crds) and [helm](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/). See [[security#crd-access]].
+    Be careful with installing CRDs inside a controller at startup. It is customary to provide a generated yaml file so consumers can install a CRD out of band to better support [gitops](https://fluxcd.io/flux/components/helm/helmreleases/#crds) and [helm](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/). See [[security#crd-access]].
 
 ### Imported Custom Resource
 
@@ -198,7 +198,7 @@ Untyped resources are using [DynamicObject]; an umbrella container for arbitrary
 
 The [DynamicObject] consists of **just the unavoidable properties** like `apiVersion`, `kind`, and `metadata`, whereas the entire spec is loaded onto an arbitrary [serde_json::Value] via [flattening].
 
-The benefits you get is that:
+The benefits you get are that:
 
 - you avoid having to write out fields manually
 - you **can** achieve tolerance against multiple versions of your object
@@ -270,7 +270,7 @@ This is functionally similar way to deriving `CustomResource` on an incomplete s
 
 !!! warning "Partial or dynamic typing always needs additional type information"
 
-    All usage of `DynamicObject` or `Object` require the use of alternate constructors for multiple interfaces such as [Api] and [Controller]. These constructors have an additional `_with` suffix to carry an associated type for the [Resource] trait.
+    All usage of `DynamicObject` or `Object` requires the use of alternate constructors for multiple interfaces such as [Api] and [Controller]. These constructors have an additional `_with` suffix to carry an associated type for the [Resource] trait.
 
 ## Summary
 

docs/controllers/reconciler.md

@@ -6,7 +6,7 @@ The reconciler is the **user-defined function** in charge of reconciling the **s
 async fn reconcile(o: Arc<K>, ctx: Arc<T>) -> Result<Action, Error>
 ```
 
-It is always **called** with the [[object]] type that you instantiate the [Controller] with, independent of what auxillary objects you may be watching:
+It is always **called** with the [[object]] type that you instantiate the [Controller] with, independent of what auxiliary objects you may be watching:
 
 ```mermaid
 graph TD
@@ -42,7 +42,7 @@ The state of the world is your main Kubernetes object along with **anything** yo
 
 !!! info "The World >= Kubernetes"
 
-    While your **main** object **must** reside **within Kubernetes**, it is possibly to manage/act on changes **outside Kubernetes**.
+    While your **main** object **must** reside **within Kubernetes**, it is possible to manage/act on changes **outside Kubernetes**.
 
 You do not have to configure the world, as any [side effect](https://en.wikipedia.org/wiki/Side_effect_(computer_science)) you perform implicitly becomes the world for your controller. It is, however, beneficial to specify any [[relations]] your object has with the world to ensure `reconcile` is correctly invoked:
 
@@ -72,7 +72,7 @@ Notice that the [ReconcileReason] is **not included** in the signature of `recon
 
 As a result, the reason is just a __best-effort property__ (that we only include for telemetry). You should not attempt to write logic against the reason in your reconciler.
 
-Instead, you must write a **defensive reconciler** and handle missed messages, and paritial runs:
+Instead, you must write a **defensive reconciler** and handle missed messages, and partial runs:
 
 - assume nothing about why reconciliation started
 - assume the reconciler could have failed at any question mark
@@ -86,7 +86,7 @@ A function is said to be **idempotent** if it can be applied multiple times with
 
 !!! warning "A reconciler must be [idempotent]"
 
-    If a reconciler is triggered twice for the same object, it must cause the same outcome. Care must be taken to ensure operations are not dependent on all-or-nothing approaches, and the flow of the reconciler must be able to recover from errors occurring in a previous reconcile runs.
+    If a reconciler is triggered twice for the same object, it must cause the same outcome. Care must be taken to ensure operations are not dependent on all-or-nothing approaches, and the flow of the reconciler must be able to recover from errors occurring in previous reconcile runs.
 
 Let us create a reconciler for a custom `PodManager` resource that will:
 
@@ -112,7 +112,7 @@ Now, what happens if the timestamp creation fails after the pod got created? The
 
     If your reconciler **errored** half-way through a run; the only way you would know **what failed**, is if you check everything.
 
-Therefore the correct way to do these two actions it to do them independently:
+Therefore the correct way to do these two actions is to do them independently:
 
 ```rust
 if pod_missing {

docs/controllers/relations.md

@@ -1,7 +1,7 @@
 
 # Related Objects
 
-A [Controller] needs to specify related resources if changes to them is meant to trigger the [[reconciler]].
+A [Controller] needs to specify related resources if changes to them are meant to trigger the [[reconciler]].
 
 These relations are generally set up with [Controller::owns], but we will go through the different variants below.
 
@@ -47,7 +47,7 @@ Controller::new(main, watcher::Config::default())
 ```
 <!-- TODO: ReconcileRequest::from sets reason to Unknow, needs a method to set reason, ReconcileReason -> controller::Reason -->
 
-In this case we are extracing an object reference from the spec of our object. Regardless of how you get the information, your mapper must return an iterator of [ObjectRef] for the root object(s) that must be reconciled as a result of the change.
+In this case, we are extracting an object reference from the spec of our object. Regardless of how you get the information, your mapper must return an iterator of [ObjectRef] for the root object(s) that must be reconciled as a result of the change.
 
 As a theoretical example; every [HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) object bundles a scale ref to the workload, so you could use this to build a Controller for `Deployment` using HPA as a watched object.
 
@@ -62,7 +62,7 @@ Free-form relations to external apis often serve to lift an external resource in
 ### External Watches
 If you want changes on an external API to cause changes in the cluster, you will need to a way to stream changes from the external api.
 
-The _change events_ must be be provided as a `Stream<Item = ObjectRef>` and passed to [Controller::reconcile_on]. As an example:
+The _change events_ must be provided as a `Stream<Item = ObjectRef>` and passed to [Controller::reconcile_on]. As an example:
 
 ```rust
 struct ExternalObject {
@@ -76,7 +76,7 @@ Controller::new(Api::<MyCr>::namespaced(client, &ns), Config::default())
     .reconcile_on(external_stream)
 ```
 
-In this case we have some opaque `fn watch_external_objects()` which here returns `-> impl Stream<Item = ExternalObject>`. It is meant to return changes from the external API. Whenever a new item is found on the stream, the controller will reconcile the matching cluster object.
+In this case, we have some opaque `fn watch_external_objects()` which here returns `-> impl Stream<Item = ExternalObject>`. It is meant to return changes from the external API. Whenever a new item is found on the stream, the controller will reconcile the matching cluster object.
 
 (The example assumes __matching names__ between the external resource and cluster resource, and a __fixed namespace__ for the cluster resources.)
 
@@ -85,7 +85,7 @@ In this case we have some opaque `fn watch_external_objects()` which here return
     If you do not have a streaming interface (like if you are doing periodic HTTP GETs), you can wrap your data in a `Stream` via either [async_stream](https://docs.rs/async-stream/latest/async_stream/) or by using channels (say [tokio::sync::mpsc](https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html), using the [Receiver](https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Receiver.html) side as a stream).
 
 ### External Writes
-If you want to populate an external API from a cluster resource, the you must update the external api from your [[reconciler]] (using the necessary client libraries for that API).
+If you want to populate an external API from a cluster resource, you must update the external api from your [[reconciler]] (using the necessary client libraries for that API).
 
 To avoid build-up of generated objects on the external side, you will want to use [[gc#finalizers]], to ensure the external resource gets _safely_ cleaned up on `kubectl delete`.
 

docs/controllers/schemas.md

@@ -100,7 +100,7 @@ See [examples/crd_derive_custom_schema](https://github.com/kube-rs/kube/blob/823
 
 ### Overriding Members
 
-When you are implementing or deriving `JsonSchema`, you can overriding specific parts of a `JsonSchema` schema using [`#[schemars(schema_with)]`](https://graham.cool/schemars/examples/7-custom_serialization/). Some specific examples:
+When you are implementing or deriving `JsonSchema`, you can override specific parts of a `JsonSchema` schema using [`#[schemars(schema_with)]`](https://graham.cool/schemars/examples/7-custom_serialization/). Some specific examples:
 
 - [overriding merge strategy on a vec](https://github.com/kube-rs/kube/blob/823f4b8db3852e6bdd271e72c56b8c40d6f962a8/examples/crd_derive_schema.rs#L85-L102)
 - [overriding x-kubernetes properties on a condition](https://github.com/kube-rs/kube/blob/823f4b8db3852e6bdd271e72c56b8c40d6f962a8/examples/crd_derive.rs#L60-L85)
@@ -114,9 +114,9 @@ When using `#[kube(schema = "disabled)]`, you are telling [[kube-derive]] not to
 
     Setting this option means the [CustomResourceDefinition] provided by [CustomResourceExt] will require modification.
 
-Any manual schemas must be attached on the generated [CustomResourceDefinition] before use. An example of this can be found in [examples/crd_derive_no_schema](https://github.com/kube-rs/kube/blob/main/examples/crd_derive_no_schema.rs).
+Any manual schemas must be attached to the generated [CustomResourceDefinition] before use. An example of this can be found in [examples/crd_derive_no_schema](https://github.com/kube-rs/kube/blob/main/examples/crd_derive_no_schema.rs).
 
-The main reason for going down this approach is if you are porting a controller with a CRD from another language and you want to 100% conformance to the existing schema out of the gate.
+The main reason for going down this approach is if you are porting a controller with a CRD from another language and you want 100% conformance to the existing schema out of the gate.
 
 This method allows eliding the `#[derive(JsonSchema)]` instruction, and possibly also `schemars` from the dependency tree if you are careful with features.
 
@@ -138,7 +138,7 @@ This approach will let you use the [1.25 Common Expression Language feature](htt
 There are currently no recommended ways of doing client-side validation with this approach, but there are new [cel parser/interpreter crates](https://crates.io/search?q=cel) and a [cel expression playground](https://playcel.undistro.io/) that might be useful here.
 
 ### Deriving via Garde
-Using [garde] is a nice for the simple case because it allows doing both client-side validation, and server-side validation, with the caveat that it only works on both sides for **basic validation rules** as [schemars can only pick up on some of them](https://graham.cool/schemars/deriving/attributes/#supported-validator-attributes).
+Using [garde] is nice for the simple case because it allows doing both client-side validation, and server-side validation, with the caveat that it only works on both sides for **basic validation rules** as [schemars can only pick up on some of them](https://graham.cool/schemars/deriving/attributes/#supported-validator-attributes).
 
 See [CustomResource#schema-validation](https://docs.rs/kube/latest/kube/derive.CustomResource.html#schema-validation).