Merge pull request #449 from Danil-Grigorev/docs-content

📖 Fill the book content with the current README.md

docs/book/Makefile

@@ -22,10 +22,11 @@ TABULATE := $(TOOLS_BIN_DIR)/mdbook-tabulate
 EMBED := $(TOOLS_BIN_DIR)/mdbook-embed
 RELEASELINK := $(TOOLS_BIN_DIR)/mdbook-releaselink
 MDBOOK := $(TOOLS_BIN_DIR)/bin/mdbook
+FS_SUMMARY := $(TOOLS_BIN_DIR)/bin/mdbook-fs-summary
 
 export PATH := $(abspath $(TOOLS_BIN_DIR)/bin):$(PATH)
 
-BOOK_DEPS := $(MDBOOK) $(TABULATE) $(EMBED) $(RELEASELINK)
+BOOK_DEPS := $(MDBOOK) $(TABULATE) $(EMBED) $(RELEASELINK) $(FS_SUMMARY)
 
 $(TOOLS_BIN_DIR)/%: $(TOOLS_DIR_DEPS)
 	make -C $(TOOLS_DIR) $(subst $(TOOLS_DIR)/,,$@)

docs/book/book.toml

@@ -5,6 +5,19 @@ src = "src"
 title = "Cluster API Operator"
 description = "Cluster API Operator"
 
+[preprocessor.toc]
+command = "mdbook-toc"
+marker = "[[_TOC_]]"
+
+[preprocessor.fs-summary]
+# (default: true)
+clean-paths = false
+
+# other preprocessors will naturally need to
+# run after the summary has been generated
+[preprocessor.links]
+after = ["fs-summary"]
+
 [output.html]
 mathjax-support = true
 git-repository-url = "https://github.com/kubernetes-sigs/cluster-api-operator"
@@ -22,4 +35,4 @@ command = "./util-tabulate.sh"
 command = "./util-embed.sh"
 
 [preprocessor.releaselink]
-command = "./util-releaselink.sh"
+command = "./util-releaselink.sh"

docs/book/src/01_user/00.md

@@ -0,0 +1,3 @@
+# User guide
+
+This section contains quick start and concepts relevant to a new operator user.

docs/book/src/user/quick-start.md → docs/book/src/01_user/02_quick-start.md

@@ -2,6 +2,8 @@
 
 This is a quickstart guide for getting Cluster API Operator up and running on your Kubernetes cluster.
 
+For more detailed information, please refer to the full documentation.
+
 ## Prerequisites
 
 - [Running Kubernetes cluster](https://cluster-api.sigs.k8s.io/user/quick-start#install-andor-configure-a-kubernetes-cluster).
@@ -25,42 +27,47 @@ kubectl create secret generic "${CREDENTIALS_SECRET_NAME}" --from-literal=AWS_B6
 
 ### Installing Cluster API Operator
 
-#### Method 1: Apply Manifests from Release Assets
-
-Before installing the Cluster API Operator this way, you must first ensure that cert-manager is installed, as the operator does not manage cert-manager installations. To install cert-manager, run the following command:
-
-```bash
-kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml
-```
-
-Wait for cert-manager to be ready before proceeding.
-
-After cert-manager is successfully installed, you can install the Cluster API operator directly by applying the latest release assets:
+Add helm repository:
 
 ```bash
-kubectl apply -f https://github.com/kubernetes-sigs/cluster-api-operator/releases/latest/download/operator-components.yaml
+helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator
+helm repo update
 ```
 
-#### Method 2: Use Helm Charts
-
-Alternatively, you can install the Cluster API operator using Helm charts:
+Deploy Cluster API components with docker provider using a single command during operator installation
 
 ```bash
-helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator
-helm repo update
-helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system
+helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set infrastructure=docker --set cert-manager.enabled=true --set configSecret.name=${CREDENTIALS_SECRET_NAME} --set configSecret.namespace=${CREDENTIALS_SECRET_NAMESPACE}  --wait --timeout 90s
 ```
 
-##### Installing cert-manager using Helm chart
+Docker provider can be replaced by any provider supported by [clusterctl](https://cluster-api.sigs.k8s.io/reference/providers.html#infrastructure).
 
-CAPI operator Helm chart supports provisioning of cert-manager as a dependency. It is disabled by default, but you can enable it with `--set cert-manager.enabled=true` option to `helm install` command or inside of `cert-manager` section in [values.yaml](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/hack/charts/cluster-api-operator/values.yaml) file. Additionally you can define other [parameters](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration) provided by the cert-manager chart.
+Other options for installing Cluster API Operator are described in [installation documentation](../02_installation/).
+
+# Example API Usage
 
-##### Installing providers using Helm chart
+Deploy latest version of core Cluster API components:
 
-Deploy Cluster API components with docker provider using a single command during operator installation:
+```yaml
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: CoreProvider
+metadata:
+  name: cluster-api
+  namespace: capi-system
 
-```bash
-helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set infrastructure=docker --set cert-manager.enabled=true --set configSecret.name=${CREDENTIALS_SECRET_NAME} --set configSecret.namespace=${CREDENTIALS_SECRET_NAMESPACE}  --wait --timeout 90s
 ```
 
-Docker provider can be replaced by any provider supported by [clusterctl](https://cluster-api.sigs.k8s.io/reference/providers.html#infrastructure).
+Deploy Cluster API AWS provider with specific version, custom manager options and flags:
+
+```yaml
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: InfrastructureProvider
+metadata:
+ name: aws
+ namespace: capa-system
+spec:
+ version: v2.1.4
+ configSecret:
+   name: aws-variables
+```

docs/book/src/02_installation/02_manifest-installation.md

@@ -0,0 +1,15 @@
+# Using Manifests from Release Assets
+
+Before installing the Cluster API Operator this way, you must first ensure that cert-manager is installed, as the operator does not manage cert-manager installations. To install cert-manager, run the following command:
+
+```bash
+kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml
+```
+
+Wait for cert-manager to be ready before proceeding.
+
+After cert-manager is successfully installed, you can install the Cluster API operator directly by applying the latest release assets:
+
+```bash
+kubectl apply -f https://github.com/kubernetes-sigs/cluster-api-operator/releases/latest/download/operator-components.yaml
+```

docs/book/src/02_installation/03_helm-chart-installation.md

@@ -0,0 +1,35 @@
+# Using Helm Charts
+
+Alternatively, you can install the Cluster API operator using Helm charts:
+
+```bash
+helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator
+helm repo update
+helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system
+```
+
+#### Installing cert-manager using Helm chart
+
+CAPI operator Helm chart supports provisioning of cert-manager as a dependency. It is disabled by default, but you can enable it with `--set cert-manager.enabled=true` option to `helm install` command or inside of `cert-manager` section in [values.yaml](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/hack/charts/cluster-api-operator/values.yaml) file. Additionally you can define other [parameters](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration) provided by the cert-manager chart.
+
+#### Installing providers using Helm chart
+
+The operator Helm chart supports a "quickstart" option for bootstrapping a management cluster. The user experience is relatively similar to [clusterctl init](https://cluster-api.sigs.k8s.io/clusterctl/commands/init.html?highlight=init#clusterctl-init):
+
+```bash
+helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set infrastructure=docker:v1.4.2  --wait --timeout 90s # core Cluster API with kubeadm bootstrap and control plane providers will also be installed
+```
+
+```bash
+helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system —set infrastructure="docker;azure"  --wait --timeout 90s # core Cluster API with kubeadm bootstrap and control plane providers will also be installed
+```
+
+```bash
+helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system —set infrastructure="capd-custom-ns:docker:v1.4.2;capz-custom-ns:azure:v1.10.0"  --wait --timeout 90s # core Cluster API with kubeadm bootstrap and control plane providers will also be installed
+```
+
+```bash
+helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set core=cluster-api:v1.4.2 --set controlPlane=kubeadm:v1.4.2 --set bootstrap=kubeadm:v1.4.2  --set infrastructure=docker:v1.4.2  --wait --timeout 90s
+```
+
+For more complex operations, please refer to our API documentation.

docs/book/src/03_topics/01_capi-providers-lifecycle/00.md

@@ -0,0 +1,7 @@
+# Cluster API Provider Lifecycle
+
+This section contains lifecycle operations a user can perform on a provider manifest, such as:
+- Install
+- Upgrade
+- Modify
+- Delete

docs/book/src/03_topics/01_capi-providers-lifecycle/01_installing-provider.md

@@ -0,0 +1,25 @@
+# Installing a Provider
+
+To install a new Cluster API provider with the Cluster API Operator, create a provider object as shown in the first example API usage for creating the secret with variables and the provider itself.
+
+The operator processes a provider object by applying the following rules:
+
+- The CoreProvider is installed first; other providers will be requeued until the core provider exists.
+- Before installing any provider, the following pre-flight checks are executed:
+- No other instance of the same provider (same Kind, same name) should exist in any namespace.
+- The Cluster API contract (e.g., v1beta1) must match the contract of the core provider.
+- The operator sets conditions on the provider object to surface any installation issues, including pre-flight checks and/or order of installation.
+- If the FetchConfiguration is not defined, the operator applies the embedded fetch configuration for the given kind and `ObjectMeta.Name` specified in the [Cluster API code](https://github.com/kubernetes-sigs/cluster-api/blob/main/cmd/clusterctl/client/config/providers_client.go).
+
+The installation process, managed by the operator, aligns with the implementation underlying the `clusterctl init` command and includes these steps:
+
+- Fetching provider artifacts (the components.yaml and metadata.yaml files).
+- Applying image overrides, if any.
+- Replacing variables in the infrastructure-components from EnvVar and Secret.
+- Applying the resulting YAML to the cluster.
+
+Differences between the operator and `clusterctl init` include:
+
+- The operator installs one provider at a time while `clusterctl init` installs a group of providers in a single operation.
+- The operator stores fetched artifacts in a config map for reuse during subsequent reconciliations.
+- The operator uses a Secret, while `clusterctl init` relies on environment variables and a local configuration file.

docs/book/src/03_topics/01_capi-providers-lifecycle/02_upgrading-provider.md

@@ -0,0 +1,13 @@
+# Upgrading a Provider
+
+To trigger an upgrade for a Cluster API provider, change the `spec.Version` field. All providers must follow the golden rule of respecting the same Cluster API contract supported by the core provider.
+
+The operator performs the upgrade by:
+
+1. Deleting the current provider components, while preserving CRDs, namespaces, and user objects.
+2. Installing the new provider components.
+
+Differences between the operator and `clusterctl upgrade apply` include:
+
+- The operator upgrades one provider at a time while `clusterctl upgrade apply` upgrades a group of providers in a single operation.
+- With the declarative approach, users are responsible for manually editing the Provider objects' YAML, while `clusterctl upgrade apply --contract` automatically determines the latest available versions for each provider.

docs/book/src/03_topics/01_capi-providers-lifecycle/03_modifying-provider.md

@@ -0,0 +1,7 @@
+# Modifying a Provider
+
+In addition to changing a provider version (upgrades), the operator supports modifying other provider fields such as controller flags and variables. This can be achieved through `kubectl edit` or `kubectl apply` to the provider object.
+
+The operation works similarly to upgrades: The current provider instance is deleted while preserving CRDs, namespaces, and user objects. Then, a new provider instance with the updated flags/variables is installed.
+
+**Note**: `clusterctl` currently does not support this operation.

docs/book/src/03_topics/01_capi-providers-lifecycle/04_deleting-provider.md

@@ -0,0 +1,8 @@
+# Deleting a Provider
+
+To remove the installed providers and all related kubernetes objects just delete the following CRs:
+
+```bash
+kubectl delete infrastructureprovider azure
+kubectl delete coreprovider cluster-api
+```

docs/book/src/03_topics/02_configuration/00.md

@@ -0,0 +1,3 @@
+# Configuration
+
+This section contains a list of frequent configuration tasks for CAPI Operator providers.

docs/book/src/03_topics/02_configuration/01_air-gapped-environtment.md

@@ -0,0 +1,86 @@
+# Air-gapped Environment
+
+To install Cluster API providers in an air-gapped environment using the operator, address the following issues:
+
+1. Configure the operator for an air-gapped environment:
+   - Manually fetch and store a helm chart for the operator.
+   - Provide image overrides for the operator in from an accessible image repository.
+2. Configure providers for an air-gapped environment:
+   - Provide fetch configuration for each provider from an accessible location (e.g., an internal GitHub repository) or from pre-created ConfigMaps within the cluster.
+   - Provide image overrides for each provider to pull images from an accessible image repository.
+
+**Example Usage:**
+
+As an admin, I need to fetch the Azure provider components from within the cluster because I am working in an air-gapped environment.
+
+In this example, there is a ConfigMap in the `capz-system` namespace that defines the components and metadata of the provider.
+
+The Azure InfrastructureProvider is configured with a `fetchConfig` specifying the label selector, allowing the operator to determine the available versions of the Azure provider. Since the provider's version is marked as `v1.9.3`, the operator uses the components information from the ConfigMap with matching label to install the Azure provider.
+
+```yaml
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  labels:
+    provider-components: azure
+  name: v1.9.3
+  namespace: capz-system
+data:
+  components: |
+    # Components for v1.9.3 YAML go here
+  metadata: |
+    # Metadata information goes here
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: InfrastructureProvider
+metadata:
+  name: azure
+  namespace: capz-system
+spec:
+  version: v1.9.3
+  configSecret:
+    name: azure-variables
+  fetchConfig:
+    selector:
+      matchLabels:
+        provider-components: azure
+```
+
+### Situation when manifests do not fit into configmap
+
+There is a limit on the [maximum size](https://kubernetes.io/docs/concepts/configuration/configmap/#motivation) of a configmap - 1MiB. If the manifests do not fit into this size, Kubernetes will generate an error and provider installation fail. To avoid this, you can archive the manifests and put them in the configmap that way.
+
+For example, you have two files: `components.yaml` and `metadata.yaml`. To create a working config map you need:
+
+1. Archive components.yaml using `gzip` cli tool
+
+```sh
+gzip -c components.yaml > components.gz
+```
+
+2. Create a configmap manifest from the archived data
+
+```sh
+kubectl create configmap v1.9.3 --namespace=capz-system --from-file=components=components.gz --from-file=metadata=metadata.yaml --dry-run=client -o yaml > configmap.yaml
+```
+
+3. Edit the file by adding "provider.cluster.x-k8s.io/compressed: true" annotation
+
+```sh
+yq eval -i '.metadata.annotations += {"provider.cluster.x-k8s.io/compressed": "true"}' configmap.yaml
+```
+
+**Note**: without this annotation operator won't be able to determine if the data is compressed or not.
+
+4. Add labels that will be used to match the configmap in `fetchConfig` section of the provider
+
+```sh
+yq eval -i '.metadata.labels += {"my-label": "label-value"}' configmap.yaml
+```
+
+5. Create a configmap in your kubernetes cluster using kubectl
+
+```sh
+kubectl create -f configmap.yaml
+```

docs/book/src/03_topics/02_configuration/02_injecting-additional-manifests.md

@@ -0,0 +1,26 @@
+# Injecting additional manifests
+
+It is possible to inject additional manifests when installing/upgrading a provider. This can be useful when you need to add extra RBAC resources to the provider controller, for example.
+The field `AdditionalManifests` is a reference to a ConfigMap that contains additional manifests, which will be applied together with the provider components. The key for storing these manifests has to be `manifests`.
+The manifests are applied only once when a certain release is installed/upgraded. If the namespace is not specified, the namespace of the provider will be used. There is no validation of the YAML content inside the ConfigMap.
+
+```yaml
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: additional-manifests
+  namespace: capi-system
+data:
+  manifests: |
+    # Additional manifests go here
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: CoreProvider
+metadata:
+  name: cluster-api
+  namespace: capi-system
+spec:
+  additionalManifests:
+    name: additional-manifests
+```