📖 Quickstart / add other sections

Signed-off-by: Vince Prignano <vincepri@vmware.com>

README.md

@@ -12,7 +12,7 @@
 - [Scope, objectives, goals and requirements](./docs/scope-and-objectives.md)
 - [Feature proposals](./docs/proposals)
 - [Reference use cases](./docs/staging-use-cases.md)
-- [Quick Start](https://cluster-api.sigs.k8s.io/quick-start.html)
+- [Quick Start](https://cluster-api.sigs.k8s.io/user/quick-start.html)
 
 ## What is the Cluster API?
 

docs/book/book.toml

@@ -8,3 +8,6 @@ title = "The Cluster API Book"
 [output.html]
 curly-quotes = true
 git-repository-url = "https://sigs.k8s.io/cluster-api"
+
+[preprocessor.foo]
+command = "go run -tags=tools ../../hack/tools/tabulate/tabulate.go"

docs/book/install-and-build.sh

@@ -60,4 +60,5 @@ curl -sL -o /tmp/mdbook.${ext} "https://github.com/rust-lang-nursery/mdBook/rele
 ${cmd} /tmp/mdbook.${ext}
 chmod +x /tmp/mdbook
 
-/tmp/mdbook build docs/book
+# Finally build the book.
+(cd docs/book && /tmp/mdbook build)

docs/book/src/SUMMARY.md

@@ -2,19 +2,21 @@
 
 [Introduction](./introduction.md)
 
-[Quick Start](./quick-start.md)
+- [User Guide](./user/guide.md)
+    - [Concepts](./user/concepts.md)
+    - [Quick Start](./user/quick-start.md)
 
-- [Architecture](./architecture/architecture.md)
+- [Developer Guide](./architecture/developer-guide.md)
     - [Repository Layout](./architecture/repository-layout.md)
     - [Controllers](./architecture/controllers.md)
         - [Cluster](./architecture/controllers/cluster.md)
         - [Machine](./architecture/controllers/machine.md)
         - [MachineSet](./architecture/controllers/machine-set.md)
         - [MachineDeployment](./architecture/controllers/machine-deployment.md)
-
-- [Clusterctl](./clusterctl/clusterctl.md)
-
-- [Provider Implementers](./providers/implementers.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)

docs/book/src/architecture/developer-guide.md

@@ -0,0 +1 @@
+# Developer Guide

docs/book/src/introduction.md

@@ -1,7 +1,7 @@
 # The Cluster API Book <div style="float: right; position: relative; display: inline;"><img src="images/introduction.png" width="160px" /></div>
 
 **Note:** Impatient readers may head straight to [Quick
-Start](quick-start.md).
+Start](./user/quick-start.md).
 
 **Using Cluster API v1alpha1? Check the [legacy
 documentation](https://release-0-1.cluster-api.sigs.k8s.io)**
@@ -14,4 +14,4 @@ manage the lifecycle of a Kubernetes cluster.
 
 {{#include ../../scope-and-objectives.md:Goals}}
 
-{{#include ../../../README.md:Get Involved}}
+{{#include ../../../README.md:Community}}

docs/developer/v1alpha1-compared-to-v1alpha2.md → docs/book/src/providers/v1alpha1-to-v1alpha2.md

@@ -25,7 +25,6 @@ controllers that are responsible for the core types:
 * Machine
 * MachineSet
 * MachineDeployment
-* [plus a few more](../../pkg/apis/cluster/v1alpha2)
 
 Bootstrap providers are an entirely new concept aimed at reducing the amount of kubeadm boilerplate that every provider
 reimplemented in v1alpha1. The Bootstrap provider is responsible for running a controller that generates data necessary
@@ -41,7 +40,7 @@ bootstrap data to turn the infrastructure into a Kubernetes cluster.
 
 Actuators are interfaces that the Cluster API controller calls. A provider pulls in the generic Cluster API controller
 and then registers actuators to run specific infrastructure logic (calls to the provider cloud).
- 
+
 ### v1alpha2
 
 Actuators are not used in this version. Cluster API's controllers are no longer shared across providers and therefore
@@ -57,11 +56,11 @@ create a cloud instance for Kubernetes to run on.
 
 `clusterctl` was a command line tool packaged with v1alpha1 providers. The goal of this tool was to go from nothing to a
 running management cluster in whatever environment the provider was built for. For example, Cluster-API-Provider-AWS
-packaged a `clusterctl` that created a Kubernetes cluster in EC2 and installed the necessary controllers to respond to 
+packaged a `clusterctl` that created a Kubernetes cluster in EC2 and installed the necessary controllers to respond to
 Cluster API's APIs.
 
 ### v1alpha2
 
-`clusterctl` is likely becoming provider-agnostic meaning one clusterctl is bundled with Cluster API and can be reused 
+`clusterctl` is likely becoming provider-agnostic meaning one clusterctl is bundled with Cluster API and can be reused
 across providers. Work here is still being figured out but providers will not be packaging their own `clusterctl`
 anymore.

docs/book/src/reference/glossary.md

@@ -137,7 +137,12 @@ The pivot process is also used for deleting a management cluster and could also
 
 See [Infrastructure Provider](#user-content-infrastructure-provider)
 
-##### Provider implementation
+### Provider components
+
+Refers to the YAML artifact a provider publishes as part of their releases which is required to use the provider components,
+it usually contains Custom Resource Definitions (CRDs), Deployments (to run the controller manager), RBAC, etc.
+
+### Provider implementation
 
 Existing Cluster API implementations consist of generic and infrastructure provider-specific logic. The [infrastructure provider](#infrastructure-provider)-specific logic is currently maintained in infrastructure provider repositories.
 

docs/book/src/reference/providers.md

@@ -27,6 +27,6 @@ support v1alpha2 API types.
 
 Following are the implementations managed by third-parties adopting the standard cluster-api and/or machine-api being developed here.
 
-  * Kubermatic machine-controller, https://github.com/kubermatic/machine-controller/tree/master
-  * Machine API Operator, https://github.com/openshift/machine-api-operator/tree/master
-  * Machine-controller-manager, https://github.com/gardener/machine-controller-manager/tree/cluster-api
+  * [Kubermatic machine controller](https://github.com/kubermatic/machine-controller/tree/master)
+  * [Machine API Operator](https://github.com/openshift/machine-api-operator/tree/master)
+  * [Machine controller manager](https://github.com/gardener/machine-controller-manager/tree/cluster-api)

docs/book/src/tooling/tooling.md

@@ -0,0 +1 @@
+# Tooling

docs/book/src/user/concepts.md

@@ -0,0 +1 @@
+# Concepts

docs/book/src/user/guide.md

@@ -0,0 +1 @@
+# User Guide

docs/book/src/user/quick-start.md

@@ -0,0 +1,152 @@
+# Quick Start
+
+In this tutorial we'll cover the basics of how to use Cluster API to create one or more Kubernetes clusters.
+
+## Prerequisites
+
+- Install and setup [kubectl] in your local environment.
+- A Kubernetes cluster to be used as [management cluster](../reference/glossary.md#management-cluster), for the purpose of this quick start, we suggest you to use [kind].
+    ```bash
+    kind create cluster --name=clusterapi
+    export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
+    ```
+
+## Installation
+
+Using [kubectl], let's create the components on the management cluster:
+
+#### Install Cluster API Components
+```bash
+kubectl create -f https://github.com/kubernetes-sigs/cluster-api/releases/latest/download/cluster-api-components.yaml
+```
+
+#### Install the Bootstrap Provider Components
+
+{{#tabs name:"tab-installation-bootstrap" tabs:"Kubeadm"}}
+{{#tab Kubeadm}}
+
+```bash
+kubectl create -f https://github.com/kubernetes-sigs/cluster-api-bootstrap-provider-kubeadm/releases/latest/download/bootstrap-components.yaml
+```
+
+{{#/tab }}
+{{#/tabs }}
+
+
+#### Install Infrastructure Provider Components
+
+{{#tabs name:"tab-installation-infrastructure" tabs:"AWS"}}
+{{#tab AWS}}
+
+For more information about prerequisites, credentials management, and or permissions for AWS, visit the [getting started guide](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/master/docs/getting-started.md).
+
+```bash
+kubectl create -f https://github.com/kubernetes-sigs/cluster-api-bootstrap-provider-kubeadm/releases/latest/download/infrastructure-components.yaml
+```
+
+{{#/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.
+
+For the purpose of this tutorial, we'll name our cluster `capi-quickstart`.
+
+{{#tabs name:"tab-usage-cluster-resource" tabs:"AWS"}}
+{{#tab AWS}}
+
+```yaml
+---
+apiVersion: cluster.x-k8s.io/v1alpha2
+kind: Cluster
+metadata:
+  name: capi-quickstart
+spec:
+  clusterNetwork:
+    pods:
+      cidrBlocks: ["192.168.0.0/16"]
+  infrastructureRef:
+    apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+    kind: AWSCluster
+    name: capi-quickstart
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+kind: AWSCluster
+metadata:
+  name: capi-quickstart
+spec:
+  region:
+  sshKeyName: default
+```
+{{#/tab }}
+{{#/tabs }}
+
+Now that we've created the cluster object, we can create the first control plane Machine.
+
+{{#tabs name:"tab-usage-controlplane-resource" tabs:"AWS"}}
+{{#tab AWS}}
+
+```yaml
+---
+apiVersion: cluster.x-k8s.io/v1alpha2
+kind: Machine
+metadata:
+  name: capi-quickstart-controlplane-0
+  labels:
+    cluster.x-k8s.io/control-plane: "true"
+    cluster.x-k8s.io/cluster-name: "capi-quickstart"
+spec:
+  version: v1.15.3
+  bootstrap:
+    configRef:
+      apiVersion: bootstrap.cluster.x-k8s.io/v1alpha2
+      kind: KubeadmConfig
+      name: capi-quickstart-controlplane-0
+  infrastructureRef:
+    apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+    kind: AWSMachine
+    name: capi-quickstart-controlplane-0
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+kind: AWSMachine
+metadata:
+  name: capi-quickstart-controlplane-0
+spec:
+  instanceType: t2.
+  iamInstanceProfile: "controllers.cluster-api-provider-aws.sigs.k8s.io"
+  sshKeyName: default
+---
+apiVersion: bootstrap.cluster.x-k8s.io/v1alpha2
+kind: KubeadmConfig
+metadata:
+  name: capi-quickstart-controlplane-0
+spec:
+  initConfiguration:
+    nodeRegistration:
+      name: '{{ ds.meta_data.hostname }}'
+      kubeletExtraArgs:
+        cloud-provider: aws
+  clusterConfiguration:
+    apiServer:
+      extraArgs:
+        cloud-provider: aws
+    controllerManager:
+      extraArgs:
+        cloud-provider: aws
+```
+{{#/tab }}
+{{#/tabs }}
+
+
+<!-- links -->
+[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
+[components]: ../reference/glossary.md#provider-components
+[kind]: https://sigs.k8s.io/kind
+
+

docs/book/theme/css/general.css

@@ -519,3 +519,68 @@ cite.literate-source > a::before {
     padding-top: 0.75em;
     padding-bottom: 0.75em;
 }
+
+.tabset > input[type="radio"] {
+  position: absolute;
+  left: -200vw;
+}
+
+.tabset .tab-panel {
+  display: none;
+}
+
+.tabset > input:first-child:checked ~ .tab-panels > .tab-panel:first-child,
+.tabset > input:nth-child(3):checked ~ .tab-panels > .tab-panel:nth-child(2),
+.tabset > input:nth-child(5):checked ~ .tab-panels > .tab-panel:nth-child(3),
+.tabset > input:nth-child(7):checked ~ .tab-panels > .tab-panel:nth-child(4),
+.tabset > input:nth-child(9):checked ~ .tab-panels > .tab-panel:nth-child(5),
+.tabset > input:nth-child(11):checked ~ .tab-panels > .tab-panel:nth-child(6) {
+  display: block;
+}
+
+.tabset > label {
+  position: relative;
+  display: inline-block;
+  padding: .6em 1em 1em;
+  border: 1px solid transparent;
+  border-bottom: 0;
+  cursor: pointer;
+  font-size: 16px;
+  border-top-right-radius: 4px;
+  border-top-left-radius: 4px;
+}
+
+.tabset > label::after {
+  content: "";
+  position: absolute;
+  left: 15px;
+  bottom: 10px;
+  width: 20px;
+  height: 4px;
+  background: #8d8d8d;
+}
+
+.tabset > label:hover,
+.tabset > input:focus + label {
+  color: #06c;
+}
+
+.tabset > label:hover::after,
+.tabset > input:focus + label::after,
+.tabset > input:checked + label::after {
+  background: #06c;
+}
+
+.tabset > input:checked + label {
+  border-color: #ccc;
+  border-bottom: 1px solid #fff;
+  margin-bottom: -1px;
+}
+
+.tab-panel {
+  padding: 1em 1.4em;
+  border: 1px solid #ccc;
+  border-bottom-right-radius: 4px;
+  border-bottom-left-radius: 4px;
+  position: relative;
+}