Merge pull request #6166 from killianmuldoon/book/update-providers

📖  Fix outdated links in implementers guide

Author: k8s-ci-robot

docs/book/src/SUMMARY.md

@@ -58,17 +58,20 @@
         - [Multi-tenancy](./developer/architecture/controllers/multi-tenancy.md)
         - [Support multiple instances](./developer/architecture/controllers/support-multiple-instances.md)
     - [Provider Implementers](./developer/providers/implementers.md)
-        - [v0.3 to v0.4](./developer/providers/v0.3-to-v0.4.md)
-        - [v0.4 to v1.0](./developer/providers/v0.4-to-v1.0.md)
-        - [v1.0 to v1.1](./developer/providers/v1.0-to-v1.1.md)
-        - [v1.1 to v1.2](./developer/providers/v1.1-to-v1.2.md)
-        - [Cluster Infrastructure](./developer/providers/cluster-infrastructure.md)
-        - [Machine Infrastructure](./developer/providers/machine-infrastructure.md)
-        - [Bootstrap](./developer/providers/bootstrap.md)
+        - [Version migration](./developer/providers/version-migration.md)
+          - [v0.3 to v0.4](./developer/providers/v0.3-to-v0.4.md)
+          - [v0.4 to v1.0](./developer/providers/v0.4-to-v1.0.md)
+          - [v1.0 to v1.1](./developer/providers/v1.0-to-v1.1.md)
+          - [v1.1 to v1.2](./developer/providers/v1.1-to-v1.2.md)
+        - [Provider contracts](./developer/providers/contracts.md)
+          - [Cluster Infrastructure](./developer/providers/cluster-infrastructure.md)
+          - [Machine Infrastructure](./developer/providers/machine-infrastructure.md)
+          - [Bootstrap](./developer/providers/bootstrap.md)
         - [Implementer's Guide](./developer/providers/implementers-guide/overview.md)
           - [Naming](./developer/providers/implementers-guide/naming.md)
           - [Create Repo and Generate CRDs](./developer/providers/implementers-guide/generate_crds.md)
           - [Create API](./developer/providers/implementers-guide/create_api.md)
+          - [Webhooks](./developer/providers/webhooks.md)
           - [Controllers and Reconciliation](./developer/providers/implementers-guide/controllers_and_reconciliation.md)
           - [Building, Running, Testing](./developer/providers/implementers-guide/building_running_and_testing.md)
     - [CustomResourceDefinitions relationships](./developer/crd-relationships.md)

docs/book/src/developer/providers/contracts.md

@@ -0,0 +1,36 @@
+# Provider contract
+
+Cluster API defines a contract which requires providers to implement certain fields and patterns in their CRDs and controllers. This contract is required for providers to work correctly with Cluster API.
+
+Cluster API defines the following contracts:
+
+- [Infrastructure provider contract](./cluster-infrastructure.md)
+- [Boostrap provider contract](./bootstrap.md)
+- [Control Plane provider contract](../../developer/architecture/controllers/control-plane.md#crd-contracts)
+- [Machine provider contract](./machine-infrastructure.md)
+- [clusterctl provider contract](../../clusterctl/provider-contract.md#clusterctl-provider-contract)
+- [Multi tenancy contract](../../developer/architecture/controllers/multi-tenancy.md#contract)
+
+## API version labels
+Providers MUST set `cluster.x-k8s.io/<version>` label on all Custom Resource Definitions related to Cluster API starting with v1alpha3.
+The label is a map from an API Version of Cluster API (contract) to your Custom Resource Definition versions.
+The value is a underscore-delimited (_) list of versions.
+Each value MUST point to an available version in your CRD Spec.
+
+The label allows Cluster API controllers to perform automatic conversions for object references, the controllers will pick the last available version in the list if multiple versions are found.
+To apply the label to CRDs it’s possible to use commonLabels in your kustomize.yaml file, usually in config/crd.
+
+In this example we show how to map a particular Cluster API contract version to your own CRD using Kustomize’s commonLabels feature:
+
+```yaml
+commonLabels:
+cluster.x-k8s.io/v1alpha2: v1alpha1
+cluster.x-k8s.io/v1alpha3: v1alpha2
+cluster.x-k8s.io/v1beta1:  v1beta1
+```
+
+An example of this is in the [Kubeadm Bootstrap provider](https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/controlplane/kubeadm/config/crd/kustomization.yaml).
+
+## Improving and contributing to the contract
+
+The definition of the contract between Cluster API and providers may be changed in future versions of Cluster API. The Cluster API maintainers welcome feedback and contributions to the contract in order to improve how it's defined, its clarity and visibility to provider implementers and its suitability across the different kinds of Cluster API providers. To provide feedback or open a discussion about the provider contract please [open an issue on the Cluster API](https://github.com/kubernetes-sigs/cluster-api/issues/new?assignees=&labels=&template=feature_request.md) repo or add an item to the agenda in the [Cluster API community meeting](http://git.k8s.io/community/sig-cluster-lifecycle/README.md#cluster-api).

docs/book/src/developer/providers/implementers-guide/generate_crds.md

@@ -83,10 +83,7 @@ make manifests
 
 The cluster API CRDs should be further customized:
 
-- [Apply the contract version label to support conversions](https://release-0-4.cluster-api.sigs.k8s.io/developer/providers/v1alpha2-to-v1alpha3.html#apply-the-contract-version-label-clusterx-k8sioversion-version1_version2_version3-to-your-crds)
-- [Upgrade to CRD v1](https://release-0-4.cluster-api.sigs.k8s.io/developer/providers/v1alpha2-to-v1alpha3.html#upgrade-to-crd-v1)
-- [Set “matchPolicy=Equivalent” kubebuilder marker for webhooks](https://release-0-4.cluster-api.sigs.k8s.io/developer/providers/v1alpha2-to-v1alpha3.html#add-matchpolicyequivalent-kubebuilder-marker-in-webhooks)
-- [Refactor the kustomize config folder to support multi-tenancy](https://release-0-4.cluster-api.sigs.k8s.io/developer/providers/v1alpha2-to-v1alpha3.html#refactor-kustomize-config-folder-to-support-multi-tenancy-when-using-webhooks)
+- [Apply the contract version label to support conversions](../contracts.md#api-version-labels)
 - [Ensure you are compliant with the clusterctl provider contract](../../../clusterctl/provider-contract.md#components-yaml)
 
 ### Commit your changes

docs/book/src/developer/providers/version-migration.md

@@ -0,0 +1,9 @@
+# Version migration
+
+The following pages provide an overview of relevant changes between versions of Cluster API and their direct successors. These guides are intended to assist 
+maintainers of other providers and consumers of the Go API in upgrading from one version of Cluster API to a subsequent version.
+
+- [v0.3 to v0.4](v0.3-to-v0.4.md)
+- [v0.4 to v1.0](v0.4-to-v1.0.md)
+- [v1.0 to v1.1](v1.0-to-v1.1.md)
+- [v1.1 to v1.2](v1.1-to-v1.2.md)

docs/book/src/developer/providers/webhooks.md

@@ -0,0 +1,38 @@
+# Webhooks
+
+Cluster API provides support for three kinds of webhooks: validating webhooks, defaulting webhook and conversion webhooks. 
+
+## Validating webhooks
+Validating webhooks are an implementation of a [Kubernetes validating webhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook). A validating webhook allows developers to test whether values supplied by users are valid. e.g. [the Cluster webhook] ensures the Infrastructure reference supplied at the Cluster's `.spec.infrastructureRef` is in the same namespace as the Cluster itself and rejects the object creation or update if not.
+
+## Defaulting webhooks
+Defaulting webhooks are an implementation of a [Kubernetes mutating webhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook). A defaulting webhook allows developers to set default values for a type before they are placed in the Kubernetes data store. e.g. [the Cluster webhook] will set the Infrastructure reference namespace to equal the Cluster namespace if `.spec.infrastructureRef.namespace` is empty.
+
+## Conversion webhooks
+Conversion webhooks are what allow Cluster API to work with multiple API types without requiring different versions. It does this by converting the incoming version to a `Hub` version which is used internally by the controllers. To read more about conversion see the [Kubebuilder documentation](https://book.kubebuilder.io/multiversion-tutorial/conversion.html)
+
+For a walkthrough on implementing conversion webhooks see the video in the [Developer Guide](https://cluster-api.sigs.k8s.io/developer/guide.html?highlight=video#videos-explaining-capi-architecture-and-code-walkthroughs)
+
+## Implementing webhooks with Controller Runtime and Kubebuilder
+The webhooks in Cluster API are offered through tools in Controller Runtime and Kubebuilder. The webhooks implement interfaces defined in Controller Runtime, while generation of manifests can be done using Kubebuilder.
+
+For information on how to create webhooks [refer to the Kubebuilder book](https://book.kubebuilder.io/cronjob-tutorial/webhook-implementation.html).
+
+
+Webhook manifests are generated using Kubebuilder in Cluster API. This is done by adding tags to the webhook implementation in the codebase. Below, for example, are the tags on the [the Cluster webhook]:
+
+```go
+
+// +kubebuilder:webhook:verbs=create;update;delete,path=/validate-cluster-x-k8s-io-v1beta1-cluster,mutating=false,failurePolicy=fail,matchPolicy=Equivalent,groups=cluster.x-k8s.io,resources=clusters,versions=v1beta1,name=validation.cluster.cluster.x-k8s.io,sideEffects=None,admissionReviewVersions=v1;v1beta1
+// +kubebuilder:webhook:verbs=create;update,path=/mutate-cluster-x-k8s-io-v1beta1-cluster,mutating=true,failurePolicy=fail,matchPolicy=Equivalent,groups=cluster.x-k8s.io,resources=clusters,versions=v1beta1,name=default.cluster.cluster.x-k8s.io,sideEffects=None,admissionReviewVersions=v1;v1beta1
+
+// Cluster implements a validating and defaulting webhook for Cluster.
+type Cluster struct {
+    Client client.Reader
+}
+```
+
+A detailed guide on the purpose of each of these tags is [here](https://book.kubebuilder.io/reference/markers/webhook.html).
+
+<!-- links -->
+[the Cluster webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/internal/webhooks/cluster.go