Document manual steps to creating a cluster with an HA controlplane (#…

…545) * Document manual steps to creating a cluster with an HA controlplane * update doc * Update docs/creating-multinode-controlplane-clusters.md don't abbreviate. Co-Authored-By: ashish-amarnath <[email protected]> * Update docs/creating-multinode-controlplane-clusters.md accept suggestions Co-Authored-By: ashish-amarnath <[email protected]> * Update docs/creating-multinode-controlplane-clusters.md accept suggestions Co-Authored-By: ashish-amarnath <[email protected]> * Update docs/creating-multinode-controlplane-clusters.md accept suggestions Co-Authored-By: ashish-amarnath <[email protected]> * Update docs/creating-multinode-controlplane-clusters.md accept suggestions Co-Authored-By: ashish-amarnath <[email protected]> * copyedits to clarify instructions
kubernetes-sigs · Feb 13, 2019 · 878bae8 · 878bae8
1 parent e1ea167
commit 878bae8
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 0 deletions.
diff --git a/docs/creating-multinode-controlplane-clusters.md b/docs/creating-multinode-controlplane-clusters.md
@@ -0,0 +1,64 @@
+# Creating Clusters With Multi-Node Control Plane  <!-- omit in toc -->
+Currently, clusterctl only supports creating clusters with a single instance control plane, but cluster-api-provider-aws has the capability to create clusters with multiple control plane nodes. This document outlines the steps for standing up a cluster with a multi-node control plane.
+
+## Contents <!-- omit in toc -->
+- [Prerequisites](#prerequisites)
+  - [Creating cluster with single instance controlplane.](#creating-cluster-with-single-instance-controlplane)
+- [Growing controlplane into multi-node controlplane.](#growing-controlplane-into-multi-node-controlplane)
+- [Troubleshooting](#troubleshooting)
+  - [Instances for the new machines not getting created](#instances-for-the-new-machines-not-getting-created)
+  - [Instances were created and initialized, but nodes don't show up on running 'kubectl get no'](#instances-were-created-and-initialized-but-nodes-dont-show-up-on-running-kubectl-get-no)
+
+## Prerequisites
+### Creating cluster with single instance controlplane.
+Set up a single instance control plane cluster by following the [getting started guide](docs/getting-started.md).
+
+## Growing controlplane into multi-node controlplane.
+At this point, a cluster with a single instance control plane has been created and is responding to `kubectl`.
+
+Now that you have a cluster with a single instance control plane, more control plane instances can be added by creating a machine object for each desired control plane machine, one machine at a time. 
+1. Copy the following yaml into a file, say `controlplane-machine.yaml`.
+  ```bash
+  apiVersion: "cluster.k8s.io/v1alpha1"
+  kind: Machine
+  metadata:
+    name: <CONTROLPLANE_MACHINE_NAME>
+    labels:
+      cluster.k8s.io/cluster-name: <CLUSTER_NAME>
+      set: controlplane
+  spec:
+    versions:
+      kubelet: v1.13.2
+      controlPlane: v1.13.2
+    providerSpec:
+      value:
+        apiVersion: awsprovider/v1alpha1
+        kind: AWSMachineProviderSpec
+        instanceType: "t2.medium"
+        iamInstanceProfile: "control-plane.cluster-api-provider-aws.sigs.k8s.io"
+        keyName: "cluster-api-provider-aws.sigs.k8s.io"
+  ```
+  *Pro tip* 💡: You may refer to the machine's yaml in the release to create the above yaml for yourself.
+  Now, for each desired controlplane machine, edit the file with machine name and cluster name and create the machine object using the command below.
+  ```bash
+  kubectl apply -f controlplane-machine.yaml
+  ``` 
+  Note: You may have to use the `-n <NAMESPACE>` option to kubectl incase your cluster and machines were created in the non-default namespace.
+2. This step is optional. Watch these newly created machine objects being reconciled by following the logs from the `aws-provider-controller-manager-0` pod using the below command
+  ```bash
+  kubectl -n aws-provider-system logs -f aws-provider-controller-manager-0
+  ```
+Additionally, view the new instances initializing in the AWS console.
+
+3. Once the machine objects have been reconciled and the instances in AWS have been created and initialized, `kubectl get nodes` should show the new machines with master roles.
+
+Just like that, you have now transformed your cluster from a single instance controlplane to one with a multi-node controlplane. 🎉
+
+## Troubleshooting
+### Instances for the new machines not getting created
+Inspect the logs from the `aws-provider-controller-manager-0` pod to determine why the controlplane is unable to create the necessary resources. Follow the logs from the `aws-provider-controller-manager-0` pod using the command below:
+```bash
+kubectl -n aws-provider-system logs -f aws-provider-controller-manager-0
+```
+### Instances were created and initialized, but nodes don't show up on running 'kubectl get no'
+Inspect the system log on the newly created instances for information about why this instance failed to join the existing controlplane. Instructions on how to view the system log are available [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-console.html)
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -20,6 +20,7 @@
   - [Setting up the environment](#setting-up-the-environment)
   - [Generating cluster manifests and example cluster](#generating-cluster-manifests-and-example-cluster)
   - [Creating a cluster](#creating-a-cluster)
+- [Using the cluster](#using-the-cluster)
 - [Troubleshooting](#troubleshooting)
 - [Bootstrap running, but resources aren't being created](#bootstrap-running-but-resources-arent-being-created)
 
@@ -235,6 +236,13 @@ The created KIND cluster is ephemeral and is cleaned up automatically when done.
 
 For a more in-depth look into what `clusterctl` is doing during this create step, please see the [clusterctl document](/docs/clusterctl.md).
 
+## Using the cluster
+Kubeconfig for the new cluster is created in the directory from where the above `clusterctl create` was run.
+Run the following command to point `kubectl` to the kubeconfig of the new cluster
+`export KUBECONFIG=$(PWD)/kubeconfig`
+
+Alternatively, move the kubeconfig file to a desired location and set the `KUBECONFIG` environment variable accordingly.
+
 ## Troubleshooting
 
 ## Bootstrap running, but resources aren't being created