Skip to content

Commit c6d1ccc

Browse files
chrisdoherty4chrisdoherty4
authored
Merge pull request #202 from jacobweinstock/quick-start-update
2 parents 58e5c57 + 8c4df82 commit c6d1ccc

File tree

1 file changed

+10
-137
lines changed

1 file changed

+10
-137
lines changed

‎docs/QUICK-START.md

Lines changed: 10 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -7,142 +7,25 @@ In this tutorial we’ll cover the basics of how to use Cluster API to create on
77
### Prerequisites
88

99
- Install and setup [kubectl] in your local environment
10-
- Install [Kind] and [Docker]
11-
- An existing [Tinkerbell] installation running at least versions mentioned in v0.6.0 of [sandbox](https://github.com/tinkerbell/sandbox/tree/v0.6.0), this guide assumes deployment using the sandbox with an IP address of 192.168.1.1, so modifications will be needed if Tinkerbell was deployed with a different method or if the IP address is different.
12-
13-
### Install and/or configure a Kubernetes cluster
14-
15-
Cluster API requires an existing Kubernetes cluster accessible via kubectl. During the installation process the
16-
Kubernetes cluster will be transformed into a [management cluster] by installing the Cluster API [provider components], so it
17-
is recommended to keep it separated from any application workload.
18-
19-
It is a common practice to create a temporary, local bootstrap cluster which is then used to provision
20-
a target [management cluster] on the selected [infrastructure provider].
21-
22-
Choose one of the options below:
23-
24-
1. **Existing Management Cluster**
25-
26-
For production use-cases a "real" Kubernetes cluster should be used with appropriate backup and DR policies and procedures in place. The Kubernetes cluster must be at least v1.19.1.
27-
28-
```bash
29-
export KUBECONFIG=<...>
30-
```
31-
32-
2. **Kind**
33-
34-
**NOTE** [kind] is not designed for production use.
35-
36-
**Minimum [kind] supported version**: v0.9.0
37-
38-
[kind] can be used for creating a local Kubernetes cluster for development environments or for
39-
the creation of a temporary [bootstrap cluster] used to provision a target [management cluster] on the selected infrastructure provider.
40-
41-
Create the kind cluster:
42-
43-
```bash
44-
kind create cluster
45-
```
46-
47-
Test to ensure the local kind cluster is ready:
48-
49-
```
50-
kubectl cluster-info
51-
```
52-
53-
### Install clusterctl
54-
55-
The clusterctl CLI tool handles the lifecycle of a Cluster API management cluster.
56-
57-
#### Install clusterctl binary with curl on linux
58-
59-
Download the latest release; on linux, type:
60-
61-
```
62-
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.0.0/clusterctl-linux-amd64 -o clusterctl
63-
```
64-
65-
Make the clusterctl binary executable.
66-
67-
```
68-
chmod +x ./clusterctl
69-
```
70-
71-
Move the binary in to your PATH.
72-
73-
```
74-
sudo mv ./clusterctl /usr/local/bin/clusterctl
75-
```
76-
77-
Test to ensure the version you installed is up-to-date:
78-
79-
```
80-
clusterctl version
81-
```
82-
83-
#### Install clusterctl binary with curl on macOS
84-
85-
Download the latest release; on macOS, type:
86-
87-
```
88-
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.0.0/clusterctl-darwin-amd64 -o clusterctl
89-
```
90-
91-
Or if your Mac has an M1 CPU ("Apple Silicon"):
92-
93-
```
94-
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.0.0/clusterctl-darwin-arm64 -o clusterctl
95-
```
96-
97-
Make the clusterctl binary executable.
98-
99-
```
100-
chmod +x ./clusterctl
101-
```
102-
103-
Move the binary in to your PATH.
104-
105-
```
106-
sudo mv ./clusterctl /usr/local/bin/clusterctl
107-
```
108-
109-
Test to ensure the version you installed is up-to-date:
110-
111-
```
112-
clusterctl version
113-
```
114-
115-
#### Install clusterctl with homebrew on macOS and linux
116-
117-
Install the latest release using homebrew:
118-
119-
```bash
120-
brew install clusterctl
121-
```
122-
123-
Test to ensure the version you installed is up-to-date:
124-
125-
```
126-
clusterctl version
127-
```
10+
- Install [clusterctl]
11+
- Tinkerbell stack with all services using a kubernetes backend. *Full docs for this don't exist yet. These docs are scheduled to be included in the v0.3.0 release.*
12812

12913
### Initialize the management cluster
13014

13115
Now that we've got clusterctl installed and all the prerequisites in place, let's transform the Kubernetes cluster
132-
into a management cluster by using `clusterctl init`.
16+
into a management cluster by using `clusterctl init`. This only needs to be run once.
13317

13418
The command accepts as input a list of providers to install; when executed for the first time, `clusterctl init`
13519
automatically adds to the list the `cluster-api` core provider, and if unspecified, it also adds the `kubeadm` bootstrap
13620
and `kubeadm` control-plane providers.
13721

138-
#### Initialization for the Tinkerbell provider
22+
`clusterctl` doesn't include the Tinkerbell CAPI provider (CAPT) so we need to configure this:
13923

14024
```sh
141-
# Let clusterctl know about the Tinkerbell provider
14225
cat >> ~/.cluster-api/clusterctl.yaml <<EOF
14326
providers:
14427
- name: "tinkerbell"
145-
url: "https://github.com/tinkerbell/cluster-api-provider-tinkerbell/releases/latest/infrastructure-components.yaml"
28+
url: "https://github.com/tinkerbell/cluster-api-provider-tinkerbell/releases/download/v0.1.0/infrastructure-components.yaml"
14629
type: "InfrastructureProvider"
14730
EOF
14831

@@ -243,7 +126,7 @@ before configuring a cluster with Cluster API. Instructions are provided for the
243126
Otherwise, you can look at the `clusterctl generate cluster` [command][clusterctl generate cluster] documentation for details about how to
244127
discover the list of variables required by a cluster templates.
245128

246-
To see all required OpenStack environment variables execute:
129+
To see all required Tinkerbell environment variables execute:
247130

248131
```bash
249132
clusterctl generate cluster --infrastructure tinkerbell --list-variables capi-quickstart
@@ -392,26 +275,16 @@ kubectl delete cluster capi-quickstart
392275

393276
**NOTE** IMPORTANT: In order to ensure a proper cleanup of your infrastructure you must always delete the cluster object. Deleting the entire cluster template with `kubectl delete -f capi-quickstart.yaml` might lead to pending resources to be cleaned up manually.
394277

395-
Delete management cluster
396-
397-
```bash
398-
kind delete cluster
399-
```
400-
401-
## Next steps
402-
403-
See the [clusterctl] documentation for more detail about clusterctl supported actions.
404-
405278
<!-- links -->
406279
[bootstrap cluster]: https://cluster-api.sigs.k8s.io/reference/glossary.html#bootstrap-cluster
407280
[clusterctl generate cluster]: https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html
408281
[clusterctl get kubeconfig]: https://cluster-api.sigs.k8s.io/clusterctl/commands/get-kubeconfig.html
409-
[clusterctl]: https://cluster-api.sigs.k8s.io/clusterctl/overview.html
410-
[Docker]: https://www.docker.com/
282+
[clusterctl]: https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl
283+
[Docker]: https://docs.docker.com/get-docker/
411284
[infrastructure provider]: https://cluster-api.sigs.k8s.io/reference/glossary.html#infrastructure-provider
412-
[kind]: https://kind.sigs.k8s.io/
285+
[kind]: https://kind.sigs.k8s.io/docs/user/quick-start
413286
[KubeadmControlPlane]: https://cluster-api.sigs.k8s.io/developer/architecture/controllers/control-plane.html
414-
[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
287+
[kubectl]: https://kubernetes.io/docs/tasks/tools/#kubectl
415288
[management cluster]: https://cluster-api.sigs.k8s.io/reference/glossary.html#management-cluster
416289
[provider]: https://cluster-api.sigs.k8s.io/reference/providers.html
417290
[provider components]: https://cluster-api.sigs.k8s.io/reference/glossary.html#provider-components

0 commit comments

Comments
 (0)