Merge pull request k0sproject#498 from ologvinova/install-section

[DOCS] Rework requirements and install steps

docs/capi-examples.md

@@ -1,23 +1,8 @@
-# Cluster API - Examples
+# Cluster API examples - software prerequisites
 
-This section presents a collection of examples showcasing the use of k0smotron as a Cluster API provider across various cloud platforms.
+This section presents a collection of examples showcasing the use of k0smotron
+as a Cluster API provider across various cloud platforms.
 
-# Prerequisites
-
-The examples herein require the following prerequisites:
-
-## Management cluster
-
-You must have an existing [management cluster](https://cluster-api.sigs.k8s.io/reference/glossary.html#management-cluster) for these examples. Ensure that `kubectl` or any other client tooling you use is configured to interact with this cluster.
-
-If you don't have a management cluster yet, you can effortlessly create one using [k0s](https://docs.k0sproject.io/stable/install/).
-
-## k0smotron
-
-Install k0smotron on your management cluster by following this installation [guide](install.md).
-
-## clusterctl
-
-Lastly, you'll need `clusterctl` [installed](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl) on your local machine.
-
-Proceed with these examples once you've fulfilled these prerequisites. Each example demonstrates how k0smotron can serve as an efficient Cluster API provider in different environments.
+Before proceeding with the Cluster API examples, make sure that you have met
+[common prerequisites](install.md#software-prerequisites) and installed
+[k0smotron](install.md#full-installation).

docs/install.md

@@ -1,34 +1,70 @@
-# Installation
+# Introduction
 
-To install k0smotron, run the following command:
+This section describes how to install k0smotron on top of an existing k0s
+Kubernetes cluster that allows for creation and management of the k0s
+control plane.
 
-```bash
-kubectl apply -f https://docs.k0smotron.io/{{{ extra.k0smotron_version }}}/install.yaml
-```
+# Hardware requirements
+
+k0smotron does not require any special hardware for workloads aside from
+the one required for k0s. For details on k0s hardware requirements for
+workloads, see [k0s documentation](https://docs.k0sproject.io/stable/system-requirements/).
+
+# Software prerequisites
+
+k0smotron requires the following software to be preinstalled:
+
+* Kubernetes management cluster.
+  In this documentation set, we use the
+  [k0s Kubernetes distribution](https://docs.k0sproject.io/stable/install/)
+  as a management cluster.
+  For Cluster API integration, you can use a
+  [Cluster API cluster](https://cluster-api.sigs.k8s.io/reference/glossary.html#management-cluster).
+* `kubectl` installed locally.
+* For Cluster API integration:
 
-This install the k0smotron controller manager, all the related CRD definitions and needed RBAC rules.
+  * [clusterctl](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl)
+    installed locally.
+  * Configured cloud provider. In this documentation set, we describe
+    configuration examples for the following providers: AWS, Docker,
+    Hetzner Cloud, OpenStack, vSphere. For setup instructions, refer to the
+    official documentation of the selected cloud provider.
 
-Once the installation is completed you are ready to [create your first control planes](cluster.md).
+* Optional. CSI provider for persistent storage in managed clusters.
+* Optional. Load balancer provider for ensuring high availability of the
+  control plane.
 
-## clusterctl
+# Full installation
 
-k0smotron is compatible with clusterctl and can act as bootstrap, infrastructure, and control plane provider. To use k0smotron with clusterctl, you need to create a clusterctl configuration file. Here's an example:
+A full k0smotron installation implies the following components:
+
+* k0smotron operator
+* Custom Resource Definitions
+* Role-based access control rules
+* Bootstrap provider
+* Infrastructure provider
+* Control plane provider
+
+To install the full version of k0smotron:
 
 ```bash
-providers:
-  - name: "k0smotron"
-    url: "https://github.com/k0sproject/k0smotron/releases/latest/bootstrap-components.yaml"
-    type: "BootstrapProvider"
-  - name: "k0smotron"
-    url: "https://github.com/k0sproject/k0smotron/releases/latest/control-plane-components.yaml"
-    type: "ControlPlaneProvider"
-  - name: "k0smotron"
-    url: "https://github.com/k0sproject/k0smotron/releases/latest/infrastructure-components.yaml"
-    type: "InfrastructureProvider"
+kubectl apply -f https://docs.k0smotron.io/{{{ extra.k0smotron_version }}}/install.yaml
 ```
 
-Once you have the configuration file in place, you can use clusterctl to create a cluster:
+Now, you can create your first control planes using k0smotron either as a
+standalone manager, or as a Cluster API provider. For use case details, see
+[k0smotron usage](usage-overview.md).
+
+# Per-module installation for Cluster API
+
+k0smotron is compatible with `clusterctl` and can act as a Cluster API
+bootstrap, infrastructure, and control plane provider. You can use
+`clusterctl` to install each k0smotron Cluster API module separately:
 
 ```bash
-clusterctl init --bootstrap k0smotron --control-plane k0smotron --config config.yaml
+clusterctl init --bootstrap k0sproject-k0smotron \
+                --control-plane k0sproject-k0smotron \
+                --infrastructure k0sproject-k0smotron
 ```
+
+To start using the k0smotron Cluster API, refer to [Cluster API](cluster-api.md).

mkdocs.yml

@@ -29,7 +29,7 @@ nav:
       - Remote Machine Provider: capi-remote.md
       - ClusterClass: capi-clusterclass.md
       - Examples:
-        - Overview: capi-examples.md
+        - Software prerequisites: capi-examples.md
         - AWS: capi-aws.md
         - Hetzner Cloud: capi-hetzner.md
         - OpenStack: capi-openstack.md