From 0c504e49845baade3e0a868cd79ca09414452510 Mon Sep 17 00:00:00 2001
From: Cristian Calin <6627509+cristicalin@users.noreply.github.com>
Date: Mon, 16 May 2022 10:50:17 +0300
Subject: [PATCH] [docs] document support for ansible versions (#8827)

drop note about not supporting ansible 2.9 since we still cover it in
nightly CI
---
 docs/_sidebar.md               |  2 +-
 docs/ansible.md                | 39 ++++++++++++++++++++++++++++------
 docs/{centos8.md => centos.md} |  9 +++++++-
 3 files changed, 41 insertions(+), 9 deletions(-)
 rename docs/{centos8.md => centos.md} (56%)

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 859cc1306..272d4a786 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -34,7 +34,7 @@
   * [Fedora CoreOS](docs/fcos.md)
   * [OpenSUSE](docs/opensuse.md)
   * [RedHat Enterprise Linux](docs/rhel.md)
-  * [CentOS/OracleLinux/AlmaLinux/Rocky Linux](docs/centos8.md)
+  * [CentOS/OracleLinux/AlmaLinux/Rocky Linux](docs/centos.md)
   * [Amazon Linux 2](docs/amazonlinux.md)
 * CRI
   * [Containerd](docs/containerd.md)
diff --git a/docs/ansible.md b/docs/ansible.md
index 959ba877e..8f952ee11 100644
--- a/docs/ansible.md
+++ b/docs/ansible.md
@@ -1,4 +1,35 @@
-# Ansible variables
+# Ansible
+
+## Installing Ansible
+
+Kubespray supports multiple ansible versions and ships different `requirements.txt` files for them.
+Depending on your available python version you may be limited in chooding which ansible version to use.
+
+It is recommended to deploy the ansible version used by kubespray into a python virtual environment.
+
+```ShellSession
+VENVDIR=kubespray-venv
+KUBESPRAYDIR=kubespray
+ANSIBLE_VERSION=2.12
+virtualenv  --python=$(which python3) $VENVDIR
+source $VENVDIR/bin/activate
+cd $KUESPRAYDIR
+pip install -U -r requirements-$ANSIBLE_VERSION.txt
+test -f requirements-$ANSIBLE_VERSION.yml && \
+  ansible-galaxy role install -r requirements-$ANSIBLE_VERSION.yml && \
+  ansible-galaxy collection -r requirements-$ANSIBLE_VERSION.yml
+```
+
+### Ansible Python Compatibility
+
+Based on the table below and the available python version for your ansible host you should choose the appropriate ansible version to use with kubespray.
+
+| Ansible Version | Python Version |
+| --------------- | -------------- |
+| 2.9             | 2.7,3.5-3.8    |
+| 2.10            | 2.7,3.5-3.8    |
+| 2.11            | 2.7,3.5-3.9    |
+| 2.12            | 3.8-3.10       |
 
 ## Inventory
 
@@ -272,9 +303,3 @@ pip uninstall ansible ansible-base ansible-core
 cd kubespray/
 pip install -U .
 ```
-
-**Note:** some changes needed to support ansible 2.10+ are not backwards compatible with 2.9
-Kubespray needs to evolve and keep pace with upstream ansible and will be forced to eventually
-drop 2.9 support. Kubespray CIs use only the ansible version specified in the `requirements.txt`
-and while the `ansible_version.yml` may allow older versions to be used, these are not
-exercised in the CI and compatibility is not guaranteed.
diff --git a/docs/centos8.md b/docs/centos.md
similarity index 56%
rename from docs/centos8.md
rename to docs/centos.md
index c72fa7178..160e092b1 100644
--- a/docs/centos8.md
+++ b/docs/centos.md
@@ -1,4 +1,11 @@
-# CentOS 8 and derivatives
+# CentOS and derivatives
+
+## CentOS 7
+
+The maximum python version offically 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
 
 CentOS 8 / Oracle Linux 8 / AlmaLinux 8 / Rocky Linux 8 ship only with iptables-nft (ie without iptables-legacy similar to RHEL8)
 The only tested configuration for now is using Calico CNI