tmp

docs/book/src/SUMMARY.md

@@ -8,6 +8,14 @@
     - [Certificate Management](./tasks/certs/index.md)
         - [Using Custom Certificates](./tasks/certs/using-custom-certificates.md)
         - [Generating a Kubeconfig](./tasks/certs/generate-kubeconfig.md)
+- [clusterctl](./clusterctl/intro.md)
+    - [init](./clusterctl/init.md)
+    - [move](./clusterctl/move.md)
+    - [update](./clusterctl/update.md)
+    - [config cluster](clusterctl/config-cluster.md)
+    - [adopt](clusterctl/adopt.md)
+    - [clusterctl configuration](clusterctl/configuring-clusterctl.md)
+    - [providers contract](clusterctl/providers-contract.md)
 - [Developer Guide](./architecture/developer-guide.md)
     - [Repository Layout](./architecture/repository-layout.md)
     - [Rapid iterative development with Tilt](./developer/tilt.md)
@@ -33,6 +41,5 @@
 - [Reference](./reference/reference.md)
     - [Glossary](./reference/glossary.md)
     - [Provider List](./reference/providers.md)
-    - [clusterctl CLI](./tooling/clusterctl.md)
     - [Code of Conduct](./code-of-conduct.md)
     - [Contributing](./CONTRIBUTING.md)

docs/book/src/clusterctl/adopt.md

@@ -0,0 +1 @@
+TODO

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

@@ -0,0 +1 @@
+TODO

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

@@ -0,0 +1,24 @@
+# The clusterctl config file
+
+The clusterctl config file can be used for:
+
+- Customizing the list of providers/providers repositories that an instance of clusterctl can use
+- Providing variables values to be used for variables substitution when installing components YAML or cluster templates 
+
+## Provider repositories
+
+The `clusterctl` command is designed to work with all the providers implementing
+the [clustetrctl contract](providers-contract.md).
+
+Each provider is expected to define a provider repository, that is well-known place where the release assets for 
+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).
+
+The `clusterctl` command ships with a pre-defined list of provider repositories that includes all the providers implementation 
+developed as a SIG-cluster-lifecycle project. 
+
+The user can change this list by adding new providers or changing the
+repository address for a pre-defined provider by using ....
+
+## Variables
+
+TODO

docs/book/src/clusterctl/init.md

@@ -0,0 +1,245 @@
+# clusterctl init
+
+The `clusterctl init` command installs the cluster-API components and transforms the Kubernetes cluster
+into a management cluster.
+
+This document provides more detail on how `clusterctl init` works and on the supported options for customizing your
+management cluster.
+
+## Defining the management cluster 
+
+The `clusterctl init` command accepts in input a list of providers to install.
+
+<aside class="note">
+
+<h1> Which providers I can use? </h1>
+
+You can use the `clusterctl config providers` to get the list of supported providers.
+
+If the provider of your choice is missing, you can customize the list of supported providers by using the
+[clusterctl configuration](configuring-clusterctl.md) file. 
+
+</aside>
+
+#### Automatically installed providers
+
+The `clusterctl init` command automatically adds to the list of providers to install the Cluster API core provider and
+the kubeadm bootstrap provider. This allows tu use a concise command syntax for initializing a management cluster. e.g.
+use the command:
+
+`clusterctl init --infrastracture aws`
+
+To install the `aws` infrastructure provider, the Cluster API core provider and the kubeadm bootstrap provider
+
+<aside class="note warning">
+
+<h1> Warning </h1>
+
+The Cluster API core provider and the kubeadm bootstrap provider are automatically installed only if:
+- The user doesn't explicitly require to install a core/bootstrap provider using the `--core` or the `-bootstrap` flags;
+- There is not already another instance of the default core/bootstrap provider installed in the cluster;
+
+Please note that the second rule allows to execute `clusterctl init` more times: the first call actually initializes
+the management cluster, while the subsequent calls can be used to add more providers.
+
+</aside>
+
+
+#### Provider version
+
+The `clusterctl init` command by default installs the latest version available for each selected provider.
+
+<aside class="note">
+
+<h1> Is it possible to install a specific version of a provider? </h1>
+
+You can specify the provider version by appending a version tag to the provider name, e.g. `aws:v0.4.1`.
+
+</aside>
+
+#### Target namespace
+
+The `clusterctl init` command by default installs each provider in the default target namespace that is defined in
+the provider's component YAML file, like e.g. `capi-system` for the Cluster API core provider. 
+
+See the provider documentation for more details.
+
+<aside class="note">
+
+<h1> Is it possible to change the target namespace ? </h1>
+
+You can specify the target namespace by using the `--target-namespace` flag.
+
+Please, note that the `--target-namespace` flag applies to all the providers to be installed during a `clusterctl init` operation.
+
+</aside>
+
+<aside class="note warning">
+
+<h1>Warning</h1>
+
+The `clusterctl init` command blocks users when trying to install two instances of the *same* provider in the
+same target namespace.
+
+It is possible to override this block with the `--force` flag, but this options is intended for advanced users only.
+
+</aside>
+
+#### Watching namespace
+
+The `clusterctl init` command by default installs each provider configured for watching objects in the default watching
+namespace that is defined in the provider's component YAML file, like e.g. `` (empty, all-namespaces) for the Cluster API core provider. 
+
+See the provider documentation for more details.
+
+<aside class="note">
+
+<h1> Is it possible to change the watching namespace ? </h1>
+
+You can specify the target namespace by using the `--watching-namespace` flag.
+
+Please, note that the `--watching-namespace` flag applies to all the providers to be installed during a `clusterctl init` operation.
+
+</aside>
+
+<aside class="note warning">
+
+<h1>Warning</h1>
+
+The `clusterctl init` command blocks users when trying to install two instances of the *same* provider watching for objects in the
+same namespace.
+
+It is possible to override this block with the `--force` flag, but this options is intended for advanced users only.
+
+</aside>
+
+#### Multi-tenancy
+
+With the term *multi-tenant* we indicating a management cluster where more instances of one or more providers are installed.
+
+The user can achieve multi-tenancy configurations with `clusterctl` by a combination of:
+
+- Multiple calls to `clusterctl init`;
+- Usage of the `--target-namespace` flag;
+- Usage of the `--watching-namespace` flag;
+
+The `clusterctl` command officially supports the following multi-tenancy configurations:
+
+{{#tabs name:"tab-multi-tenancy" tabs:"n-Infra, n-Core"}}
+{{#tab n-Infra}}
+A management cluster with <em>n (with n>1)</em> instances of an infrastructure provider, and <em>only one</em> instance 
+of Cluster API core provider, bootstrap provider and control plane provider (optional).
+
+For example:
+
+* Cluster API core provider installed in the `capi-system` namespace, watching objects in all namespaces;
+* The kubeadm bootstrap provider in `capbpk-system`, watching all namespaces;
+* The kubeadm control plane provider in `cacpk-system`, watching all namespaces;
+* An `aws` infrastructure provider in `aws-system1`, watching objects in `aws-system1` only;
+* An `aws` infrastructure provider in `aws-system2`, watching objects in `aws-system2` only;
+* etc. (more instances of the `aws` provider)
+
+{{#/tab }}
+{{#tab n-Core}}
+A management cluster with <em>n (with n>1)</em> instances of the Cluster API core provider, each one with <em>a dedicated</em> 
+instance of infrastructure provider, bootstrap provider, and control plane provider (optional.
+
+For example:
+
+* A Cluster API core provider installed in the `capi-system1` namespace, watching objects in `capi-system1` only with a dedicated:
+    * kubeadm bootstrap provider in `capi-system1`, watching `capi-system1`;
+    * kubeadm control plane provider in `capi-system1`, watching `capi-system1`;
+    * `aws` infrastructure provider in `capi-system1`, watching objects `capi-system1`;
+* A Cluster API core provider installed in the `capi-system2` namespace, watching objects in `capi-system2` only with a dedicated:
+    * kubeadm bootstrap provider in `capi-system2`, watching `capi-system2`;
+    * kubeadm control plane provider in `capi-system2`, watching `capi-system2`;
+    * `aws` infrastructure provider in `capi-system2`, watching objects `capi-system2`;
+* etc. (more instances of the Cluster API core provider and the dedicated providers)
+
+
+{{#/tab }}
+{{#/tabs }}
+
+
+<aside class="note warning">
+
+<h1>Warning</h1>
+
+It is possible to achieve many other different configurations of multi-tenancy with `clusterctl`.
+
+However, the user should be aware that configurations not listed above are not verified by the clusterctl tests
+and support will be provided at best effort only.
+
+</aside>
+
+
+## Provider repositories
+
+In order to access provider specific information, like the components YAML to be used for installing a provider,
+`clusterctl init` access the **provider repositories**, that are well-known place where the release assets for 
+a provider are published.
+
+See the [clusterctl configuration](configuring-clusterctl.md) for more info about provider's repository configurations.
+
+<aside class="note">
+
+<h1> Is it possible to override files read from a provider repository? </h1>
+
+<aside class="note warning">
+
+<h1>Warning</h1>
+
+This feature is intended for advanced users.
+
+</aside>
+
+If, for any reasons, the user wants to replace the assets available on a provider repository with a locally available asset,
+the user is required to save the file under `$HOME\cluster-api\overrides\<provider-name>\<version>\<file-name.yaml>`. 
+
+</aside>
+
+## Variable substitution
+Providers can use variables into the components YAML published in the provider's repository. 
+
+During `clusterctl init`, those variables will be replace with environment variables or with variables read from the 
+[clusterctl configuration](configuring-clusterctl.md).
+
+<aside class="note warning">
+
+<h1> Action Required </h1>
+
+The user should ensure the variables required by a provider are set in advance.
+
+</aside>
+
+<aside class="note">
+
+<h1> How can I known which variables a provider requires? </h1>
+
+Users can refer to the provider documentation for the list of variables to be set or use the 
+`clusterctl config provider <provider-name>` command to get a list of expected variable names.
+
+</aside>
+
+## Additional information
+
+When installing a provider the `clusterctl init` command takes following additional steps in order to simplify
+the management of lifecycle of the provider's components.
+
+* All the provider's components are labeled, so they can be easily identified in
+subsequent moments of the provider's lifecycle, e.g. for upgrades. Applied labels are: 
+    - `clusterctl.cluster.x-k8s.io`
+    - `clusterctl.cluster.x-k8s.io/provider=<provider-name>`
+
+* An additional `Provider` object is created in the target namespace where the provider is installed.
+This objects keeps track of the provider version, of the watching namespace and other useful information
+for the inventory of the providers currently installed in the management cluster.  
+
+<aside class="note warning">
+
+<h1>Warning</h1>
+
+The `clusterctl.cluster.x-k8s.io` labels and the `Provider` objects MUST NOT altered.
+If this happen, there are no guarantees about the proper functioning of `clusterctl`.  
+
+</aside>