modify doc structure and update existing doc-links as preparation for new doc generation script

docs/operating_systems/amazonlinux.md

@@ -0,0 +1,15 @@
+# Amazon Linux 2
+
+Amazon Linux is supported with docker,containerd and cri-o runtimes.
+
+**Note:** that Amazon Linux is not currently covered in kubespray CI and
+support for it is currently considered experimental.
+
+Amazon Linux 2, while derived from the Redhat OS family, does not keep in
+sync with RHEL upstream like CentOS/AlmaLinux/Oracle Linux. In order to use
+Amazon Linux as the ansible host for your kubespray deployments you need to
+manually install `python3` and deploy ansible and kubespray dependencies in
+a python virtual environment or use the official kubespray containers.
+
+There are no special considerations for using Amazon Linux as the target OS
+for Kubespray deployments.

docs/operating_systems/bootstrap-os.md

@@ -0,0 +1,61 @@
+# bootstrap-os
+
+Bootstrap an Ansible host to be able to run Ansible modules.
+
+This role will:
+
+* configure the package manager (if applicable) to be able to fetch packages
+* install Python
+* install the necessary packages to use Ansible's package manager modules
+* set the hostname of the host to `{{ inventory_hostname }}` when requested
+
+## Requirements
+
+A host running an operating system that is supported by Kubespray.
+See [Supported Linux Distributions](https://github.com/kubernetes-sigs/kubespray#supported-linux-distributions) for a current list.
+
+SSH access to the host.
+
+## Role Variables
+
+Variables are listed with their default values, if applicable.
+
+### General variables
+
+* `http_proxy`/`https_proxy`
+  The role will configure the package manager (if applicable) to download packages via a proxy.
+
+* `override_system_hostname: true`
+  The role will set the hostname of the machine to the name it has according to Ansible's inventory (the variable `{{ inventory_hostname }}`).
+
+### Per distribution variables
+
+#### Flatcar Container Linux
+
+* `coreos_locksmithd_disable: false`
+  Whether `locksmithd` (responsible for rolling restarts) should be disabled or be left alone.
+
+#### CentOS/RHEL/AlmaLinux/Rocky Linux
+
+* `centos_fastestmirror_enabled: false`
+  Whether the [fastestmirror](https://wiki.centos.org/PackageManagement/Yum/FastestMirror) yum plugin should be enabled.
+
+## Dependencies
+
+The `kubespray-defaults` role is expected to be run before this role.
+
+## Example Playbook
+
+Remember to disable fact gathering since Python might not be present on hosts.
+
+```yaml
+- hosts: all
+  gather_facts: false  # not all hosts might be able to run modules yet
+  roles:
+    - kubespray-defaults
+    - bootstrap-os
+```
+
+## License
+
+Apache 2.0

docs/operating_systems/centos.md

@@ -0,0 +1,12 @@
+# CentOS and derivatives
+
+## CentOS 7
+
+The maximum python version officially supported in CentOS is 3.6. Ansible as of version 5 (ansible core 2.12.x) increased their python requirement to python 3.8 and above.
+Kubespray supports multiple ansible versions but only the default (5.x) gets wide testing coverage. If your deployment host is CentOS 7 it is recommended to use one of the earlier versions still supported.
+
+## CentOS 8
+
+If you have containers that are using iptables in the host network namespace (`hostNetwork=true`),
+you need to ensure they are using iptables-nft.
+An example how k8s do the autodetection can be found [in this PR](https://github.com/kubernetes/kubernetes/pull/82966)

docs/operating_systems/fcos.md

@@ -0,0 +1,69 @@
+# Fedora CoreOS
+
+Tested with stable version 37.20230322.3.0
+
+Because package installation with `rpm-ostree` requires a reboot, playbook may fail while bootstrap.
+Restart playbook again.
+
+## Containers
+
+Tested with
+
+- containerd
+- crio
+
+## Network
+
+### calico
+
+To use calico create sysctl file with ignition:
+
+```yaml
+files:
+    - path: /etc/sysctl.d/reverse-path-filter.conf
+      contents:
+        inline: |
+          net.ipv4.conf.all.rp_filter=1
+```
+
+## libvirt setup
+
+### Prepare
+
+Prepare ignition and serve via http (a.e. python -m http.server )
+
+```json
+{
+  "ignition": {
+     "version": "3.0.0"
+  },
+
+  "passwd": {
+    "users": [
+      {
+        "name": "ansibleUser",
+        "sshAuthorizedKeys": [
+          "ssh-rsa ..publickey.."
+        ],
+        "groups": [ "wheel" ]
+      }
+    ]
+  }
+}
+```
+
+### create guest
+
+```ShellSeasion
+machine_name=myfcos1
+ignition_url=http://mywebserver/fcos.ign
+
+fcos_version=34.20210611.3.0
+kernel=https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/${fcos_version}/x86_64/fedora-coreos-${fcos_version}-live-kernel-x86_64
+initrd=https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/${fcos_version}/x86_64/fedora-coreos-${fcos_version}-live-initramfs.x86_64.img
+rootfs=https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/${fcos_version}/x86_64/fedora-coreos-${fcos_version}-live-rootfs.x86_64.img
+kernel_args="console=ttyS0 coreos.live.rootfs_url=${rootfs} coreos.inst.install_dev=/dev/sda coreos.inst.stream=stable coreos.inst.ignition_url=${ignition_url}"
+sudo virt-install --name ${machine_name} --ram 4048 --graphics=none --vcpus 2 --disk size=20 \
+                --network bridge=virbr0 \
+                --install kernel=${kernel},initrd=${initrd},kernel_args_overwrite=yes,kernel_args="${kernel_args}"
+```

docs/operating_systems/flatcar.md

@@ -0,0 +1,14 @@
+Flatcar Container Linux bootstrap
+===============
+
+Example with Ansible:
+
+Before running the cluster playbook you must satisfy the following requirements:
+
+General Flatcar Pre-Installation Notes:
+
+- Ensure that the bin_dir is set to `/opt/bin`
+- ansible_python_interpreter should be `/opt/bin/python`. This will be laid down by the bootstrap task.
+- The resolvconf_mode setting of `docker_dns` **does not** work for Flatcar. This is because we do not edit the systemd service file for docker on Flatcar nodes. Instead, just use the default `host_resolvconf` mode. It should work out of the box.
+
+Then you can proceed to [cluster deployment](#run-deployment)

docs/operating_systems/kylinlinux.md

@@ -0,0 +1,11 @@
+# Kylin Linux
+
+Kylin Linux is supported with docker and containerd runtimes.
+
+**Note:** that Kylin Linux is not currently covered in kubespray CI and
+support for it is currently considered experimental.
+
+At present, only `Kylin Linux Advanced Server V10 (Sword)` has been adapted, which can support the deployment of aarch64 and x86_64 platforms.
+
+There are no special considerations for using Kylin Linux as the target OS
+for Kubespray deployments.

docs/operating_systems/openeuler.md

@@ -0,0 +1,11 @@
+# OpenEuler
+
+[OpenEuler](https://www.openeuler.org/en/) Linux is supported with docker and containerd runtimes.
+
+**Note:** that OpenEuler Linux is not currently covered in kubespray CI and
+support for it is currently considered experimental.
+
+At present, only `openEuler 22.03 LTS` has been adapted, which can support the deployment of aarch64 and x86_64 platforms.
+
+There are no special considerations for using OpenEuler Linux as the target OS
+for Kubespray deployments.

docs/operating_systems/opensuse.md

@@ -0,0 +1,17 @@
+# openSUSE Leap 15.3 and Tumbleweed
+
+openSUSE Leap installation Notes:
+
+- Install Ansible
+
+  ```ShellSession
+  sudo zypper ref
+  sudo zypper -n install ansible
+
+  ```
+
+- Install Jinja2 and Python-Netaddr
+
+  ```sudo zypper -n install python-Jinja2 python-netaddr```
+
+Now you can continue with [Preparing your deployment](getting-started.md#starting-custom-deployment)

docs/operating_systems/rhel.md

@@ -0,0 +1,34 @@
+# Red Hat Enterprise Linux (RHEL)
+
+## RHEL Support Subscription Registration
+
+In order to install packages via yum or dnf, RHEL 7/8 hosts are required to be registered for a valid Red Hat support subscription.
+
+You can apply for a 1-year Development support subscription by creating a [Red Hat Developers](https://developers.redhat.com/) account. Be aware though that as the Red Hat Developers subscription is limited to only 1 year, it should not be used to register RHEL 7/8 hosts provisioned in Production environments.
+
+Once you have a Red Hat support account, simply add the credentials to the Ansible inventory parameters `rh_subscription_username` and `rh_subscription_password` prior to deploying Kubespray. If your company has a Corporate Red Hat support account, then obtain an **Organization ID** and **Activation Key**, and add these to the Ansible inventory parameters `rh_subscription_org_id` and `rh_subscription_activation_key` instead of using your Red Hat support account credentials.
+
+```ini
+rh_subscription_username: ""
+rh_subscription_password: ""
+# rh_subscription_org_id: ""
+# rh_subscription_activation_key: ""
+```
+
+Either the Red Hat support account username/password, or Organization ID/Activation Key combination must be specified in the Ansible inventory in order for the Red Hat subscription registration to complete successfully during the deployment of Kubespray.
+
+Update the Ansible inventory parameters `rh_subscription_usage`, `rh_subscription_role` and `rh_subscription_sla` if necessary to suit your specific requirements.
+
+```ini
+rh_subscription_usage: "Development"
+rh_subscription_role: "Red Hat Enterprise Server"
+rh_subscription_sla: "Self-Support"
+```
+
+If the RHEL 7/8 hosts are already registered to a valid Red Hat support subscription via an alternative configuration management approach prior to the deployment of Kubespray, the successful RHEL `subscription-manager` status check will simply result in the RHEL subscription registration tasks being skipped.
+
+## RHEL 8
+
+If you have containers that are using iptables in the host network namespace (`hostNetwork=true`),
+you need to ensure they are using iptables-nft.
+An example how k8s do the autodetection can be found [in this PR](https://github.com/kubernetes/kubernetes/pull/82966)

docs/operating_systems/uoslinux.md

@@ -0,0 +1,9 @@
+# UOS Linux
+
+UOS Linux(UnionTech OS Server 20) is supported with docker and containerd runtimes.
+
+**Note:** that UOS Linux is not currently covered in kubespray CI and
+support for it is currently considered experimental.
+
+There are no special considerations for using UOS Linux as the target OS
+for Kubespray deployments.