📖Quickstart / add other sections

vincepri · vincepri · commit 66bc3fb68108 · 2019-09-05T07:54:32.000-07:00
Signed-off-by: Vince Prignano &lt;vincepri@vmware.com&gt;
diff --git a/README.md b/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?
 
diff --git a/docs/book/src/SUMMARY.md b/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)
diff --git a/docs/book/src/architecture/architecture.md b/docs/book/src/architecture/architecture.md
diff --git a/docs/book/src/architecture/developer-guide.md b/docs/book/src/architecture/developer-guide.md
@@ -0,0 +1 @@
+# Developer Guide
diff --git a/docs/book/src/glossary.md b/docs/book/src/glossary.md
diff --git a/docs/book/src/introduction.md b/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)**
diff --git a/docs/book/src/providers/v1alpha1-to-v1alpha2.md b/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.
diff --git a/docs/book/src/quick-start.md b/docs/book/src/quick-start.md
diff --git a/docs/book/src/reference/glossary.md b/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.
 
diff --git a/docs/book/src/reference/providers.md b/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)
diff --git a/docs/book/src/tooling/clusterctl.md b/docs/book/src/tooling/clusterctl.md
diff --git a/docs/book/src/tooling/tooling.md b/docs/book/src/tooling/tooling.md
@@ -0,0 +1 @@
+# Tooling
diff --git a/docs/book/src/user/concepts.md b/docs/book/src/user/concepts.md
@@ -0,0 +1 @@
+# Concepts
diff --git a/docs/book/src/user/guide.md b/docs/book/src/user/guide.md
@@ -0,0 +1 @@
+# User Guide
diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/user/quick-start.md
@@ -0,0 +1,71 @@
+# 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](https://kubernetes.io/docs/tasks/tools/install-kubectl/) in your local environment.
+- A working Kubernetes cluster to be used as [management cluster](../reference/glossary.md#management-cluster).
+
+## Before we start
+
+#### Picking Infrastructure and Bootstrap Providers
+
+The [providers section](../reference/providers.md) offers a quick reference to some providers
+available and compatible with Cluster API _v1alpha2_.
+
+<aside class="note">
+<h1>Following Along vs Jumping Ahead</h1>
+
+If you're unfamiliar with the different providers types introduced in v1alpha2
+and how they interact with each other, please refer to the [user guide concepts].
+
+[user guide concepts]: ../user/concepts.md
+</aside>
+
+To proceed, we'll need to pick and choose a _Bootstrap_ and _Infrastructure_ provider.
+Once you've chosen which provider to use, we'll need to grab the [components]
+published as part of the release.
+
+> **NB**: Providers usually have their own getting started guide on how to generate additional resources,
+> configuration, credential management, etc. Refer to their documentation before proceeding.
+
+#### What if I don't have a management cluster?
+In some cases, you might not have a Kubernetes Cluster available to be used
+as management cluster for Cluster API resources.
+
+Services like Google Cloud GKE, Amazon EKS, Azure Kuberentes Service (AKS),
+or similar, are good examples of Kubernetes-as-a-service platforms
+that can be used for this purpose.
+
+##### Testing or development
+If you're looking for a temporary cluster for testing, development, or demos,
+we suggest you to use [kind].
+
+```bash
+GO111MODULE="on" go get sigs.k8s.io/kind@v0.5.1
+kind create cluster --name=clusterapi
+export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
+```
+
+## Installation
+
+Each [release](https://github.com/kubernetes-sigs/cluster-api/releases) has a list of published assets.
+For the purpose of this tutorial, download the `cluster-api-components.yaml` file from the latest `v0.2.x` release.
+
+At this point, we should have all the required [components]:
+- Cluster API: `cluster-api-components.yaml`
+- Bootstrap: `bootstrap-components.yaml`
+- Infrastructure: `infrastructure-components.yaml`
+
+```bash
+kubectl create -f cluster-api-components.yaml
+kubectl create -f bootstrap-components.yaml
+kubectl create -f infrastructure-components.yaml
+```
+
+The Cluster API resources are now installed.
+
+<!-- links -->
+[components]: ../reference/glossary.md#provider-components
+[kind]: https://sigs.k8s.io/kind
