Skip to content

Commit 8dac15d

Browse files
fabriziopandinifabriziopandini
committed
tmp
1 parent c246f9b commit 8dac15d

File tree

10 files changed

+705
-58
lines changed

10 files changed

+705
-58
lines changed

‎docs/book/src/SUMMARY.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@
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](./clusterctl/intro.md)
12+
- [init](./clusterctl/init.md)
13+
- [move](./clusterctl/move.md)
14+
- [update](./clusterctl/update.md)
15+
- [config cluster](clusterctl/config-cluster.md)
16+
- [adopt](clusterctl/adopt.md)
17+
- [clusterctl configuration](clusterctl/configuring-clusterctl.md)
18+
- [providers contract](clusterctl/providers-contract.md)
1119
- [Developer Guide](./architecture/developer-guide.md)
1220
- [Repository Layout](./architecture/repository-layout.md)
1321
- [Rapid iterative development with Tilt](./developer/tilt.md)
@@ -33,6 +41,5 @@
3341
- [Reference](./reference/reference.md)
3442
- [Glossary](./reference/glossary.md)
3543
- [Provider List](./reference/providers.md)
36-
- [clusterctl CLI](./tooling/clusterctl.md)
3744
- [Code of Conduct](./code-of-conduct.md)
3845
- [Contributing](./CONTRIBUTING.md)

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

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

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

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

‎docs/book/src/clusterctl/configuring-clusterctl.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# The clusterctl config file
2+
3+
The clusterctl config file can be used for:
4+
5+
- Customizing the list of providers/providers repositories that an instance of clusterctl can use
6+
- Providing variables values to be used for variables substitution when installing components YAML or cluster templates
7+
8+
## Provider repositories
9+
10+
The `clusterctl` command is designed to work with all the providers implementing
11+
the [clustetrctl contract](providers-contract.md).
12+
13+
Each provider is expected to define a provider repository, that is well-known place where the release assets for
14+
a provider are published. An example of provider repository is the [Github release assets for Cluster API](https://github.com/kubernetes-sigs/cluster-api/releases).
15+
16+
The `clusterctl` command ships with a pre-defined list of provider repositories that includes all the providers implementation
17+
developed as a SIG-cluster-lifecycle project.
18+
19+
The user can change this list by adding new providers or changing the
20+
repository address for a pre-defined provider by using ....
21+
22+
## Variables
23+
24+
TODO

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

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
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 I can use? </h1>
16+
17+
You can use the `clusterctl config providers` 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](configuring-clusterctl.md) file.
21+
22+
</aside>
23+
24+
#### Automatically installed providers
25+
26+
The `clusterctl init` command automatically adds to the list of providers to install the Cluster API core provider and
27+
the kubeadm bootstrap provider. This allows tu 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 already another instance of the default core/bootstrap provider 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 that is defined in
63+
the provider's component YAML file, like e.g. `capi-system` for the Cluster API core provider.
64+
65+
See the provider documentation for more details.
66+
67+
<aside class="note">
68+
69+
<h1> Is it possible to change the target namespace ? </h1>
70+
71+
You can specify the target namespace by using the `--target-namespace` flag.
72+
73+
Please, note that the `--target-namespace` flag applies to all the providers to be installed during a `clusterctl init` operation.
74+
75+
</aside>
76+
77+
<aside class="note warning">
78+
79+
<h1>Warning</h1>
80+
81+
The `clusterctl init` command blocks users when trying to install two instances of the *same* provider in the
82+
same target namespace.
83+
84+
It is possible to override this block with the `--force` flag, but this options is intended for advanced users only.
85+
86+
</aside>
87+
88+
#### Watching namespace
89+
90+
The `clusterctl init` command by default installs each provider configured for watching objects in the default watching
91+
namespace that is defined in the provider's component YAML file, like e.g. `` (empty, all-namespaces) for the Cluster API core provider.
92+
93+
See the provider documentation for more details.
94+
95+
<aside class="note">
96+
97+
<h1> Is it possible to change the watching namespace ? </h1>
98+
99+
You can specify the target namespace by using the `--watching-namespace` flag.
100+
101+
Please, note that the `--watching-namespace` flag applies to all the providers to be installed during a `clusterctl init` operation.
102+
103+
</aside>
104+
105+
<aside class="note warning">
106+
107+
<h1>Warning</h1>
108+
109+
The `clusterctl init` command blocks users when trying to install two instances of the *same* provider watching for objects in the
110+
same namespace.
111+
112+
It is possible to override this block with the `--force` flag, but this options is intended for advanced users only.
113+
114+
</aside>
115+
116+
#### Multi-tenancy
117+
118+
With the term *multi-tenant* we indicating a management cluster where more instances of one or more providers are installed.
119+
120+
The user can achieve multi-tenancy configurations with `clusterctl` by a combination of:
121+
122+
- Multiple calls to `clusterctl init`;
123+
- Usage of the `--target-namespace` flag;
124+
- Usage of the `--watching-namespace` flag;
125+
126+
The `clusterctl` command officially supports the following multi-tenancy configurations:
127+
128+
{{#tabs name:"tab-multi-tenancy" tabs:"n-Infra, n-Core"}}
129+
{{#tab n-Infra}}
130+
A management cluster with <em>n (with n>1)</em> instances of an infrastructure provider, and <em>only one</em> instance
131+
of Cluster API core provider, bootstrap provider and control plane provider (optional).
132+
133+
For example:
134+
135+
* Cluster API core provider installed in the `capi-system` namespace, watching objects in all namespaces;
136+
* The kubeadm bootstrap provider in `capbpk-system`, watching all namespaces;
137+
* The kubeadm control plane provider in `cacpk-system`, watching all namespaces;
138+
* An `aws` infrastructure provider in `aws-system1`, watching objects in `aws-system1` only;
139+
* An `aws` infrastructure provider in `aws-system2`, watching objects in `aws-system2` only;
140+
* etc. (more instances of the `aws` provider)
141+
142+
{{#/tab }}
143+
{{#tab n-Core}}
144+
A management cluster with <em>n (with n>1)</em> instances of the Cluster API core provider, each one with <em>a dedicated</em>
145+
instance of infrastructure provider, bootstrap provider, and control plane provider (optional.
146+
147+
For example:
148+
149+
* A Cluster API core provider installed in the `capi-system1` namespace, watching objects in `capi-system1` only with a dedicated:
150+
* kubeadm bootstrap provider in `capi-system1`, watching `capi-system1`;
151+
* kubeadm control plane provider in `capi-system1`, watching `capi-system1`;
152+
* `aws` infrastructure provider in `capi-system1`, watching objects `capi-system1`;
153+
* A Cluster API core provider installed in the `capi-system2` namespace, watching objects in `capi-system2` only with a dedicated:
154+
* kubeadm bootstrap provider in `capi-system2`, watching `capi-system2`;
155+
* kubeadm control plane provider in `capi-system2`, watching `capi-system2`;
156+
* `aws` infrastructure provider in `capi-system2`, watching objects `capi-system2`;
157+
* etc. (more instances of the Cluster API core provider and the dedicated providers)
158+
159+
160+
{{#/tab }}
161+
{{#/tabs }}
162+
163+
164+
<aside class="note warning">
165+
166+
<h1>Warning</h1>
167+
168+
It is possible to achieve many other different configurations of multi-tenancy with `clusterctl`.
169+
170+
However, the user should be aware that configurations not listed above are not verified by the clusterctl tests
171+
and support will be provided at best effort only.
172+
173+
</aside>
174+
175+
176+
## Provider repositories
177+
178+
In order to access provider specific information, like the components YAML to be used for installing a provider,
179+
`clusterctl init` access the **provider repositories**, that are well-known place where the release assets for
180+
a provider are published.
181+
182+
See the [clusterctl configuration](configuring-clusterctl.md) for more info about provider's repository configurations.
183+
184+
<aside class="note">
185+
186+
<h1> Is it possible to override files read from a provider repository? </h1>
187+
188+
<aside class="note warning">
189+
190+
<h1>Warning</h1>
191+
192+
This feature is intended for advanced users.
193+
194+
</aside>
195+
196+
If, for any reasons, the user wants to replace the assets available on a provider repository with a locally available asset,
197+
the user is required to save the file under `$HOME\cluster-api\overrides\<provider-name>\<version>\<file-name.yaml>`.
198+
199+
</aside>
200+
201+
## Variable substitution
202+
Providers can use variables into the components YAML published in the provider's repository.
203+
204+
During `clusterctl init`, those variables will be replace with environment variables or with variables read from the
205+
[clusterctl configuration](configuring-clusterctl.md).
206+
207+
<aside class="note warning">
208+
209+
<h1> Action Required </h1>
210+
211+
The user should ensure the variables required by a provider are set in advance.
212+
213+
</aside>
214+
215+
<aside class="note">
216+
217+
<h1> How can I known which variables a provider requires? </h1>
218+
219+
Users can refer to the provider documentation for the list of variables to be set or use the
220+
`clusterctl config provider <provider-name>` command to get a list of expected variable names.
221+
222+
</aside>
223+
224+
## Additional information
225+
226+
When installing a provider the `clusterctl init` command takes following additional steps in order to simplify
227+
the management of lifecycle of the provider's components.
228+
229+
* All the provider's components are labeled, so they can be easily identified in
230+
subsequent moments of the provider's lifecycle, e.g. for upgrades. Applied labels are:
231+
- `clusterctl.cluster.x-k8s.io`
232+
- `clusterctl.cluster.x-k8s.io/provider=<provider-name>`
233+
234+
* An additional `Provider` object is created in the target namespace where the provider is installed.
235+
This objects keeps track of the provider version, of the watching namespace and other useful information
236+
for the inventory of the providers currently installed in the management cluster.
237+
238+
<aside class="note warning">
239+
240+
<h1>Warning</h1>
241+
242+
The `clusterctl.cluster.x-k8s.io` labels and the `Provider` objects MUST NOT altered.
243+
If this happen, there are no guarantees about the proper functioning of `clusterctl`.
244+
245+
</aside>

0 commit comments

Comments
 (0)