Skip to content

Commit eea1679

Browse files
fabriziopandinifabriziopandini
committed
first iteration on clusterctl docs
1 parent c246f9b commit eea1679

14 files changed

+873
-58
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,17 @@
88
- [Certificate Management](./tasks/certs/index.md)
99
- [Using Custom Certificates](./tasks/certs/using-custom-certificates.md)
1010
- [Generating a Kubeconfig](./tasks/certs/generate-kubeconfig.md)
11+
- [clusterctl CLI](./clusterctl/overview.md)
12+
- [clusterctl Commands](clusterctl/commands/commands.md)
13+
- [init](clusterctl/commands/init.md)
14+
- [config cluster](clusterctl/commands/config-cluster.md)
15+
- [move](./clusterctl/commands/move.md)
16+
- [adopt](clusterctl/commands/adopt.md)
17+
- [upgrade](clusterctl/commands/upgrade.md)
18+
- [delete](clusterctl/commands/delete.md)
19+
- [clusterctl Configuration](clusterctl/configuration.md)
20+
- [clusterctl Provider Contract](clusterctl/provider-contract.md)
21+
- [clusterctl for Developers](clusterctl/developers.md)
1122
- [Developer Guide](./architecture/developer-guide.md)
1223
- [Repository Layout](./architecture/repository-layout.md)
1324
- [Rapid iterative development with Tilt](./developer/tilt.md)
@@ -33,6 +44,5 @@
3344
- [Reference](./reference/reference.md)
3445
- [Glossary](./reference/glossary.md)
3546
- [Provider List](./reference/providers.md)
36-
- [clusterctl CLI](./tooling/clusterctl.md)
3747
- [Code of Conduct](./code-of-conduct.md)
3848
- [Contributing](./CONTRIBUTING.md)

‎docs/book/src/clusterctl/command-init.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# init

‎docs/book/src/clusterctl/commands/adopt.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# clusterctl adopt

‎docs/book/src/clusterctl/commands/commands.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# clusterctl Commands
2+
3+
* [`clusterctl init`](init.md)
4+
* [`clusterctl config cluster`](config-cluster.md)
5+
* [`clusterctl move`](move.md)
6+
* [`clusterctl adopt`](adopt.md)
7+
* [`clusterctl upgrade`](upgrade.md)
8+
* [`clusterctl delete`](delete.md)
9+
10+
11+

‎docs/book/src/clusterctl/commands/config-cluster.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# clusterctl config cluster

‎docs/book/src/clusterctl/commands/delete.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# clusterctl delete

‎docs/book/src/clusterctl/commands/init.md

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# clusterctl init
2+
3+
The `clusterctl init` command installs the Cluster API components and transforms the Kubernetes cluster
4+
into a management cluster.
5+
6+
This document provides more detail on how `clusterctl init` works and on the supported options for customizing your
7+
management cluster.
8+
9+
## Defining the management cluster
10+
11+
The `clusterctl init` command accepts in input a list of providers to install.
12+
13+
<aside class="note">
14+
15+
<h1> Which providers can I use? </h1>
16+
17+
You can use the `clusterctl config providers` command to get the list of supported providers.
18+
19+
If the provider of your choice is missing, you can customize the list of supported providers by using the
20+
[clusterctl configuration](../configuration.md) file.
21+
22+
</aside>
23+
24+
#### Automatically installed providers
25+
26+
The `clusterctl init` command automatically adds the Cluster API core provider and
27+
the kubeadm bootstrap provider to the list of providers to install. This allows users to use a concise command syntax for initializing a management cluster. e.g.
28+
use the command:
29+
30+
`clusterctl init --infrastracture aws`
31+
32+
To install the `aws` infrastructure provider, the Cluster API core provider and the kubeadm bootstrap provider
33+
34+
<aside class="note warning">
35+
36+
<h1> Warning </h1>
37+
38+
The Cluster API core provider and the kubeadm bootstrap provider are automatically installed only if:
39+
- The user doesn't explicitly require to install a core/bootstrap provider using the `--core` or the `-bootstrap` flags;
40+
- There is not another instance of core provider/bootstrap provider already installed in the cluster;
41+
42+
Please note that the second rule allows to execute `clusterctl init` more times: the first call actually initializes
43+
the management cluster, while the subsequent calls can be used to add more providers.
44+
45+
</aside>
46+
47+
48+
#### Provider version
49+
50+
The `clusterctl init` command by default installs the latest version available for each selected provider.
51+
52+
<aside class="note">
53+
54+
<h1> Is it possible to install a specific version of a provider? </h1>
55+
56+
You can specify the provider version by appending a version tag to the provider name, e.g. `aws:v0.4.1`.
57+
58+
</aside>
59+
60+
#### Target namespace
61+
62+
The `clusterctl init` command by default installs each provider in the default target namespace defined by each provider, e.g. `capi-system` for the Cluster API core provider.
63+
64+
See the provider documentation for more details.
65+
66+
<aside class="note">
67+
68+
<h1> Is it possible to change the target namespace ? </h1>
69+
70+
You can specify the target namespace by using the `--target-namespace` flag.
71+
72+
Please, note that the `--target-namespace` flag applies to all the providers to be installed during a `clusterctl init` operation.
73+
74+
</aside>
75+
76+
<aside class="note warning">
77+
78+
<h1>Warning</h1>
79+
80+
The `clusterctl init` command forbids users from installing two instances of the *same* provider in the
81+
same target namespace.
82+
83+
</aside>
84+
85+
#### Watching namespace
86+
87+
The `clusterctl init` command by default installs each provider configured for watching objects in all namespaces.
88+
89+
<aside class="note">
90+
91+
<h1> Is it possible to change the watching namespace ? </h1>
92+
93+
You can specify the target namespace by using the `--watching-namespace` flag.
94+
95+
Please, note that the `--watching-namespace` flag applies to all the providers to be installed during a `clusterctl init` operation.
96+
97+
</aside>
98+
99+
<aside class="note warning">
100+
101+
<h1>Warning</h1>
102+
103+
The `clusterctl init` command forbids users from installing two instances of the *same* provider watching for objects in the
104+
same namespace.
105+
106+
</aside>
107+
108+
#### Multi-tenancy
109+
110+
*Multi-tenancy* for Cluster API means a management cluster where multiple instances of the same provider are installed.
111+
112+
The user can achieve multi-tenancy configurations with `clusterctl` by a combination of:
113+
114+
- Multiple calls to `clusterctl init`;
115+
- Usage of the `--target-namespace` flag;
116+
- Usage of the `--watching-namespace` flag;
117+
118+
The `clusterctl` command officially supports the following multi-tenancy configurations:
119+
120+
{{#tabs name:"tab-multi-tenancy" tabs:"n-Infra, n-Core"}}
121+
{{#tab n-Infra}}
122+
A management cluster with <em>n (n>1)</em> instances of an infrastructure provider, and <em>only one</em> instance
123+
of Cluster API core provider, bootstrap provider and control plane provider (optional).
124+
125+
For example:
126+
127+
* Cluster API core provider installed in the `capi-system` namespace, watching objects in all namespaces;
128+
* The kubeadm bootstrap provider in `capbpk-system`, watching all namespaces;
129+
* The kubeadm control plane provider in `cacpk-system`, watching all namespaces;
130+
* The `aws` infrastructure provider in `aws-system1`, watching objects in `aws-system1` only;
131+
* The `aws` infrastructure provider in `aws-system2`, watching objects in `aws-system2` only;
132+
* etc. (more instances of the `aws` provider)
133+
134+
{{#/tab }}
135+
{{#tab n-Core}}
136+
A management cluster with <em>n (n>1)</em> instances of the Cluster API core provider, each one with <em>a dedicated</em>
137+
instance of infrastructure provider, bootstrap provider, and control plane provider (optional).
138+
139+
For example:
140+
141+
* A Cluster API core provider installed in the `capi-system1` namespace, watching objects in `capi-system1` only, and with:
142+
* The kubeadm bootstrap provider in `capi-system1`, watching `capi-system1`;
143+
* The kubeadm control plane provider in `capi-system1`, watching `capi-system1`;
144+
* The `aws` infrastructure provider in `capi-system1`, watching objects `capi-system1`;
145+
* A Cluster API core provider installed in the `capi-system2` namespace, watching objects in `capi-system2` only, and with:
146+
* The kubeadm bootstrap provider in `capi-system2`, watching `capi-system2`;
147+
* The kubeadm control plane provider in `capi-system2`, watching `capi-system2`;
148+
* The `aws` infrastructure provider in `capi-system2`, watching objects `capi-system2`;
149+
* etc. (more instances of the Cluster API core provider and the dedicated providers)
150+
151+
152+
{{#/tab }}
153+
{{#/tabs }}
154+
155+
156+
<aside class="note warning">
157+
158+
<h1>Warning</h1>
159+
160+
It is possible to achieve many other different configurations of multi-tenancy with `clusterctl`.
161+
162+
However, the user should be aware that configurations not listed above are not verified by the `clusterctl`tests
163+
and support will be provided at best effort only.
164+
165+
</aside>
166+
167+
168+
## Provider repositories
169+
170+
To access provider specific information, such as the components YAML to be used for installing a provider,
171+
`clusterctl init` accesses the **provider repositories**, that are well-known places where the release assets for
172+
a provider are published.
173+
174+
See [clusterctl configuration](../configuration.md) for more info about provider repository configurations.
175+
176+
<aside class="note">
177+
178+
<h1> Is it possible to override files read from a provider repository? </h1>
179+
180+
If, for any reasons, the user wants to replace the assets available on a provider repository with a locally available asset,
181+
the user is required to save the file under `$HOME/.cluster-api/overrides/<provider-name>/<version>/<file-name.yaml>`.
182+
183+
</aside>
184+
185+
## Variable substitution
186+
Providers can use variables in the components YAML published in the provider's repository.
187+
188+
During `clusterctl init`, those variables are replaced with environment variables or with variables read from the
189+
[clusterctl configuration](../configuration.md).
190+
191+
<aside class="note warning">
192+
193+
<h1> Action Required </h1>
194+
195+
The user should ensure the variables required by a provider are set in advance.
196+
197+
</aside>
198+
199+
<aside class="note">
200+
201+
<h1> How can I known which variables a provider requires? </h1>
202+
203+
Users can refer to the provider documentation for the list of variables to be set or use the
204+
`clusterctl config provider <provider-name>` command to get a list of expected variable names.
205+
206+
</aside>
207+
208+
## Additional information
209+
210+
When installing a provider, the `clusterctl init` command executes a set of steps to simplify
211+
the lifecycle management of the provider's components.
212+
213+
* All the provider's components are labeled, so they can be easily identified in
214+
subsequent moments of the provider's lifecycle, e.g. upgrades.
215+
216+
```bash
217+
labels:
218+
- clusterctl.cluster.x-k8s.io: ""
219+
- clusterctl.cluster.x-k8s.io/provider: "<provider-name>"
220+
```
221+
222+
* An additional `Provider` object is created in the target namespace where the provider is installed.
223+
This object keeps track of the provider version, the watching namespace, and other useful information
224+
for the inventory of the providers currently installed in the management cluster.
225+
226+
<aside class="note warning">
227+
228+
<h1>Warning</h1>
229+
230+
The `clusterctl.cluster.x-k8s.io` labels and the `Provider` objects MUST NOT altered.
231+
If this happens, there are no guarantees about the proper functioning of `clusterctl`.
232+
233+
</aside>

‎docs/book/src/clusterctl/commands/move.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# clusterctl move

‎docs/book/src/clusterctl/commands/upgrade.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# clusterctl

‎docs/book/src/clusterctl/configuration.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# clusterctl Configuration File
2+
3+
The `clusterctl` config file is located at `$HOME/.cluster-api/clusterctl.yaml` and it can be used to:
4+
5+
- Customize the list of providers and provider repositories.
6+
- Provide configuration values to be used for variable substitution when installing providers or creating clusters.
7+
8+
## Provider repositories
9+
10+
The `clusterctl` CLI is designed to work with providers implementing the [clusterct Provider Contract](contract.md).
11+
12+
Each provider is expected to define a provider repository, a well-known place where release assets are published.
13+
14+
By default, `clusterctl` ships with providers sponsored by SIG Cluster Lifecycle.
15+
16+
Users can customize the list of available providers using the `clusterctl` configuration file, as shown in the following example:
17+
18+
```yaml
19+
providers:
20+
# add a custom provider
21+
- name: "my-infra-provider"
22+
url: "https://github.com/myorg/myrepo/releases/latest/infrastructure_components.yaml"
23+
type: "InfrastructureProvider"
24+
# override a pre-defined provider
25+
- name: "cluster-api"
26+
url: "https://github.com/myorg/myforkofclusterapi/releases/latest/core_components.yaml"
27+
type: "CoreProvider"
28+
```
29+
30+
## Variables
31+
32+
When installing a provider `clusterctl` reads a YAML file that is published in the provider repository; while executing
33+
this operation, `clusterctl` can substitute certain variables with the ones provided by the user.
34+
35+
The same mechanism also applies when `clusterctl` reads the cluster templates YAML published in the repository, e.g.
36+
when injecting the Kubernetes version to use, or the number of worker machines to create.
37+
38+
The user can provide values using OS environment variables, but it is also possible to add
39+
variables in the `clusterctl` config file:
40+
41+
```yaml
42+
# Values for environment variable substitution
43+
AWS_B64ENCODED_CREDENTIALS: XXXXXXXX
44+
```
45+
46+
In case a variable is defined both in the config file and as an OS environment variable, the latter takes precedence.

0 commit comments

Comments
 (0)