diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 62024764b018..16bb01f4c165 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -5,7 +5,6 @@ [Concepts](./user/concepts.md) [Personas](./user/personas.md) - [Tasks](./tasks/index.md) - - [Installation](./tasks/installation.md) - [Certificate Management](./tasks/certs/index.md) - [Using Custom Certificates](./tasks/certs/using-custom-certificates.md) - [Generating a Kubeconfig](./tasks/certs/generate-kubeconfig.md) diff --git a/docs/book/src/tasks/installation.md b/docs/book/src/tasks/installation.md deleted file mode 100644 index efa881b5d6cf..000000000000 --- a/docs/book/src/tasks/installation.md +++ /dev/null @@ -1,193 +0,0 @@ -# Installation - -## Common Prerequisites - -- Install and setup [kubectl] in your local environment - -## Install and/or configure a kubernetes cluster - -Cluster API requires an existing Kubernetes cluster accessible via kubectl; during the installation process the -Kubernetes cluster will be transformed into a [management cluster] by installing the Cluster API [provider components], so it -is recommended to keep it separated from any application workload. - -Please note that it is a common practice the creation of a temporary [bootstrap cluster] to be used to provision -a target [management cluster] on the selected [infrastructure provider]. - -Choose one of the options below: - -1. **Existing Management Cluster** - -For production use-cases a "real" Kubernetes cluster should be used with appropriate backup and DR policies and procedures in place. - -```bash -export KUBECONFIG=<...> -``` - -2. **Kind** - - - -[kind] can be used for creating a local Kubernetes cluster for development environments or for -the creation of a temporary [bootstrap cluster] used to provision a target [management cluster] on the selected infrastructure provider. - - ```bash - kind create cluster - ``` -Test to ensure the local kind cluster is ready: -``` -kubectl cluster-info -``` - -## Provider Specific Prerequisites -Depending on the infrastructure provider you are planning to use, some additional prerequisites should be satisfied -before getting started with Cluster API. - -{{#tabs name:"tab-installation-infrastructure" tabs:"AWS,Azure,Docker,GCP,vSphere,OpenStack,Metal3"}} -{{#tab AWS}} - -Download the latest binary of `clusterawsadm` from the [AWS provider releases] and make sure to place it in your path. - -```bash -# Create the base64 encoded credentials using clusterawsadm. -# This command uses your environment variables and encodes -# them in a value to be stored in a Kubernetes Secret. -export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm alpha bootstrap encode-aws-credentials) -``` - -See the [AWS Provider Prerequisites](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/master/docs/prerequisites.md) document for more details. - -{{#/tab }} -{{#tab Azure}} - -For more information about authorization, AAD, or requirements for Azure, visit the [Azure Provider Prerequisites](https://github.com/kubernetes-sigs/cluster-api-provider-azure/blob/master/docs/getting-started.md#prerequisites) document. - -```bash -# Create the base64 encoded credentials -export AZURE_SUBSCRIPTION_ID_B64="$(echo -n "$AZURE_SUBSCRIPTION_ID" | base64 | tr -d '\n')" -export AZURE_TENANT_ID_B64="$(echo -n "$AZURE_TENANT_ID" | base64 | tr -d '\n')" -export AZURE_CLIENT_ID_B64="$(echo -n "$AZURE_CLIENT_ID" | base64 | tr -d '\n')" -export AZURE_CLIENT_SECRET_B64="$(echo -n "$AZURE_CLIENT_SECRET" | base64 | tr -d '\n')" -``` - -{{#/tab }} -{{#tab Docker}} - -If you are planning to use to test locally Cluster API using the Docker infrastructure provider, please follow additional -steps described in the [developer instruction](../clusterctl/developers.md#additional-steps-in-order-to-use-the-docker-provider) page. - -{{#/tab }} -{{#tab GCP}} - -```bash -# Create the base64 encoded credentials by catting your credentials json. -# This command uses your environment variables and encodes -# them in a value to be stored in a Kubernetes Secret. -export GCP_B64ENCODED_CREDENTIALS=$( cat /path/to/gcp-credentials.json | base64 | tr -d '\n' ) -``` - -{{#/tab }} -{{#tab vSphere}} - -It is required to use an official CAPV machine image for your vSphere VM templates. See [Uploading CAPV Machine Images](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/master/docs/getting_started.md#uploading-the-capv-machine-image) for instructions on how to do this. - -Then, it is required Upload vCenter credentials as a Kubernetes secret: - -```bash -$ cat <" - password: "" -EOF -``` - -For more information about prerequisites, credentials management, or permissions for vSphere, visit the [getting started guide](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/master/docs/getting_started.md). - -{{#/tab }} -{{#tab OpenStack}} - -Please visit the [OpenStack getting started guide](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/master/docs/getting-started.md). - -{{#/tab }} -{{#tab Metal3}} - -Please visit the [Metal3 getting started guide](https://github.com/metal3-io/cluster-api-provider-metal3/blob/master/docs/getting-started.md). - -{{#/tab }} -{{#/tabs }} - -## Install clusterctl -The clusterctl CLI tool handles the lifecycle of a Cluster API management cluster. - -{{#tabs name:"install-clusterctl" tabs:"linux,macOS"}} -{{#tab linux}} - -#### Install clusterctl binary with curl on linux -Download the latest release; for example, to download version v0.3.0 on linux, type: -``` -curl -L {{#releaselink gomodule:"sigs.k8s.io/cluster-api" asset:"clusterctl-linux-amd64" version:"0.3.x"}} -o clusterctl -``` -Make the kubectl binary executable. -``` -chmod +x ./clusterctl -``` -Move the binary in to your PATH. -``` -sudo mv ./clusterctl /usr/local/bin/clusterctl -``` -Test to ensure the version you installed is up-to-date: -``` -clusterctl version -``` - -{{#/tab }} -{{#tab macOS}} - -#### Install clusterctl binary with curl on macOS -Download the latest release; for example, to download version v0.3.0 on macOS, type: -``` -curl -L {{#releaselink gomodule:"sigs.k8s.io/cluster-api" asset:"clusterctl-darwin-amd64" version:"0.3.x"}} -o clusterctl -``` -Make the kubectl binary executable. -``` -chmod +x ./clusterctl -``` -Move the binary in to your PATH. -``` -sudo mv ./clusterctl /usr/local/bin/clusterctl -``` -Test to ensure the version you installed is up-to-date: -``` -clusterctl version -``` -{{#/tab }} -{{#/tabs }} - - -[AWS provider releases]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases -[bootstrap cluster]: ../reference/glossary.md#bootstrap-cluster -[infrastructure provider]: ../reference/glossary.md#infrastructure-provider -[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/ -[kind]: https://kind.sigs.k8s.io/ -[management cluster]: ../reference/glossary.md#management-cluster -[provider components]: ../reference/glossary.md#provider-components \ No newline at end of file diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/user/quick-start.md index a81a666078d7..2bfa63985148 100644 --- a/docs/book/src/user/quick-start.md +++ b/docs/book/src/user/quick-start.md @@ -2,32 +2,214 @@ In this tutorial we'll cover the basics of how to use Cluster API to create one or more Kubernetes clusters. -{{#include ../tasks/installation.md}} +## Installation -# Usage +### Common Prerequisites -## Initialize the management cluster +- Install and setup [kubectl] in your local environment -Now that we've got clusterctl installed and all the prerequisites in places, -let's transforms the Kubernetes cluster into a management cluster by using the `clusterctl init`. +### Install and/or configure a kubernetes cluster + +Cluster API requires an existing Kubernetes cluster accessible via kubectl; during the installation process the +Kubernetes cluster will be transformed into a [management cluster] by installing the Cluster API [provider components], so it +is recommended to keep it separated from any application workload. + +It is a common practice to create a temporary, local bootstrap cluster which is then used to provision +a target [management cluster] on the selected [infrastructure provider]. + +Choose one of the options below: + +1. **Existing Management Cluster** + +For production use-cases a "real" Kubernetes cluster should be used with appropriate backup and DR policies and procedures in place. + +```bash +export KUBECONFIG=<...> +``` + +2. **Kind** + + + +[kind] can be used for creating a local Kubernetes cluster for development environments or for +the creation of a temporary [bootstrap cluster] used to provision a target [management cluster] on the selected infrastructure provider. + + ```bash + kind create cluster + ``` +Test to ensure the local kind cluster is ready: +``` +kubectl cluster-info +``` + +### Install clusterctl +The clusterctl CLI tool handles the lifecycle of a Cluster API management cluster. + +{{#tabs name:"install-clusterctl" tabs:"linux,macOS"}} +{{#tab linux}} + +#### Install clusterctl binary with curl on linux +Download the latest release; for example, to download version v0.3.0 on linux, type: +``` +curl -L {{#releaselink gomodule:"sigs.k8s.io/cluster-api" asset:"clusterctl-linux-amd64" version:"0.3.x"}} -o clusterctl +``` +Make the kubectl binary executable. +``` +chmod +x ./clusterctl +``` +Move the binary in to your PATH. +``` +sudo mv ./clusterctl /usr/local/bin/clusterctl +``` +Test to ensure the version you installed is up-to-date: +``` +clusterctl version +``` + +{{#/tab }} +{{#tab macOS}} + +##### Install clusterctl binary with curl on macOS +Download the latest release; for example, to download version v0.3.0 on macOS, type: +``` +curl -L {{#releaselink gomodule:"sigs.k8s.io/cluster-api" asset:"clusterctl-darwin-amd64" version:"0.3.x"}} -o clusterctl +``` +Make the kubectl binary executable. +``` +chmod +x ./clusterctl +``` +Move the binary in to your PATH. +``` +sudo mv ./clusterctl /usr/local/bin/clusterctl +``` +Test to ensure the version you installed is up-to-date: +``` +clusterctl version +``` +{{#/tab }} +{{#/tabs }} + + +### Initialize the management cluster + +Now that we've got clusterctl installed and all the prerequisites in places, let's transforms the Kubernetes cluster +into a management cluster by using the `clusterctl init`. The command accepts as input a list of providers to install; when executed for the first time, `clusterctl init` -automatically adds to the list the `cluster-api` core provider, and if unspecified, it -also adds the `kubeadm` bootstrap and `kubeadm` control-plane providers. +automatically adds to the list the `cluster-api` core provider, and if unspecified, it also adds the `kubeadm` bootstrap +and `kubeadm` control-plane providers. -```shell -clusterctl init --infrastructure aws +#### Initialization for common providers + +Depending on the infrastructure provider you are planning to use, some additional prerequisites should be satisfied +before getting started with Cluster API. + +{{#tabs name:"tab-installation-infrastructure" tabs:"AWS,Azure,Docker,GCP,vSphere,OpenStack,Metal3"}} +{{#tab AWS}} + +Download the latest binary of `clusterawsadm` from the [AWS provider releases] and make sure to place it in your path. + +```bash +$ export AWS_REGION=us-east-1 # This is used to help encode your environment variables +# Create the base64 encoded credentials using clusterawsadm. +# This command uses your environment variables and encodes +# them in a value to be stored in a Kubernetes Secret. +$ export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm alpha bootstrap encode-aws-credentials) + +# Finally, initialize the management cluster +$ clusterctl init --infrastructure aws +``` + +See the [AWS provider prerequisites] document for more details. + +{{#/tab }} +{{#tab Azure}} + +For more information about authorization, AAD, or requirements for Azure, visit the [Azure provider prerequisites] document. + +```bash +$ export AZURE_SUBSCRIPTION_ID_B64="$(echo -n "$AZURE_SUBSCRIPTION_ID" | base64 | tr -d '\n')" +$ export AZURE_TENANT_ID_B64="$(echo -n "$AZURE_TENANT_ID" | base64 | tr -d '\n')" +$ export AZURE_CLIENT_ID_B64="$(echo -n "$AZURE_CLIENT_ID" | base64 | tr -d '\n')" +$ export AZURE_CLIENT_SECRET_B64="$(echo -n "$AZURE_CLIENT_SECRET" | base64 | tr -d '\n')" + +# Finally, initialize the management cluster +$ clusterctl init --infrastructure azure ``` +{{#/tab }} +{{#tab Docker}} + +If you are planning to use to test locally Cluster API using the Docker infrastructure provider, please follow additional +steps described in the [developer instruction][docker-provider] page. + +{{#/tab }} +{{#tab GCP}} + +```bash +# Create the base64 encoded credentials by catting your credentials json. +# This command uses your environment variables and encodes +# them in a value to be stored in a Kubernetes Secret. +$ export GCP_B64ENCODED_CREDENTIALS=$( cat /path/to/gcp-credentials.json | base64 | tr -d '\n' ) + +# Finally, initialize the management cluster +$ clusterctl init --infrastructure gcp +``` + +{{#/tab }} +{{#tab vSphere}} + +```bash +# The username used to access the remote vSphere endpoint +$ export VSPHERE_USERNAME="vi-admin@vsphere.local" +# The password used to access the remote vSphere endpoint +# You may want to set this in ~/.cluster-api/clusterctl.yaml so your password is not in +# bash history +$ export VSPHERE_PASSWORD="admin!23" + +# Finally, initialize the management cluster +$ clusterctl init --infrastructure vsphere +``` + +For more information about prerequisites, credentials management, or permissions for vSphere, see the [vSphere getting started +guide]. + +{{#/tab }} +{{#tab OpenStack}} + +Please visit the [OpenStack getting started guide]. + +{{#/tab }} +{{#tab Metal3}} + +Please visit the [Metal3 getting started guide]. + +{{#/tab }} +{{#/tabs }} + + The output of `clusterctl init` is similar to this: ```shell @@ -46,13 +228,11 @@ You can now create your first workload cluster by running the following: clusterctl config cluster [name] --kubernetes-version [version] | kubectl apply -f - ``` -See [`clusterctl init`](../clusterctl/commands/init.md) for more details. - -## Create the first workload cluster +### Create your first workload cluster -Once the management cluster is ready, you can create the first workload cluster. +Once the management cluster is ready, you can create your first workload cluster. -### Preparing the Workload cluster configuration +#### Preparing the workload cluster configuration The `clusterctl create config` command returns a YAML template for creating a [workload cluster]. @@ -65,16 +245,15 @@ it detects that there is only an `aws` infrastructure provider and so it uses th - @@ -82,19 +261,119 @@ for cluster templates.

Action Required

-If the cluster template defined by the infrastructure provider expects some environment variables, user +If the cluster template defined by the infrastructure provider expects some environment variables, you should ensure those variables are set in advance. -If you have followed [provided specific requirements](#provider-specific-prerequisites), everything should be already set -at this stage. Otherwise, you can look at [`clusterctl config cluster`](../clusterctl/commands/config-cluster.md) for details about how to discover the list of -variables required by a cluster templates. +Instructions are provided for common providers below. + +Otherwise, you can look at the `clusterctl config cluster` [command][clusterctl config cluster] documentation for details about how to +discover the list of variables required by a cluster templates. + +#### Required configuration for common providers + +Depending on the infrastructure provider you are planning to use, some additional prerequisites should be satisfied +before configuring a cluster with Cluster API. + +{{#tabs name:"tab-installation-infrastructure" tabs:"AWS,Azure,Docker,GCP,vSphere,OpenStack,Metal3"}} +{{#tab AWS}} + +Download the latest binary of `clusterawsadm` from the [AWS provider releases] and make sure to place it in your path. + + +```bash +$ export AWS_REGION=us-east-1 +$ export AWS_SSH_KEY_NAME=default +# Select instance types +$ export AWS_CONTROL_PLANE_MACHINE_TYPE=t3.large +$ export AWS_NODE_MACHINE_TYPE=t3.large +``` + + +See the [AWS provider prerequisites] document for more details. + +{{#/tab }} +{{#tab Azure}} + +```bash +# Name of the resource group to provision into +$ export AZURE_RESOURCE_GROUP="kubernetesResourceGroup" +# Name of the Azure datacenter location +$ export AZURE_LOCATION="centralus" +# Name of the virtual network in which to provision the cluster +$ export AZURE_VNET_NAME="kubernetesNetwork" +# Select machine types +$ export AZURE_CONTROL_PLANE_MACHINE_TYPE="Standard_D4a_v4" +$ export AZURE_NODE_MACHINE_TYPE="Standard_D4a_v4" +# A SSH key to use for break-glass access +$ export AZURE_SSH_PUBLIC_KEY="ssh-rsa AAAAB3N..." +``` + +For more information about authorization, AAD, or requirements for Azure, visit the [Azure provider prerequisites] document. + + +{{#/tab }} +{{#tab Docker}} + +If you are planning to use to test locally Cluster API using the Docker infrastructure provider, please follow additional +steps described in the [developer instructions][docker-provider] page. + +{{#/tab }} +{{#tab GCP}} + +See the [GCP provider] for more information. + +{{#/tab }} +{{#tab vSphere}} + +It is required to use an official CAPV machine images for your vSphere VM templates. See [uploading CAPV machine images][capv-upload-images] for instructions on how to do this. + +```bash +# The vCenter server IP or FQDN +$ export VSPHERE_SERVER="10.0.0.1" +# The vSphere datacenter to deploy the management cluster on +$ export VSPHERE_DATACENTER="SDDC-Datacenter" +# The vSphere datastore to deploy the management cluster on +$ export VSPHERE_DATASTORE="vsanDatastore" +# The VM network to deploy the management cluster on +$ export VSPHERE_NETWORK="VM Network" + # The vSphere resource pool for your VMs +$ export VSPHERE_RESOURCE_POOL="*/Resources" +# The VM folder for your VMs. Set to "" to use the root vSphere folder +$ export VSPHERE_FOLDER: "vm" + # The VM template to use for your +$ export VSPHERE_TEMPLATE: "ubuntu-1804-kube-v1.17.3" m +# The VM template to use for the HAProxy load balanceranagement cluster. +$ export VSPHERE_HAPROXY_TEMPLATE: "capv-haproxy-v0.6.0-rc.2" + # The public ssh authorized key on all machines +$ export VSPHERE_SSH_AUTHORIZED_KEY: "ssh-rsa AAAAB3N..." + +$ clusterctl init --infrastructure vsphere +``` + +For more information about prerequisites, credentials management, or permissions for vSphere, see the [vSphere getting started guide]. + +{{#/tab }} +{{#tab OpenStack}} + +Please visit the [OpenStack getting started guide]. + +{{#/tab }} +{{#tab Metal3}} + +Please visit the [Metal3 getting started guide]. + +{{#/tab }} +{{#/tabs }} + +#### Generating the cluster configuration + For the purpose of this tutorial, we’ll name our cluster capi-quickstart. ``` -clusterctl config cluster capi-quickstart --kubernetes-version v1.17.0 --control-plane-machine-count=3 --worker-machine-count=3 > capi-quickstart.yaml +clusterctl config cluster capi-quickstart --kubernetes-version v1.17.3 --control-plane-machine-count=3 --worker-machine-count=3 > capi-quickstart.yaml ``` Creates a YAML file named `capi-quickstart.yaml` with a predefined list of Cluster API objects; Cluster, Machines, @@ -102,9 +381,9 @@ Machine Deployments, etc. The file can be eventually modified using your editor of choice. -See [`clusterctl config cluster`](../clusterctl/commands/config-cluster.md) for more details. - -### Apply the Workload cluster +See `[clusterctl config cluster]` for more details. + +#### Apply the workload cluster When ready, run the following command to apply the cluster manifest. @@ -124,16 +403,15 @@ awsmachinetemplate.infrastructure.cluster.x-k8s.io/capi-quickstart-md-0 created kubeadmconfigtemplate.bootstrap.cluster.x-k8s.io/capi-quickstart-md-0 created ``` -### Accessing Workload cluster +#### Accessing the workload cluster -To verify the control plane is up, check if the control plane machine -has a ProviderID. +To verify the control plane is up, check if the control plane is ready. ``` -kubectl get machines --selector cluster.x-k8s.io/control-plane --all-namespaces +kubectl get kubeadmcontrolplane --all-namespaces ``` If the control plane is deployed using a control plane provider, such as -[KubeadmControlPlane][control-plane-controller] ensure the control plane is +[KubeadmControlPlane] ensure the control plane is ready. ``` kubectl get clusters --output jsonpath="{range .items[*]} [{.metadata.name} {.status.ControlPlaneInitialized} {.status.ControlPlaneReady}] {end}" @@ -151,6 +429,7 @@ kubectl --namespace=default get secret/capi-quickstart-kubeconfig -o jsonpath={. Calico is used here as an example. + ```bash kubectl --kubeconfig=./capi-quickstart.kubeconfig \ apply -f https://docs.projectcalico.org/v3.12/manifests/calico.yaml @@ -163,10 +442,27 @@ let's check the status using `kubectl get nodes`: kubectl --kubeconfig=./capi-quickstart.kubeconfig get nodes ``` -# Next Steps +## Next steps -See the [clusterctl](../clusterctl/overview.md) documentation for more detail about clusterctl supported actions. +See the [clusterctl] documentation for more detail about clusterctl supported actions. -[control-plane-controller]: ../developer/architecture/controllers/control-plane.md +[AWS provider prerequisites]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/master/docs/prerequisites.md +[AWS provider releases]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases +[Azure Provider Prerequisites]: https://github.com/kubernetes-sigs/cluster-api-provider-azure/blob/master/docs/getting-started.md#prerequisites +[bootstrap cluster]: ../reference/glossary.md#bootstrap-cluster +[capv-upload-images]: https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/master/docs/getting_started.md#uploading-the-machine-images +[clusterctl config cluster]: ../clusterctl/commands/config-cluster.md +[clusterctl]: ../clusterctl/overview.md +[docker-provider]: ../clusterctl/developers.md#additional-steps-in-order-to-use-the-docker-provider +[GCP provider]: https://github.com/kubernetes-sigs/cluster-api-provider-gcp +[infrastructure provider]: ../reference/glossary.md#infrastructure-provider +[kind]: https://kind.sigs.k8s.io/ +[KubeadmControlPlane]: ../developer/architecture/controllers/control-plane.md +[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/ +[management cluster]: ../reference/glossary.md#management-cluster +[Metal3 getting started guide]: https://github.com/metal3-io/cluster-api-provider-metal3/blob/master/docs/getting-started.md +[OpenStack getting started guide]: https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/master/docs/getting-started.md +[provider components]: ../reference/glossary.md#provider-components +[vSphere getting started guide]: https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/master/docs/getting_started.md [workload cluster]: ../reference/glossary.md#workload-cluster