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

📖 Fill the book content with the current README.md

Author: k8s-ci-robot

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/introduction.md renamed to docs/book/src/00_introduction.md

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

docs/book/src/01_user/00.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/user/concepts.md renamed to docs/book/src/01_user/01_concepts.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/user/quick-start.md renamed to docs/book/src/01_user/02_quick-start.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.