diff --git a/README.md b/README.md index e04a583edb2b..b73a0159f32d 100644 --- a/README.md +++ b/README.md @@ -19,57 +19,6 @@ You can reach the maintainers of this project at: Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md). -### Quick Start +### Getting Started -Go [here](docs/README.md) for an example of how to get up and going with the cluster api using vSphere. - -### Where to get the containers - -The containers for this provider are currently hosted at `gcr.io/cnx-cluster-api/`. Each release of the -container are tagged with the release version appropriately. Please note, the release tagging changed to -stay uniform with the main cluster api repo. Also note, these are docker containers. A container runtime -must pull them. They cannot simply be downloaded. - -| vSphere provider version | container url | -| --- | --- | -| 0.1.0 | gcr.io/cnx-cluster-api/vsphere-cluster-api-provider:v0.1 | -| 0.2.0 | gcr.io/cnx-cluster-api/vsphere-cluster-api-provider:0.2.0 | - -| main Cluster API version | container url | -| --- | --- | -| 0.1.0 | gcr.io/k8s-cluster-api/cluster-api-controller:0.1.0 | - -To use the appropriate version (instead of `:latest`), replace the version in the generated `provider-components.yaml`, -described in the quick start guide. - -### Compatibility Matrix - -Below are tables showing the compatibility between versions of the vSphere provider, the main cluster api, -kubernetes versions, and OSes. Please note, this table only shows version 0.2 of the vSphere provider. Due -to the way this provider bootstrap nodes (e.g. using Ubuntu package manager to pull some components), there -were changes in some packages that broke version 0.1 (but may get resolved at some point) so the compatibility -tables for that provider version are not provided here. - -Compatibility matrix for Cluster API versions and the vSphere provider versions. - -| | Cluster API 0.1.0 | -|--- | --- | -| vSphere Provider 0.2.0 | ✓ | - -Compatibility matrix for the vSphere provider versions and Kubernetes versions. - -| |k8s 1.11.x|k8s 1.12.x|k8s 1.13.x|k8s 1.14.x| -|---|---|---|---|---| -| vSphere Provider 0.2.0 | ✓ | ✓ | ✓ | ✓ | - -Compatibility matrix for the vSphere provider versions and node OS. Further OS support may be added in future releases. - -| | Ubuntu Xenial Cloud Image | Ubuntu Bionic Cloud Image | -| --- | --- | --- | -| vSphere Provider 0.2.0 | ✓ | ✓ | - -Users may download the cloud images here: - -[Ubuntu Xenial (16.04)](https://cloud-images.ubuntu.com/xenial/current/) - -[Ubuntu Bionic (18.04)](https://cloud-images.ubuntu.com/bionic/current/) +See the [Getting Started](docs/getting_started.md) guide to get up and going with Cluster API for vSphere. diff --git a/docs/getting_started.md b/docs/getting_started.md index 1601d65c36af..72d1f860f09d 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -166,14 +166,26 @@ path that it ran (i.e. `out/kubeconfig`). This is the **admin** kubeconfig file going forward to spin up multiple clusters using Cluster API, however, it is recommended that you create dedicated roles with limited access before doing so. +Note that from this point forward, you no longer need to use `clusterctl` to provision clusters since your management cluster +(the cluster used to manage workload clusters) has been created. Workload clusters should be provisioned by applying Cluster API resources +directly on the management cluster using `kubectl`. More on this below. + ## Managing Workload Clusters using the Management Cluster With your management cluster bootstrapped, it's time to reap the benefits of Cluster API. From this point forward, clusters and machines (belonging to a cluster) are simply provisioned by creating `cluster`, `machine` and `machineset` resources. -Taking the generated `out/cluster.yaml` and `out/machine.yaml` file from earlier as a reference, you can create a cluster with the -initial control plane node by just editing the name of the cluster and machine resource. For example, the following cluster and -machine resource will provision a cluster named "prod-workload" with 1 initial control plane node: +Using the same `prod-yaml` make target, generate Cluster API resources for a new cluster, this time with a different name: +``` +$ CLUSTER_NAME=prod-workload make prod-yaml +``` + +**NOTE**: The `make prod-yaml` target is not required to manage your Cluster API resources at this point but is used to simplify this guide. +You should manage your Cluster API resources in the same way you would manage your application yaml files for Kubernetes. Use the +generated yaml files from `make prod-yaml` as a reference. + +The Cluster and Machine resource in `out/prod-workload/cluster.yaml` and `out/prod-workload/machines.yaml` defines your workload +cluster with the initial control plane. ```yaml --- @@ -227,7 +239,7 @@ spec: controlPlane: "1.13.6" ``` -To add 3 additional worker nodes to your cluster, create a machineset like the following: +To add 3 additional worker nodes to your cluster, see the generated machineset file `out/prod-workload/machineset.yaml`: ```yaml apiVersion: "cluster.k8s.io/v1alpha1" @@ -269,7 +281,17 @@ spec: controlPlane: "1.13.6" ``` -Run `kubectl apply -f` to apply the above files on your management cluster and it should start provisioning the new cluster. +Run `kubectl apply -f` to apply the above files on your management cluster and it should start provisioning the new cluster: +```bash +$ cd out/prod-workload +$ kubectl apply -f cluster.yaml +cluster.cluster.k8s.io/prod-workload created +$ kubectl apply -f machines.yaml +machine.cluster.k8s.io/prod-workload-controlplane-1 created +$ kubectl apply -f machineset.yaml +machineset.cluster.k8s.io/prod-workload-machineset-1 created +``` + Clusters that are provisioned by the management cluster that run your application workloads are called [Workload Clusters](https://github.com/kubernetes-sigs/cluster-api/blob/master/docs/book/GLOSSARY.md#workload-cluster). The `kubeconfig` file to access workload clusters should be accessible as a Kubernetes Secret on the management cluster. As of today, the @@ -286,3 +308,7 @@ $ kubectl get secret prod-workload-kubeconfig -o=jsonpath='{.data.value}' | base ``` Now that you have the `kubeconfig` for your Workload Cluster, you can start deploying your applications there. + +**NOTE**: workload clusters do not have any addons applied aside from those added by kubeadm. Nodes in your workload clusters +will be in the `NotReady` state until you apply a CNI addon. The `addons.yaml` file generated from `make prod-yaml` has a default calico +addon which you can use, otherwise apply custom addons based on your use-case.