From dcb625e592e814a3afb829c9ff1ddfd6b7609d23 Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Thu, 6 Feb 2020 22:04:30 +0100 Subject: [PATCH 1/3] clusterctl more docs --- docs/book/src/clusterctl/commands/adopt.md | 12 ++- .../src/clusterctl/commands/config-cluster.md | 94 +++++++++++++++++++ docs/book/src/clusterctl/commands/move.md | 26 +++++ docs/book/src/clusterctl/commands/upgrade.md | 75 ++++++++++++++- docs/book/src/clusterctl/configuration.md | 2 + docs/book/src/clusterctl/overview.md | 15 ++- docs/book/src/clusterctl/provider-contract.md | 21 +++++ 7 files changed, 234 insertions(+), 11 deletions(-) diff --git a/docs/book/src/clusterctl/commands/adopt.md b/docs/book/src/clusterctl/commands/adopt.md index 43d96ad4ca49..0d4e10cef081 100644 --- a/docs/book/src/clusterctl/commands/adopt.md +++ b/docs/book/src/clusterctl/commands/adopt.md @@ -1,11 +1,19 @@ # clusterctl adopt -## Pre-requisites +The `clusterctl adopt` command is designed for allowing users to start using clusterctl on management clusters originally +created by installing providers with `kubectl apply ` instead of `clusterctl init`. + +The adoption process must be repeated for each provider installed in the cluster, thus allowing clusterctl to re-create +the providers inventory as described in the `clusterctl init` [documentation](init.md#additional-information). -### Labels +## Pre-requisites In order for `clusterctl adopt` to work, ensure the components are correctly labeled. Please see the [provider contract labels][provider-contract-labels] for reference. [provider-contract-labels]: ../provider-contract.md#labels + +## Adopting a provider + +TODO \ No newline at end of file diff --git a/docs/book/src/clusterctl/commands/config-cluster.md b/docs/book/src/clusterctl/commands/config-cluster.md index f15445d0d43c..46ae47a8ae7a 100644 --- a/docs/book/src/clusterctl/commands/config-cluster.md +++ b/docs/book/src/clusterctl/commands/config-cluster.md @@ -1 +1,95 @@ # clusterctl config cluster + +The `clusterctl config cluster` command returns a YAML template for creating a workload cluster. + +For example + +``` +clusterctl config cluster my-cluster --kubernetes-version v1.16.3 > my-cluster.yaml +``` + +Creates a YAML file named `my-cluster.yaml` with a predefined list of Cluster API objects; Cluster, Machines, +Machine Deployments, etc. to be deployed in the current namespace (in case, use the `--target-namespace` flag to +specify a different target namespace). + +Then, the file can be modified using your editor of choice; when ready, run the following command +to apply the cluster manifest. + +``` +kubectl apply -f my-cluster.yaml +``` + +### Selecting the infrastructure provider to use + +The `clusterctl config cluster` command uses smart defaults in order to simplify the user experience; in the example above, +it detects that there is only an `aws` infrastructure provider in the current management cluster and so it automatically +selects a cluster template from the `aws` provider's repository. + +In case there is more than one infrastructure provider, the following syntax can be used to select which infrastructure +provider to use for the workload cluster: + +``` +clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ + --infrastructure:aws > my-cluster.yaml +``` + +or + +``` +clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ + --infrastructure:aws:v0.4.1 > my-cluster.yaml +``` + +### Flavors + +The infrastructure provider authors can provide different type of cluster templates, or flavors; use the `--flavor` flag +to specify which flavor to use; e.g. + +``` +clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ + --flavor high-availabilty > my-cluster.yaml +``` + +Please refer to the providers documentation for more info about available flavors. + +### Alternative source for cluster templates + +clusterctl uses the provider's repository as a primary source for cluster templates; the following alternative sources +for cluster templates can be used as well: + +#### ConfigMaps + +Use the `--from-config-map` flag to read cluster templates stored in a Kubernetes ConfigMap; e.g. + +``` +clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ + --from-config-map my-templates > my-cluster.yaml +``` + +#### GitHub or local file system folder + +Use the `--from` flag to read cluster templates stored in a GitHub repository or in a local file system folder; e.g. + +``` +clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ + --from https://github.com/my-org/my-repository/blob/master/my-template.yaml > my-cluster.yaml +``` + +or + +``` +clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ + --from ~/my-template.yaml > my-cluster.yaml +``` + +### Variables + +If the selected cluster template expects some environment variables, user should ensure those variables are set in advance. + +e.g. if the `AWS_CREDENTIALS` variable is expected for a cluster template targeting the `aws` infrastructure, you +should ensure the corresponding environment variable to be set before executing `clusterctl config cluster`. + +Please refer to the providers documentation for more info about the required variables or use the +`clusterctl config cluster --list-variables` flag to get a list of variables names required by a cluster template. + +The [clusterctl configuration](configuration.md) file can be used as alternative to environment variables. diff --git a/docs/book/src/clusterctl/commands/move.md b/docs/book/src/clusterctl/commands/move.md index 2dc65872a1d3..39e5ec5b8331 100644 --- a/docs/book/src/clusterctl/commands/move.md +++ b/docs/book/src/clusterctl/commands/move.md @@ -35,3 +35,29 @@ The `Cluster` object created in the target management cluster instead will be ac process completes. + +## Pivot + +Pivoting is a process for moving the provider components and declared Cluster API resources from a source management +cluster to a target management cluster. + +This can now achieved with the following procedure: + +1. Use `clusterctl init` to install the provider components into the target management cluster +2. Use `clusterctl move` to move the cluster-api resources from a Source Management cluster to a Target Management cluster + +## Bootstrap & Pivot + +The pivot process can be bounded with the creation of a temporary bootstrap cluster +used to provision a target Management cluster. + +This can now achieved with the following procedure: + +1. Create a temporary bootstrap cluster, e.g. using Kind or Minikube +2. Use `clusterctl init` to install the provider components +3. Use `clusterctl config cluster ... | kubectl apply -f -` to provision a target management cluster +4. Wait for the target management cluster to be up and running +5. Get the kubeconfig for the new target management cluster +6. Use `clusterctl init` with the new cluster's kubeconfig to install the provider components +7. Use `clusterctl move` to move the Cluster API resources from the bootstrap cluster to the target management cluster +8. Delete the bootstrap cluster \ No newline at end of file diff --git a/docs/book/src/clusterctl/commands/upgrade.md b/docs/book/src/clusterctl/commands/upgrade.md index ca0fe9494696..eb879a36e3da 100644 --- a/docs/book/src/clusterctl/commands/upgrade.md +++ b/docs/book/src/clusterctl/commands/upgrade.md @@ -1 +1,74 @@ -# clusterctl +# clusterctl upgrade + +The `clusterctl upgrade` command can be used to upgrade the version of the Cluster API providers (CRDs, controllers) +installed into a management cluster. + +## Background info: management groups + +The upgrade procedure is designed to ensure all the provider in a *management group* will be using the same +Cluster API - API version. + +A management group is a group of providers composed by a CoreProvider and a set of Bootstrap/ControlPlane/Infrastructure +providers watching objects in the same namespace. + +Usually, in a management cluster there is only a management group, but in case of [n-core multi tenancy](init.md#multi-tenancy) +there can be more than one. + +# upgrade plan + +The `clusterctl upgrade plan` command can be used to identify possible targets for upgrades. + + +```shell +clusterctl upgrade plan +``` + +Produces an output similar to this: + +```shell +Checking new release availability... + +Management group: capi-system/cluster-api, latest release available for the v1alpha3 Cluster API version: + +NAME NAMESPACE TYPE CURRENT VERSION TARGET VERSION +kubeadm-bootstrap capi-kubeadm-bootstrap-system BootstrapProvider v0.3.0 v0.3.1 +cluster-api capi-system CoreProvider v0.3.0 v0.3.1 +docker capd-system InfrastructureProvider v0.3.0 v0.3.1 + + +You can now apply the upgrade by executing the following command: + + upgrade apply --management-group capi-system/cluster-api --cluster-api-version v1alpha3 +``` + +The output contains the latest release available for each management group in the cluster/for each Cluster API / API version +available at the moment. + +# upgrade apply + +After choosing the desired option for the upgrade, you can run the provided command. + +```shell +upgrade apply --management-group capi-system/cluster-api --cluster-api-version v1alpha3 +``` + +The upgrade process is composed by two steps: + +* Delete the current version of the provider components, while preserving the namespace where the provider components + are hosted and the provider's CRDs. +* Install the new version of the provider components. + +Please note that clusterctl does not upgrade Cluster API objects (Clusters, MachineDeployments, Machine etc.); upgrading +such objects are the responsibility of the provider's controllers. + + + diff --git a/docs/book/src/clusterctl/configuration.md b/docs/book/src/clusterctl/configuration.md index 461e48e25cd6..4508edacbec8 100644 --- a/docs/book/src/clusterctl/configuration.md +++ b/docs/book/src/clusterctl/configuration.md @@ -29,6 +29,8 @@ providers: type: "CoreProvider" ``` +See [provider contract](provider-contract.md) for instructions about how to set up a provider repository. + ## Variables When installing a provider `clusterctl` reads a YAML file that is published in the provider repository; while executing diff --git a/docs/book/src/clusterctl/overview.md b/docs/book/src/clusterctl/overview.md index da598f7221a3..2492746f70ce 100644 --- a/docs/book/src/clusterctl/overview.md +++ b/docs/book/src/clusterctl/overview.md @@ -56,7 +56,7 @@ See the [Minikube documentation](https://minikube.sigs.k8s.io/) for more details {{#/tab }} {{#tab Production}} -{{#tabs name:"tab-create-production-cluster" tabs:"Pre-Existing cluster,Pivot"}} +{{#tabs name:"tab-create-production-cluster" tabs:"Pre-Existing cluster"}} {{#tab Pre-Existing cluster}} For production use-cases a "real" kubernetes cluster should be used with appropriate backup and DR policies and procedures in place. @@ -64,13 +64,6 @@ For production use-cases a "real" kubernetes cluster should be used with appropr ```bash export KUBECONFIG=<...> ``` -{{#/tab }} -{{#tab Pivot}} - -- Create a bootstrap management cluster with kind/Minikube -- Use `clusterctl init` and `clusterctl config cluster` to create a production cluster (see below) -- "Pivot" the bootstrap management cluster into the production management cluster - {{#/tab }} {{#/tabs }} @@ -224,6 +217,9 @@ it detects that there is only an `aws` infrastructure provider and so it uses th The `clusterctl config cluster` uses cluster templates which are provided by the infrastructure providers. See the provider's documentation for more information. +See [`clusterctl config cluster`](commands/config-cluster.md) for details about how to use alternative sources +for cluster templates. + For example diff --git a/docs/book/src/clusterctl/provider-contract.md b/docs/book/src/clusterctl/provider-contract.md index 4ab71653db0a..15c3814abcab 100644 --- a/docs/book/src/clusterctl/provider-contract.md +++ b/docs/book/src/clusterctl/provider-contract.md @@ -34,6 +34,27 @@ It is possible to customize the list of providers for `clusterctl` by changing t +#### Creating a provider repository on GitHub + +You can use GitHub release to package your provider artifacts for other people to use. + +A github release can be used as a provider repository if: + +* The release tag is a valid semantic version number +* The components YAML, the metadata YAML and eventually the workload cluster templates are include into the release assets. + +See the [GitHub help](https://help.github.com/en/github/administering-a-repository/creating-releases) for more information +about how to create a release. + +#### Creating a local provider repository + +clusterctl supports reading from a repository defined on the local file system. + +A local repository can be defined by creating a `` folder with a `` sub-folder for each hosted release; +the sub-folder name MUST be a valid semantic version number. + +Each version sub-folder MUST contain the corresponding components YAML, the metadata YAML and eventually the workload cluster templates. + ### Metadata YAML The provider is required to generate a **metadata YAML** file and publish it to the provider's repository. From 52b208c8d63077454df33a884171ac3c68484ad4 Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Fri, 7 Feb 2020 08:48:35 +0100 Subject: [PATCH 2/3] address comments --- docs/book/src/clusterctl/commands/move.md | 4 ++-- docs/book/src/clusterctl/commands/upgrade.md | 13 ++++++------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/book/src/clusterctl/commands/move.md b/docs/book/src/clusterctl/commands/move.md index 39e5ec5b8331..5c85e598ade9 100644 --- a/docs/book/src/clusterctl/commands/move.md +++ b/docs/book/src/clusterctl/commands/move.md @@ -41,7 +41,7 @@ process completes. Pivoting is a process for moving the provider components and declared Cluster API resources from a source management cluster to a target management cluster. -This can now achieved with the following procedure: +This can now be achieved with the following procedure: 1. Use `clusterctl init` to install the provider components into the target management cluster 2. Use `clusterctl move` to move the cluster-api resources from a Source Management cluster to a Target Management cluster @@ -51,7 +51,7 @@ This can now achieved with the following procedure: The pivot process can be bounded with the creation of a temporary bootstrap cluster used to provision a target Management cluster. -This can now achieved with the following procedure: +This can now be achieved with the following procedure: 1. Create a temporary bootstrap cluster, e.g. using Kind or Minikube 2. Use `clusterctl init` to install the provider components diff --git a/docs/book/src/clusterctl/commands/upgrade.md b/docs/book/src/clusterctl/commands/upgrade.md index eb879a36e3da..94202df791e8 100644 --- a/docs/book/src/clusterctl/commands/upgrade.md +++ b/docs/book/src/clusterctl/commands/upgrade.md @@ -5,8 +5,8 @@ installed into a management cluster. ## Background info: management groups -The upgrade procedure is designed to ensure all the provider in a *management group* will be using the same -Cluster API - API version. +The upgrade procedure is designed to ensure all the providers in a *management group* use the same +API Version of Cluster API (contract), e.g. the v1alpha 3 Cluster API contract. A management group is a group of providers composed by a CoreProvider and a set of Bootstrap/ControlPlane/Infrastructure providers watching objects in the same namespace. @@ -28,7 +28,7 @@ Produces an output similar to this: ```shell Checking new release availability... -Management group: capi-system/cluster-api, latest release available for the v1alpha3 Cluster API version: +Management group: capi-system/cluster-api, latest release available for the v1alpha3 API Version of Cluster API (contract): NAME NAMESPACE TYPE CURRENT VERSION TARGET VERSION kubeadm-bootstrap capi-kubeadm-bootstrap-system BootstrapProvider v0.3.0 v0.3.1 @@ -38,10 +38,10 @@ docker capd-system InfrastructureProvider v0. You can now apply the upgrade by executing the following command: - upgrade apply --management-group capi-system/cluster-api --cluster-api-version v1alpha3 + clusterctl upgrade apply --management-group capi-system/cluster-api --contract v1alpha3 ``` -The output contains the latest release available for each management group in the cluster/for each Cluster API / API version +The output contains the latest release available for each management group in the cluster/for each API Version of Cluster API (contract) available at the moment. # upgrade apply @@ -49,7 +49,7 @@ available at the moment. After choosing the desired option for the upgrade, you can run the provided command. ```shell -upgrade apply --management-group capi-system/cluster-api --cluster-api-version v1alpha3 +clusterctl upgrade apply --management-group capi-system/cluster-api --cluster-api-version v1alpha3 ``` The upgrade process is composed by two steps: @@ -61,7 +61,6 @@ The upgrade process is composed by two steps: Please note that clusterctl does not upgrade Cluster API objects (Clusters, MachineDeployments, Machine etc.); upgrading such objects are the responsibility of the provider's controllers. -