📖 Add quick start for the Docker provider

Signed-off-by: Daniel Lipovetsky <dlipovetsky@d2iq.com>
kubernetes-sigs · Oct 15, 2019 · 168321f · 168321f
1 parent 20da46b
commit 168321f
Show file tree

Hide file tree

Showing 2 changed files with 258 additions and 17 deletions.
diff --git a/docs/book/src/tasks/installation.md b/docs/book/src/tasks/installation.md
@@ -11,10 +11,56 @@ Cluster API requires an existing kubernetes cluster accessible via kubectl, choo
 
 1. **Kind**
 
-```bash
-kind create cluster --name=clusterapi
-export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
-```
+{{#tabs name:"kind-cluster" tabs:"AWS,Docker,vSphere"}}
+{{#tab AWS}}
+
+  ```bash
+  kind create cluster --name=clusterapi
+  export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
+  ```
+{{#/tab }}
+{{#tab Docker}}
+
+<aside class="note warning">
+
+<h1>Not Intended For Production</h1>
+
+Because it requires no external infrastructure, the Docker provider allows you to quickly try Cluster API. It is also useful for developing Cluster API, and tooling that uses it. **Running a production cluster using the Docker provider is not supported**.
+
+</aside>
+
+<aside class="note warning">
+
+<h1>Docker on MacOS</h1>
+
+Instructions for using the Docker infra provider on MacOS will be added soon.
+
+</aside>
+
+  Because the Docker provider needs to access Docker on the host, a custom kind cluster configuration is required:
+
+  ```bash
+  cat > kind-cluster-with-extramounts.yaml <<EOF
+kind: Cluster
+apiVersion: kind.sigs.k8s.io/v1alpha3
+nodes:
+  - role: control-plane
+    extraMounts:
+      - hostPath: /var/run/docker.sock
+        containerPath: /var/run/docker.sock
+EOF
+  kind create cluster --config ./kind-cluster-with-extramounts.yaml --name clusterapi
+  export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
+  ```
+{{#/tab }}
+{{#tab vSphere}}
+
+  ```bash
+  kind create cluster --name=clusterapi
+  export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
+  ```
+{{#/tab }}
+{{#/tabs }}
 
 <aside class="note warning">
 
@@ -95,6 +141,15 @@ curl -L {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-aws" asset:"in
   | kubectl create -f -
 ```
 
+{{#/tab }}
+{{#tab Docker}}
+
+Check the [Docker provider releases](https://github.com/kubernetes-sigs/cluster-api-provider-docker/releases) for an up-to-date components file.
+
+```bash
+kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-docker" asset:"provider_components.yaml" version:"0.2.x"}}
+```
+
 {{#/tab }}
 {{#tab vSphere}}
 

diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/user/quick-start.md
@@ -2,19 +2,53 @@
 
 In this tutorial we'll cover the basics of how to use Cluster API to create one or more Kubernetes clusters.
 
-## Prerequisites
+{{#include ../tasks/installation.md}}
 
-- Install and setup [kubectl] in your local environment.
-- A Kubernetes cluster to be used as [management cluster].
-  For the purpose of this quick start we suggest you to use [kind] as a _non production-ready_ solution.
-  ```bash
-  kind create cluster --name=clusterapi
-  export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
-  ```
+#### Install Infrastructure Provider Components
 
+{{#tabs name:"tab-installation-infrastructure" tabs:"AWS,Docker,vSphere"}}
+{{#tab AWS}}
 
-{{#include ../tasks/installation.md}}
+{{#embed-github repo:"kubernetes-sigs/cluster-api-provider-aws" path:"docs/prerequisites.md"}}
+
+##### Create the components
+
+Check the [AWS provider releases] for an up-to-date components file.
+
+```bash
+# Create the base64 encoded credentials using clusterawsadm.
+# This command uses your environment variables and encodes
+# them in a value to be stored in a Kubernetes Secret.
+export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm alpha bootstrap encode-aws-credentials)
+
+# Create the components.
+curl -L {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-aws" asset:"infrastructure-components.yaml" version:"0.4.x"}} \
+  | envsubst \
+  | kubectl create -f -
+```
+
+{{#/tab }}
+{{#tab Docker}}
 
+Check the [Docker provider releases](https://github.com/kubernetes-sigs/cluster-api-provider-docker/releases) for an up-to-date components file.
+
+```bash
+kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-docker" asset:"provider_components.yaml" version:"0.2.x"}}
+```
+
+{{#/tab }}
+{{#tab vSphere}}
+
+Check the [vSphere provider releases](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/releases) for an up-to-date components file.
+
+For more information about prerequisites, credentials management, or permissions for vSphere, visit the [getting started guide](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/master/docs/getting_started.md).
+
+```bash
+kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api-provider-vsphere" asset:"infrastructure-components.yaml" version:"0.5.x"}}
+```
+
+{{#/tab }}
+{{#/tabs }}
 
 ## Usage
 
@@ -23,7 +57,7 @@ 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,vSphere"}}
+{{#tabs name:"tab-usage-cluster-resource" tabs:"AWS,Docker,vSphere"}}
 {{#tab AWS}}
 
 ```yaml
@@ -51,6 +85,28 @@ spec:
   sshKeyName: default
 ```
 {{#/tab }}
+{{#tab Docker}}
+
+```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: DockerCluster
+    name: capi-quickstart
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+kind: DockerCluster
+metadata:
+  name: capi-quickstart
+```
+{{#/tab }}
 {{#tab vSphere}}
 
 <aside class="note warning">
@@ -102,7 +158,7 @@ spec:
 
 Now that we've created the cluster object, we can create a control plane Machine.
 
-{{#tabs name:"tab-usage-controlplane-resource" tabs:"AWS,vSphere"}}
+{{#tabs name:"tab-usage-controlplane-resource" tabs:"AWS,Docker,vSphere"}}
 {{#tab AWS}}
 
 ```yaml
@@ -157,6 +213,54 @@ spec:
         cloud-provider: aws
 ```
 {{#/tab }}
+{{#tab Docker}}
+
+```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:
+    kind: DockerMachine
+    apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+    name: capi-quickstart-controlplane-0
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+kind: DockerMachine
+metadata:
+  name: capi-quickstart-controlplane-0
+---
+apiVersion: bootstrap.cluster.x-k8s.io/v1alpha2
+kind: KubeadmConfig
+metadata:
+  name: capi-quickstart-controlplane-0
+spec:
+  initConfiguration:
+    nodeRegistration:
+      kubeletExtraArgs:
+        # Default thresholds are higher to provide a buffer before resources
+        # are completely depleted, at the cost of requiring more total
+        # resources. These low thresholds allow running with fewer resources.
+        # Appropriate for testing or development only.
+        eviction-hard: nodefs.available<0%,nodefs.inodesFree<0%,imagefs.available<0%
+  clusterConfiguration:
+    controllerManager:
+      extraArgs:
+        # Enables dynamic storage provisioning without a cloud provider.
+        # Appropriate for testing or development only.
+        enable-hostpath-provisioner: "true"
+```
+{{#/tab }}
 {{#tab vSphere}}
 
 <aside class="note warning">
@@ -277,6 +381,26 @@ kubectl --kubeconfig=./capi-quickstart.kubeconfig \
   apply -f https://docs.projectcalico.org/v3.8/manifests/calico.yaml
 ```
 
+<aside class="note warning">
+<h1>Action Required (Docker provider v0.2.0 only)</h1>
+
+A [known issue](https://github.com/kubernetes-sigs/kind/issues/891) affects Calico with the Docker provider v0.2.0. After you deploy Calico, apply this patch to work around the issue:
+
+```bash
+kubectl --kubeconfig=./capi-quickstart.kubeconfig \
+  -n kube-system patch daemonset calico-node \
+  --type=strategic --patch='
+spec:
+  template:
+    spec:
+      containers:
+      - name: calico-node
+        env:
+        - name: FELIX_IGNORELOOSERPF
+          value: "true"
+'
+```
+</aside>
 {{#/tab }}
 {{#/tabs }}
 
@@ -289,7 +413,7 @@ kubectl --kubeconfig=./capi-quickstart.kubeconfig get nodes
 
 Finishing up, we'll create a single node _MachineDeployment_.
 
-{{#tabs name:"tab-usage-machinedeployment" tabs:"AWS,vSphere"}}
+{{#tabs name:"tab-usage-machinedeployment" tabs:"AWS,Docker,vSphere"}}
 {{#tab AWS}}
 
 ```yaml
@@ -355,6 +479,69 @@ spec:
             cloud-provider: aws
 ```
 
+{{#/tab }}
+{{#tab Docker}}
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1alpha2
+kind: MachineDeployment
+metadata:
+  name: capi-quickstart-worker
+  labels:
+    cluster.x-k8s.io/cluster-name: capi-quickstart
+    # Labels beyond this point are for example purposes,
+    # feel free to add more or change with something more meaningful.
+    # Sync these values with spec.selector.matchLabels and spec.template.metadata.labels.
+    nodepool: nodepool-0
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      cluster.x-k8s.io/cluster-name: capi-quickstart
+      nodepool: nodepool-0
+  template:
+    metadata:
+      labels:
+        cluster.x-k8s.io/cluster-name: capi-quickstart
+        nodepool: nodepool-0
+    spec:
+      version: v1.15.3
+      bootstrap:
+        configRef:
+          name: capi-quickstart-worker
+          apiVersion: bootstrap.cluster.x-k8s.io/v1alpha2
+          kind: KubeadmConfigTemplate
+      infrastructureRef:
+        name: capi-quickstart-worker
+        apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+        kind: DockerMachineTemplate
+---
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+kind: DockerMachineTemplate
+metadata:
+  name: capi-quickstart-worker
+spec:
+  template:
+    spec: {}
+---
+apiVersion: bootstrap.cluster.x-k8s.io/v1alpha2
+kind: KubeadmConfigTemplate
+metadata:
+  name: capi-quickstart-worker
+spec:
+  template:
+    spec:
+      # For more information about these values,
+      # refer to the Kubeadm Bootstrap Provider documentation.
+      joinConfiguration:
+        nodeRegistration:
+          kubeletExtraArgs:
+            eviction-hard: nodefs.available<0%,nodefs.inodesFree<0%,imagefs.available<0%
+      clusterConfiguration:
+        controllerManager:
+          extraArgs:
+            enable-hostpath-provisioner: "true"
+```
 {{#/tab }}
 {{#tab vSphere}}
 
@@ -455,4 +642,3 @@ spec:
 [management cluster]: ../reference/glossary.md#management-cluster
 [target cluster]: ../reference/glossary.md#target-cluster
 [AWS provider releases]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases
-