diff --git a/docs/book/SUMMARY.md b/docs/book/SUMMARY.md new file mode 100644 index 000000000000..81fbd4592877 --- /dev/null +++ b/docs/book/SUMMARY.md @@ -0,0 +1,32 @@ +# Managing Kubernetes Infrastructure with the Cluster API + +* [Introduction](README.md) + +## Getting Started + +* [Abbreviations](ABBREVIATIONS.md) +* [Glossary](GLOSSARY.md) +* [Interoperability](getting_started/interoperability.md) +* [Existing Providers](getting_started/existing_providers.md) + +## Common Code + +* [Architecture](common_code/architecture.md) +* [Repository Layout](common_code/repository_layout.md) +* [Cluster Controller](common_code/cluster_controller.md) +* [Machine Controller](common_code/machine_controller.md) +* [MachineSet Controller](common_code/machineset_controller.md) +* [MachineDeployment Controller](common_code/machinedeployment_controller.md) +* [NodeRef Controller](common_code/noderef_controller.md) +* [Node Controller](common_code/node_controller.md) + +## Creating a New Provider + +* [Overview](provider_implementations/overview.md) +* [Naming](provider_implementations/naming.md) +* [Generate CRDs](provider_implementations/generate_crds.md) +* [Register Schemes](provider_implementations/register_schemes.md) +* [Create Actuators](provider_implementations/create_actuators.md) +* [Register Controllers](provider_implementations/register_controllers.md) +* [Building, Running, and Testing](provider_implementations/building_running_and_testing.md) + diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 340e88a6cb43..c86fe1eab7ac 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -1,24 +1,26 @@ # Summary [Introduction](./introduction.md) - -- [User Guide](./user/guide.md) - - [Concepts](./user/concepts.md) - - [Quick Start](./user/quick-start.md) - +[Quick Start](./user/quick-start.md) +[Concepts](./user/concepts.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) - [Developer Guide](./architecture/developer-guide.md) - [Repository Layout](./architecture/repository-layout.md) - [Controllers](./architecture/controllers.md) + - [Bootstrap](./architecture/controllers/bootstrap.md) - [Cluster](./architecture/controllers/cluster.md) - [Machine](./architecture/controllers/machine.md) - [MachineSet](./architecture/controllers/machine-set.md) - [MachineDeployment](./architecture/controllers/machine-deployment.md) + - [Node](./architecture/controllers/node.md) - [Provider Implementers](./providers/implementers.md) - [v1alpha1 to v1alpha2](./providers/v1alpha1-to-v1alpha2.md) - - [Tooling](./tooling/tooling.md) - - [Clusterctl](./tooling/clusterctl.md) - [Reference](./reference/reference.md) - - [Abbreviations](./reference/abbreviations.md) - [Glossary](./reference/glossary.md) - - [Providers](./reference/providers.md) + - [Provider List](./reference/providers.md) + - [clusterctl CLI](./tooling/clusterctl.md) diff --git a/docs/book/src/architecture/controllers/bootstrap.md b/docs/book/src/architecture/controllers/bootstrap.md new file mode 100644 index 000000000000..f6fd60eeb573 --- /dev/null +++ b/docs/book/src/architecture/controllers/bootstrap.md @@ -0,0 +1,16 @@ +# Bootstrap Controller + +Bootstrapping is the process in which: + +1. A cluster is bootstrapped +1. A machine is bootstrapped and takes on a role within a cluster + +[CAPBK](https://github.com/kubernetes-sigs/cluster-api-bootstrap-provider-kubeadm) is the reference bootstrap provider and is based on `kubeadm`. CAPBK codifies the steps for [creating a cluster](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/) in multiple configurations. + +![](../../images/bootstrap-controller.png) + +See [proposal](https://github.com/kubernetes-sigs/cluster-api/blob/master/docs/proposals/20190610-machine-states-preboot-bootstrapping.md) for the full details on how the bootstrap process works. + +### Implementations + +* [Kubeadm](https://github.com/kubernetes-sigs/cluster-api-bootstrap-provider-kubeadm) (Reference Implementation) diff --git a/docs/book/src/architecture/controllers/cluster.md b/docs/book/src/architecture/controllers/cluster.md index 5a512cc269f9..85a7ee65f32d 100644 --- a/docs/book/src/architecture/controllers/cluster.md +++ b/docs/book/src/architecture/controllers/cluster.md @@ -1,5 +1,7 @@ # Cluster Controller +![](../../images/cluster-admission-cluster-controller.svg) + The Cluster controller's main responsibilities are: * Setting an OwnerReference on the infrastructure object referenced in `Cluster.Spec.InfrastructureRef`. @@ -67,3 +69,4 @@ formatted as described below. | Secret name | Field name | Content | |:---:|:---:|:---:| |`-kubeconfig`|`value`|base64 encoded kubeconfig| + diff --git a/docs/book/src/architecture/controllers/machine-deployment.md b/docs/book/src/architecture/controllers/machine-deployment.md index 3d43baff5516..861ea7e475b4 100644 --- a/docs/book/src/architecture/controllers/machine-deployment.md +++ b/docs/book/src/architecture/controllers/machine-deployment.md @@ -1,3 +1,4 @@ # MachineDeployment + This page is still being written - stay tuned! diff --git a/docs/book/src/architecture/controllers/machine-set.md b/docs/book/src/architecture/controllers/machine-set.md index 49bd00771088..1626033ebbfb 100644 --- a/docs/book/src/architecture/controllers/machine-set.md +++ b/docs/book/src/architecture/controllers/machine-set.md @@ -1,3 +1,3 @@ # MachineSet - + This page is still being written - stay tuned! diff --git a/docs/book/src/architecture/controllers/machine.md b/docs/book/src/architecture/controllers/machine.md index 56d9ec42f32f..6953307f7613 100644 --- a/docs/book/src/architecture/controllers/machine.md +++ b/docs/book/src/architecture/controllers/machine.md @@ -1,5 +1,7 @@ # Machine Controller +![](../../images/cluster-admission-machine-controller.svg) + The Machine controller's main responsibilities are: * Setting an OwnerReference on: @@ -9,6 +11,7 @@ The Machine controller's main responsibilities are: * Copy data from `BootstrapConfig.Status.BootstrapData` to `Machine.Spec.Bootstrap.Data` if `Machine.Spec.Bootstrap.Data` is empty. * Setting NodeRefs to be able to associate machines and kubernetes nodes. +* Deleting Nodes in the target cluster when the associated machine is deleted. * Cleanup of related objects. * Keeping the Machine's Status object up to date with the InfrastructureMachine's Status object. @@ -95,3 +98,5 @@ The Machine controller will create a secret or use an existing secret in the fol | secret name | field name | content | |:---:|:---:|---| |`-kubeconfig`|`value`|base64 encoded kubeconfig that is authenticated with the child cluster| + + diff --git a/docs/book/src/architecture/controllers/node.md b/docs/book/src/architecture/controllers/node.md new file mode 100644 index 000000000000..579726d8e47c --- /dev/null +++ b/docs/book/src/architecture/controllers/node.md @@ -0,0 +1 @@ +# Node Controller diff --git a/docs/proposals/images/machine-states-preboot/Figure1.plantuml b/docs/book/src/images/bootstrap-controller.plantuml similarity index 100% rename from docs/proposals/images/machine-states-preboot/Figure1.plantuml rename to docs/book/src/images/bootstrap-controller.plantuml diff --git a/docs/proposals/images/machine-states-preboot/Figure1.png b/docs/book/src/images/bootstrap-controller.png similarity index 100% rename from docs/proposals/images/machine-states-preboot/Figure1.png rename to docs/book/src/images/bootstrap-controller.png diff --git a/docs/book/src/images/cluster-admission-cluster-controller.plantuml b/docs/book/src/images/cluster-admission-cluster-controller.plantuml new file mode 100644 index 000000000000..43009904957a --- /dev/null +++ b/docs/book/src/images/cluster-admission-cluster-controller.plantuml @@ -0,0 +1,26 @@ +@startuml cluster-admission-cluster-controller + +start; +:Cluster controller; + +repeat + :Cluster controller enqueues a Reconcile call; + if (Cluster has ready annotation) then (no) + #LightBlue:Get control plane machines for cluster; + if (A control plane machine is ready) then (yes) + #LightBlue:Set Cluster Ready annotation; + #LightBlue:Patch Cluster back to API server; + else (no) + #Pink:Return RequeueError; + endif + endif +repeat while (Reconcile returned RequeueError) is (yes) +-> no; +if (Reconcile returned error) then (yes) + #Pink:Error reconciling cluster; +else (no) + #LightBlue:Cluster is ready; +endif +stop; + +@enduml \ No newline at end of file diff --git a/docs/book/src/images/cluster-admission-cluster-controller.png b/docs/book/src/images/cluster-admission-cluster-controller.png new file mode 100644 index 000000000000..eb42f1181a70 Binary files /dev/null and b/docs/book/src/images/cluster-admission-cluster-controller.png differ diff --git a/docs/book/src/images/cluster-admission-cluster-controller.svg b/docs/book/src/images/cluster-admission-cluster-controller.svg new file mode 100644 index 000000000000..4443feecd0a9 --- /dev/null +++ b/docs/book/src/images/cluster-admission-cluster-controller.svg @@ -0,0 +1,39 @@ +Cluster controllerCluster controller enqueues a Reconcile callGet control plane machines for clusterA control plane machine is readyyesnoSet Cluster Ready annotationPatch Cluster back to API serverReturn RequeueErrornoCluster has ready annotationReconcile returned RequeueErroryesReconcile returned erroryesnoError reconciling clusterCluster is readyno \ No newline at end of file diff --git a/docs/book/src/images/cluster-admission-machine-controller.plantuml b/docs/book/src/images/cluster-admission-machine-controller.plantuml new file mode 100644 index 000000000000..5621c030df68 --- /dev/null +++ b/docs/book/src/images/cluster-admission-machine-controller.plantuml @@ -0,0 +1,37 @@ +@startuml cluster-admission-machine-controller + +start; +:Machine controller; + +repeat + :Machine controller enqueues a Create call; + if (Cluster has ready annotation) then (yes) + if (Machine has control plane role) then (yes) + #LightBlue:Join as control plane member; + else (no) + #LightBlue:Join as worker node; + endif + else (no) + if (Machine has control plane role) then (yes) + #LightBlue:Create control plane config map; + if (Control plane config map already exists) then (yes) + #Pink:Return RequeueError; + else (no) + #LightBlue:Init control plane; + #LightBlue:Set ready status on Machine annotation; + #LightBlue:Patch Machine back to API server; + endif + else (no) + #Pink:Return RequeueError; + endif + endif +repeat while (Create returned RequeueError) is (yes) +-> no; +if (Create returned error) then (yes) + #Pink:Error creating machine; +else (no) + #LightBlue:Machine has initialized or joined the cluster; +endif +stop; + +@enduml \ No newline at end of file diff --git a/docs/book/src/images/cluster-admission-machine-controller.png b/docs/book/src/images/cluster-admission-machine-controller.png new file mode 100644 index 000000000000..8e04fdc3d11e Binary files /dev/null and b/docs/book/src/images/cluster-admission-machine-controller.png differ diff --git a/docs/book/src/images/cluster-admission-machine-controller.svg b/docs/book/src/images/cluster-admission-machine-controller.svg new file mode 100644 index 000000000000..b2fefa59561f --- /dev/null +++ b/docs/book/src/images/cluster-admission-machine-controller.svg @@ -0,0 +1,50 @@ +Machine controllerMachine controller enqueues a Create callCluster has ready annotationyesnoMachine has control plane roleyesnoJoin as control plane memberJoin as worker nodeMachine has control plane roleyesnoCreate control plane config mapControl plane config map already existsyesnoReturn RequeueErrorInit control planeSet ready status on Machine annotationPatch Machine back to API serverReturn RequeueErrorCreate returned RequeueErroryesCreate returned erroryesnoError creating machineMachine has initialized or joined the clusterno \ No newline at end of file diff --git a/docs/book/src/reference/abbreviations.md b/docs/book/src/reference/abbreviations.md deleted file mode 100644 index a66c726dccc9..000000000000 --- a/docs/book/src/reference/abbreviations.md +++ /dev/null @@ -1,11 +0,0 @@ -# Acronyms and Abbreviations - -Acronym or Abbreviation | Full name --------------------------|--------------------- -CAPI | Cluster API -CAPA | Cluster API AWS infrastructure provider -CAPD | Cluster API Docker infrastructure provider -CAPO | Cluster API OpenStack infrastructure provider -CAPV | Cluster API vSphere infrastructure provider -CAPZ | Cluster API Azure infrastructure provider -CABPK | Cluster API Kubeadm bootstrap provider diff --git a/docs/book/src/reference/glossary.md b/docs/book/src/reference/glossary.md index 57cadd3eabcd..636ac56659e5 100644 --- a/docs/book/src/reference/glossary.md +++ b/docs/book/src/reference/glossary.md @@ -26,6 +26,31 @@ A temporary cluster that is used to provision a Target Management cluster. # C --- +### CAPI +Core Cluster API + +### CAPA +Cluster API Provider AWS + +### CABPK +Cluster API Bootstrap Provider Kubeadm + +### CAPD +Cluster API Provider Docker + +### CAPG +Cluster API Google Cloud Provider + +### CAPO +Cluster API Provider OpenStack + +### CAPV +Cluster API Provider vSphere + +### CAPZ +Cluster API Provider Azure + + ### Cluster A full Kubernetes deployment. See Management Cluster and Workload Cluster @@ -169,6 +194,4 @@ When running `clusterctl alpha phases pivot` this refers to the cluster that wil # W --- -### Workload cluster -A cluster whose lifecycle is managed by the Management cluster. diff --git a/docs/book/src/tasks/certs/generate-kubeconfig.md b/docs/book/src/tasks/certs/generate-kubeconfig.md new file mode 100644 index 000000000000..2ec7e23276bd --- /dev/null +++ b/docs/book/src/tasks/certs/generate-kubeconfig.md @@ -0,0 +1,14 @@ +## Generating a Kubeconfig with your own CA + +1. Create a new Certificate Signing Request (CSR) for the `system:masters` Kubernetes role, or specify any other role under CN. +```bash +openssl req -subj "/CN=system:masters" -new -newkey rsa:2048 -nodes -out admin.csr -keyout admin.key -out admin.csr +``` +2. Sign the CSR using the *[cluster-name]-ca* key: +```bash +openssl x509 -req -in admin.csr -CA tls.crt -CAkey tls.key -CAcreateserial -out admin.crt -days 5 -sha256 +``` +3. Update your kubeconfig with the sign key: +```bash +kubectl config set-credentials cluster-admin --client-certificate=admin.crt --client-key=admin.key --embed-certs=true +``` diff --git a/docs/book/src/tasks/certs/index.md b/docs/book/src/tasks/certs/index.md new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/book/src/tasks/certs/using-custom-certificates.md b/docs/book/src/tasks/certs/using-custom-certificates.md new file mode 100644 index 000000000000..d1d31550ee61 --- /dev/null +++ b/docs/book/src/tasks/certs/using-custom-certificates.md @@ -0,0 +1,34 @@ +## Using Custom Certificates + +Cluster API expects certificates and keys used for bootstrapping to follow the below convention. CAPBK generates new certificates using this convention if they do not already exist. + +Each certificate must be stored in a single secret named one of: + +| Name | Type | Example | +| ---------------------- | -------- | ------------------------------------------------------------ | +| *[cluster name]***-ca** | CA | openssl req -x509 -subj "/CN=Kubernetes API" -new -newkey rsa:2048 -nodes -keyout tls.key -sha256 -days 3650 -out tls.crt | +| *[cluster name]***-etcd** | CA | openssl req -x509 -subj "/CN=ETCD CA" -new -newkey rsa:2048 -nodes -keyout tls.key -sha256 -days 3650 -out tls.crt | +| *[cluster name]***-proxy** | CA | openssl req -x509 -subj "/CN=Front-End Proxy" -new -newkey rsa:2048 -nodes -keyout tls.key -sha256 -days 3650 -out tls.crt | +| *[cluster name]***-sa** | Key Pair | openssl genrsa -out tls.key 2048 && openssl rsa -in tls.key -pubout -out tls.crt | + + + + +**Example** +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: cluster1-ca +type: kubernetes.io/tls +data: + tls.crt: + tls.key: +``` + diff --git a/docs/book/src/tasks/index.md b/docs/book/src/tasks/index.md new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/book/src/tasks/installation.md b/docs/book/src/tasks/installation.md new file mode 100644 index 000000000000..c98d36ba1528 --- /dev/null +++ b/docs/book/src/tasks/installation.md @@ -0,0 +1,119 @@ +# Installation + +## Prerequisites + +- Install and setup [kubectl] in your local environment. +- Install and/or configure a [management cluster] + +## Setup Management Cluster + +Cluster API requires an existing kubernetes cluster accessible via kubectl, choose one of the options below: + +1. **Kind** + +```bash +kind create cluster --name=clusterapi +export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")" +``` + + + +2. **Existing Management Cluster** + +For production use-cases a "real" kubernetes cluster should be used with apropriate backup and DR policies and procedures in place. + +```bash +export KUBECONFIG=<...> +``` + +3. Pivoting + +Pivoting is the process of taking an initial kind cluster to create a new workload cluster, and then converting the workload cluster into a management cluster by migrating the Cluster API CRD's. + + +## Installation + +Using [kubectl], create the components on the [management cluster]: + +#### Install Cluster API + +```bash +kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api" asset:"cluster-api-components.yaml" version:"0.2.x"}} +``` + +#### Install the Bootstrap Provider + +{{#tabs name:"tab-installation-bootstrap" tabs:"Kubeadm"}} +{{#tab Kubeadm}} + +Check the [Kubeadm provider releases](https://github.com/kubernetes-sigs/cluster-api-bootstrap-provider-kubeadm/releases) for an up-to-date components file. + +```bash +kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api-bootstrap-provider-kubeadm" asset:"bootstrap-components.yaml" version:"0.1.x"}} +``` + +{{#/tab }} +{{#/tabs }} + + +#### Install Infrastructure Provider + +{{#tabs name:"tab-installation-infrastructure" tabs:"AWS,vSphere"}} +{{#tab AWS}} + + + +#### Install clusterawsadm + +Download the latest binary of `clusterawsadm` from the [AWS provider releases] and make sure to place it in your path. + +##### Create the components + +Check the [AWS provider releases] for an up-to-date components file. + +```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) + +# Create the components. +curl -L {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-aws" asset:"infrastructure-components.yaml" version:"0.4.x"}} \ + | envsubst \ + | kubectl create -f - +``` + +{{#/tab }} +{{#tab vSphere}} + +Check the [vSphere provider releases](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/releases) for an up-to-date components file. + +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). + +```bash +kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-vsphere" asset:"infrastructure-components.yaml" version:"0.5.x"}} +``` + +{{#/tab }} +{{#/tabs }} + + + +[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/ +[components]: ../reference/glossary.md#provider-components +[kind]: https://sigs.k8s.io/kind +[management cluster]: ../reference/glossary.md#management-cluster +[target cluster]: ../reference/glossary.md#target-cluster +[AWS provider releases]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases diff --git a/docs/book/src/user/concepts.md b/docs/book/src/user/concepts.md index 74d42e13cdfa..0f107d3754f3 100644 --- a/docs/book/src/user/concepts.md +++ b/docs/book/src/user/concepts.md @@ -1 +1,68 @@ # Concepts + +![](../images/management-cluster.svg) + + +### Management cluster + +The cluster where one or more Infrastructure Providers run, and where resources (e.g. Machines) are stored. Typically referred to when you are provisioning multiple clusters. + +### Workload/Target Cluster + +A cluster whose lifecycle is managed by the Management cluster. + +### Infrastructure provider + +A source of computational resources (e.g. machines, networking, etc.). Examples for cloud include AWS, Azure, Google, etc.; for bare metal include VMware, MAAS, metal3.io, etc. When there is more than one way to obtain resources from the same infrastructure provider (e.g. EC2 vs. EKS) each way is referred to as a variant. + +### Bootstrap provider + +The bootstrap provider is responsible for (usually by generating cloud-init or similar): + +1. Generating the cluster certificates, if not otherwise specified +1. Initializing the control plane, and gating the creation of other nodes until it is complete +1. Joining master and worker nodes to the cluster + +### Control plane + +The control plane (sometimes referred to as master nodes) is a set of [services](https://kubernetes.io/docs/concepts/#kubernetes-control-plane) that serve the Kubernetes API and reconcile desired state through the control-loops. + +* __Machine Based__ based control planes are the most common type deployment model and is used by tools like kubeadm and kubespray. Dedicated machines are provisioned running [*static pods*](https://kubernetes.io/docs/tasks/configure-pod-container/static-pod/) for the control plane components such as [*kube-apiserver*](https://kubernetes.io/docs/admin/kube-apiserver/), [*kube-controller-manager*](https://kubernetes.io/docs/admin/kube-controller-manager/) and [*kube-scheduler*](https://kubernetes.io/docs/admin/kube-scheduler/). + +* __Pod Based__ deployments require an external hosting cluster, the control plane is deployed using standard *Deployment* and *StatefulSet* objects and then the API exposed using a *Service*. + +* __External__ control planes are offered and controlled by some system other than Cluster API (e.g., GKE, AKS, EKS, IKS). + +As of v1alpha2 __Machine Based__ is the only supported Cluster API control plane type. +## Custom Resource Definitions (CRDs) + +### Machine + +A "Machine" is the declarative spec for a Node, as represented in Kuberenetes core. If a new Machine object is created, a provider-specific controller will handle provisioning and installing a new host to register as a new Node matching the Machine spec. If the Machine's spec is updated, a provider-specific controller is responsible for updating the Node in-place or replacing the host with a new one matching the updated spec. If a Machine object is deleted, the corresponding Node should have its external resources released by the provider-specific controller, and should be deleted as well. + +Fields like the kubelet version are modeled as fields on the Machine's spec. Any other information that is provider-specific, though, is part of the InfraProviderRef and is not portable between different providers. + +#### Machine Immutability (In-place Upgrade vs. Replace) + +From the perspective of Cluster API all machines are immutable, once they are created they are never updated (except for maybe labels, annotations and status) - only deleted. + +For this reason, it is recommended to use MachineDeployments which handles changes to machines by replacing them in the same way regular Deployments handle changes to the podSpec. + +### MachineDeployment + +MachineDeployment work similar to regular POD [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) reconciling changes to a machine spec by rolling out changes to 2 MachineSets, the old and newly updated. + + + +### MachineSet + +MachineSets work similar to regulat POD [ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/), MachineSets are not meant to be used directly, but are rather the mechanism MachineDeployments use to reconcile desired state. + + + +### BootstrapData + +BootstrapData contains the machine or node role specific initialization data (usually cloud-init) used by the infrastructure provider to bootstrap a machine into a node. + + + diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/user/quick-start.md index cbdc1f2838e4..b0314a841ffb 100644 --- a/docs/book/src/user/quick-start.md +++ b/docs/book/src/user/quick-start.md @@ -12,74 +12,12 @@ In this tutorial we'll cover the basics of how to use Cluster API to create one export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")" ``` -## Installation -Using [kubectl], let's create the components on the [management cluster]: +{{#include ../tasks/installation.md}} -#### Install Cluster API Components - -```bash -kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api" asset:"cluster-api-components.yaml" version:"0.2.x"}} -``` - -#### Install the Bootstrap Provider Components - -{{#tabs name:"tab-installation-bootstrap" tabs:"Kubeadm"}} -{{#tab Kubeadm}} - -Check the [Kubeadm provider releases](https://github.com/kubernetes-sigs/cluster-api-bootstrap-provider-kubeadm/releases) for an up-to-date components file. - -```bash -kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api-bootstrap-provider-kubeadm" asset:"bootstrap-components.yaml" version:"0.1.x"}} -``` - -{{#/tab }} -{{#/tabs }} - - -#### Install Infrastructure Provider Components - -{{#tabs name:"tab-installation-infrastructure" tabs:"AWS,vSphere"}} -{{#tab AWS}} - -{{#embed-github repo:"kubernetes-sigs/cluster-api-provider-aws" path:"docs/prerequisites.md"}} - -##### Create the components - -Check the [AWS provider releases] for an up-to-date components file. - -```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) - -# Create the components. -curl -L {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-aws" asset:"infrastructure-components.yaml" version:"0.4.x"}} \ - | envsubst \ - | kubectl create -f - -``` - -{{#/tab }} -{{#tab vSphere}} - -Check the [vSphere provider releases](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/releases) for an up-to-date components file. - -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). - -```bash -kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-vsphere" asset:"infrastructure-components.yaml" version:"0.5.x"}} -``` - -{{#/tab }} -{{#/tabs }} ## Usage -The Cluster API resources are now installed. - -![](../images/management-cluster.svg) - Now that we've got Cluster API, Bootstrap and Infrastructure resources installed, let's proceed to create a single node cluster.