kubernetes-sigs · k8s-ci-robot · Jan 17, 2020 · Jan 17, 2020
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -8,6 +8,17 @@
     - [Certificate Management](./tasks/certs/index.md)
         - [Using Custom Certificates](./tasks/certs/using-custom-certificates.md)
         - [Generating a Kubeconfig](./tasks/certs/generate-kubeconfig.md)
+- [clusterctl CLI](./clusterctl/overview.md)
+    - [clusterctl Commands](clusterctl/commands/commands.md)
+        - [init](clusterctl/commands/init.md)
+        - [config cluster](clusterctl/commands/config-cluster.md)
+        - [move](./clusterctl/commands/move.md)
+        - [adopt](clusterctl/commands/adopt.md)
+        - [upgrade](clusterctl/commands/upgrade.md)
+        - [delete](clusterctl/commands/delete.md)
+    - [clusterctl Configuration](clusterctl/configuration.md)
+    - [clusterctl Provider Contract](clusterctl/provider-contract.md)
+    - [clusterctl for Developers](clusterctl/developers.md)
 - [Developer Guide](./architecture/developer-guide.md)
     - [Repository Layout](./architecture/repository-layout.md)
     - [Rapid iterative development with Tilt](./developer/tilt.md)
@@ -33,6 +44,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)
diff --git a/docs/book/src/clusterctl/command-init.md b/docs/book/src/clusterctl/command-init.md
@@ -0,0 +1 @@
+# init
diff --git a/docs/book/src/clusterctl/commands/adopt.md b/docs/book/src/clusterctl/commands/adopt.md
@@ -0,0 +1 @@
+# clusterctl adopt
diff --git a/docs/book/src/clusterctl/commands/commands.md b/docs/book/src/clusterctl/commands/commands.md
@@ -0,0 +1,11 @@
+# clusterctl Commands
+
+* [`clusterctl init`](init.md)
+* [`clusterctl config cluster`](config-cluster.md)
+* [`clusterctl move`](move.md)
+* [`clusterctl adopt`](adopt.md)
+* [`clusterctl upgrade`](upgrade.md)
+* [`clusterctl delete`](delete.md)
+
+
+
diff --git a/docs/book/src/clusterctl/commands/config-cluster.md b/docs/book/src/clusterctl/commands/config-cluster.md
@@ -0,0 +1 @@
+# clusterctl config cluster
diff --git a/docs/book/src/clusterctl/commands/delete.md b/docs/book/src/clusterctl/commands/delete.md
@@ -0,0 +1 @@
+# clusterctl delete
diff --git a/docs/book/src/clusterctl/commands/init.md b/docs/book/src/clusterctl/commands/init.md
@@ -0,0 +1,233 @@
+# 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 can I use? </h1>
+
+You can use the `clusterctl config providers` command 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](../configuration.md) file. 
+
+</aside>
+
+#### Automatically installed providers
+
+The `clusterctl init` command automatically adds the Cluster API core provider and
+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.
+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 another instance of core provider/bootstrap provider already 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 defined by each provider, 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 forbids users from installing two instances of the *same* provider in the
+same target namespace.
+
+</aside>
+
+#### Watching namespace
+
+The `clusterctl init` command by default installs each provider configured for watching objects in all namespaces. 
+
+<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 forbids users from installing two instances of the *same* provider watching for objects in the
+same namespace.
+
+</aside>
+
+#### Multi-tenancy
+
+*Multi-tenancy* for Cluster API means a management cluster where multiple instances of the same provider 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 (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;
+* The `aws` infrastructure provider in `aws-system1`, watching objects in `aws-system1` only;
+* The `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 (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, and with:
+    * The kubeadm bootstrap provider in `capi-system1`, watching `capi-system1`;
+    * The kubeadm control plane provider in `capi-system1`, watching `capi-system1`;
+    * The `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, and with:
+    * The kubeadm bootstrap provider in `capi-system2`, watching `capi-system2`;
+    * The kubeadm control plane provider in `capi-system2`, watching `capi-system2`;
+    * The `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
+
+To access provider specific information, such as the components YAML to be used for installing a provider,
+`clusterctl init` accesses the **provider repositories**, that are well-known places where the release assets for 
+a provider are published.
+
+See [clusterctl configuration](../configuration.md) for more info about provider repository configurations.
+
+<aside class="note">
+
+<h1> Is it possible to override files read from a provider repository? </h1>
+
+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 in the components YAML published in the provider's repository. 
+
+During `clusterctl init`, those variables are replaced with environment variables or with variables read from the 
+[clusterctl configuration](../configuration.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 executes a set of steps to simplify
+the lifecycle management 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. upgrades. 
+
+ ```bash
+ labels:
+ - 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 object keeps track of the provider version, 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 happens, there are no guarantees about the proper functioning of `clusterctl`.  
+
+</aside>
diff --git a/docs/book/src/clusterctl/commands/move.md b/docs/book/src/clusterctl/commands/move.md
@@ -0,0 +1 @@
+# clusterctl move
diff --git a/docs/book/src/clusterctl/commands/upgrade.md b/docs/book/src/clusterctl/commands/upgrade.md
@@ -0,0 +1 @@
+# clusterctl 
diff --git a/docs/book/src/clusterctl/configuration.md b/docs/book/src/clusterctl/configuration.md
@@ -0,0 +1,46 @@
+# clusterctl Configuration File
+
+The `clusterctl` config file is located at `$HOME/.cluster-api/clusterctl.yaml` and it can be used to:
+
+- Customize the list of providers and provider repositories.
+- Provide configuration values to be used for variable substitution when installing providers or creating clusters.
+
+## Provider repositories
+
+The `clusterctl` CLI is designed to work with providers implementing the [clusterct Provider Contract](contract.md).
+
+Each provider is expected to define a provider repository, a well-known place where release assets are published. 
+
+By default, `clusterctl` ships with providers sponsored by SIG Cluster Lifecycle. 
+
+Users can customize the list of available providers using the `clusterctl` configuration file, as shown in the following example:
+
+```yaml
+providers:
+  # add a custom provider
+  - name: "my-infra-provider"
+    url: "https://github.com/myorg/myrepo/releases/latest/infrastructure_components.yaml"
+    type: "InfrastructureProvider"
+  # override a pre-defined provider
+  - name: "cluster-api"
+    url: "https://github.com/myorg/myforkofclusterapi/releases/latest/core_components.yaml"
+    type: "CoreProvider"
+```
+
+## Variables
+
+When installing a provider `clusterctl` reads a YAML file that is published in the provider repository; while executing
+this operation, `clusterctl` can substitute certain variables with the ones provided by the user.   
+
+The same mechanism also applies when `clusterctl` reads the cluster templates YAML published in the repository, e.g. 
+when injecting the Kubernetes version to use, or the number of worker machines to create.
+
+The user can provide values using OS environment variables, but it is also possible to add
+variables in the `clusterctl` config file:
+
+```yaml
+# Values for environment variable substitution
+AWS_B64ENCODED_CREDENTIALS: XXXXXXXX
+```
+
+In case a variable is defined both in the config file and as an OS environment variable, the latter takes precedence.