-
Notifications
You must be signed in to change notification settings - Fork 1.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
📖 Fix outdated links in implementers guide #6166
Merged
k8s-ci-robot
merged 1 commit into
kubernetes-sigs:main
from
killianmuldoon:book/update-providers
Feb 22, 2022
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| # Provider contract | ||
killianmuldoon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 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 | ||
killianmuldoon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit, if you want (same for the file name)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think version migration is clearer and more specific here, but if there's a call to use the more generic title I'll change it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just keep it as is. Version migration just sounded strange to me, but my entire understanding of the english language is subjective :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As is mine!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I hope yours is better than mine and you correct the nits I drop on PRs of other folks if they are just too wrong :) (btw :) )