Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Add quick start for the Docker provider #1484

Merged
merged 1 commit into from
Oct 16, 2019
Merged

docs: Add quick start for the Docker provider #1484

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 79 additions & 7 deletions docs/book/src/tasks/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,82 @@ 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}}

<aside class="note warning">

<h1>Warning</h1>

[kind] is not designed for production use, and is intended for development environments only.

</aside>

```bash
kind create cluster --name=clusterapi
export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
```
{{#/tab }}
{{#tab Docker}}

<aside class="note warning">

<h1>Warning</h1>

[kind] is not designed for production use and is intended for development environments only
[kind] is not designed for production use, and is intended for development environments only.

</aside>

<aside class="note warning">

<h1>Warning</h1>

The Docker provider is not designed for production use and is intended for development environments only.

</aside>

<aside class="note warning">

<h1>Docker Provider on MacOS</h1>

Instructions for using the Docker 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}}

<aside class="note warning">

<h1>Warning</h1>

[kind] is not designed for production use, and is intended for development environments only.

</aside>

```bash
kind create cluster --name=clusterapi
export KUBECONFIG="$(kind get kubeconfig-path --name="clusterapi")"
```
{{#/tab }}
{{#/tabs }}


2. **Existing Management Cluster**

For production use-cases a "real" kubernetes cluster should be used with apropriate backup and DR policies and procedures in place.
Expand All @@ -32,7 +95,7 @@ For production use-cases a "real" kubernetes cluster should be used with apropri
export KUBECONFIG=<...>
```

3. Pivoting
3. **Pivoting**

Pivoting is the process of taking an initial kind cluster to create a new workload cluster, and then converting the workload cluster into a management cluster by migrating the Cluster API CRD's.

Expand Down Expand Up @@ -64,7 +127,7 @@ kubectl create -f {{#releaselink gomodule:"sigs.k8s.io/cluster-api-bootstrap-pro

#### Install Infrastructure Provider

{{#tabs name:"tab-installation-infrastructure" tabs:"AWS,vSphere"}}
{{#tabs name:"tab-installation-infrastructure" tabs:"AWS,Docker,vSphere"}}
{{#tab AWS}}

<aside class="note warning">
Expand Down Expand Up @@ -95,6 +158,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}}

Expand Down
177 changes: 156 additions & 21 deletions docs/book/src/user/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,16 @@

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].
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")"
```


{{#include ../tasks/installation.md}}


## Usage

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,vSphere"}}
{{#tabs name:"tab-usage-cluster-resource" tabs:"AWS,Docker,vSphere"}}
{{#tab AWS}}

```yaml
Expand Down Expand Up @@ -51,6 +39,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">
Expand Down Expand Up @@ -102,7 +112,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
Expand Down Expand Up @@ -157,6 +167,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%
dlipovetsky marked this conversation as resolved.
Show resolved Hide resolved
clusterConfiguration:
controllerManager:
extraArgs:
# Enables dynamic storage provisioning without a cloud provider.
# Appropriate for testing or development only.
enable-hostpath-provisioner: "true"
dlipovetsky marked this conversation as resolved.
Show resolved Hide resolved
```
{{#/tab }}
{{#tab vSphere}}

<aside class="note warning">
Expand Down Expand Up @@ -277,6 +335,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:
dlipovetsky marked this conversation as resolved.
Show resolved Hide resolved

```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 }}

Expand All @@ -289,7 +367,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
Expand Down Expand Up @@ -355,6 +433,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: {}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yuck, I'm wondering if we should make some of these fields optional rather than required.

---
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}}

Expand Down Expand Up @@ -449,10 +590,4 @@ spec:
{{#/tabs }}

<!-- links -->
[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
[components]: ../reference/glossary.md#provider-components
[kind]: https://sigs.k8s.io/kind
[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