From 0f7dc8b7ffb3e4aae2988ad1cccad009c37213ff Mon Sep 17 00:00:00 2001 From: Vince Prignano Date: Wed, 4 Sep 2019 14:05:43 -0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96Quickstart=20/=20add=20other=20sect?= =?UTF-8?q?ions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Vince Prignano --- README.md | 2 +- docs/book/src/SUMMARY.md | 14 ++-- docs/book/src/glossary.md | 1 - .../src/providers/v1alpha1-to-v1alpha2.md} | 7 +- docs/book/src/quick-start.md | 1 - docs/book/src/reference/glossary.md | 7 +- .../src/{clusterctl => tooling}/clusterctl.md | 0 docs/book/src/tooling/tooling.md | 1 + docs/book/src/user/concepts.md | 1 + docs/book/src/user/guide.md | 1 + docs/book/src/user/quick-start.md | 70 +++++++++++++++++++ 11 files changed, 91 insertions(+), 14 deletions(-) delete mode 100644 docs/book/src/glossary.md rename docs/{developer/v1alpha1-compared-to-v1alpha2.md => book/src/providers/v1alpha1-to-v1alpha2.md} (94%) delete mode 100644 docs/book/src/quick-start.md rename docs/book/src/{clusterctl => tooling}/clusterctl.md (100%) create mode 100644 docs/book/src/tooling/tooling.md create mode 100644 docs/book/src/user/concepts.md create mode 100644 docs/book/src/user/guide.md create mode 100644 docs/book/src/user/quick-start.md diff --git a/README.md b/README.md index c68c9fa7165c..c70d9118772e 100644 --- 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 index 70a4d459903e..73ae4a95d299 100644 --- 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/architecture.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/glossary.md b/docs/book/src/glossary.md deleted file mode 100644 index ca3c8276922f..000000000000 --- a/docs/book/src/glossary.md +++ /dev/null @@ -1 +0,0 @@ -# Glossary diff --git a/docs/developer/v1alpha1-compared-to-v1alpha2.md b/docs/book/src/providers/v1alpha1-to-v1alpha2.md similarity index 94% rename from docs/developer/v1alpha1-compared-to-v1alpha2.md rename to docs/book/src/providers/v1alpha1-to-v1alpha2.md index 632212f5287d..ef429d813dfc 100644 --- a/docs/developer/v1alpha1-compared-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 deleted file mode 100644 index 05cf8c1fd04c..000000000000 --- a/docs/book/src/quick-start.md +++ /dev/null @@ -1 +0,0 @@ -# Quick Start diff --git a/docs/book/src/reference/glossary.md b/docs/book/src/reference/glossary.md index 74ea03acd008..57cadd3eabcd 100644 --- 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/clusterctl/clusterctl.md b/docs/book/src/tooling/clusterctl.md similarity index 100% rename from docs/book/src/clusterctl/clusterctl.md rename to docs/book/src/tooling/clusterctl.md diff --git a/docs/book/src/tooling/tooling.md b/docs/book/src/tooling/tooling.md new file mode 100644 index 000000000000..a07e7c8bb9a0 --- /dev/null +++ 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 new file mode 100644 index 000000000000..74d42e13cdfa --- /dev/null +++ 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 new file mode 100644 index 000000000000..cd3d452278b0 --- /dev/null +++ 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 new file mode 100644 index 000000000000..1d0aa6fbd610 --- /dev/null +++ b/docs/book/src/user/quick-start.md @@ -0,0 +1,70 @@ +# 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_. + + + +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](https://sigs.k8s.io/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. + + +[components]: ../reference/glossary.md#provider-components