Various documentation updates (#8243)

* Docs: update CONTRIBUTING.md

* Docs: clean up outdated roadmap and point to github issues instead

* Docs: update note on kubelet_cgroup_driver

* Docs: update kata containers docs with note about cgroup driver

* Docs: note about CI specific overrides

CONTRIBUTING.md

@@ -6,11 +6,17 @@
 
 It is recommended to use filter to manage the GitHub email notification, see [examples for setting filters to Kubernetes Github notifications](https://github.com/kubernetes/community/blob/master/communication/best-practices.md#examples-for-setting-filters-to-kubernetes-github-notifications)
 
-To install development dependencies you can use `pip install -r tests/requirements.txt`
+To install development dependencies you can set up a python virtual env with the necessary dependencies:
+
+```ShellSession
+virtualenv venv
+source venv/bin/activate
+pip install -r tests/requirements.txt
+```
 
 #### Linting
 
-Kubespray uses `yamllint` and `ansible-lint`. To run them locally use `yamllint .` and `ansible-lint`
+Kubespray uses `yamllint` and `ansible-lint`. To run them locally use `yamllint .` and `ansible-lint`. It is a good idea to add call these tools as part of your pre-commit hook and avoid a lot of back end forth on fixing linting issues (<https://support.gitkraken.com/working-with-repositories/githooksexample/>).
 
 #### Molecule
 
@@ -29,3 +35,5 @@ Vagrant with VirtualBox or libvirt driver helps you to quickly spin test cluster
 3. Fork the desired repo, develop and test your code changes.
 4. Sign the CNCF CLA (<https://git.k8s.io/community/CLA.md#the-contributor-license-agreement>)
 5. Submit a pull request.
+6. Work with the reviewers on their suggestions.
+7. Ensure to rebase to the HEAD of your target branch and squash un-necessary commits (<https://blog.carbonfive.com/always-squash-and-rebase-your-git-commits/>) before final merger of your contribution.

docs/ci-setup.md

@@ -18,3 +18,10 @@ Kubespray has 3 types of GitLab runners:
 ## Vagrant
 
 Vagrant jobs are using the [quay.io/kubespray/vagrant](/test-infra/vagrant-docker/Dockerfile) docker image with `/var/run/libvirt/libvirt-sock` exposed from the host, allowing the container to boot VMs on the host.
+
+## CI Variables
+
+In CI we have a set of overrides we use to ensure greater success of our CI jobs and avoid throttling by various APIs we depend on. See:
+
+- [Docker mirrors](/tests/common/_docker_hub_registry_mirror.yml)
+- [Test settings](/tests/common/_kubespray_test_settings.yml)

docs/kata-containers.md

@@ -37,10 +37,18 @@ Pod Overhead is mandatory if you run Pods with Kata Containers that use [resourc
 
 To enable Pod Overhead feature you have to configure Kubelet with the appropriate cgroup driver, using the following configuration:
 
+`cgroupfs` works best:
+
 ```yaml
 kubelet_cgroup_driver: cgroupfs
 ```
 
+... but when using `cgroups v2` (see <https://www.redhat.com/en/blog/world-domination-cgroups-rhel-8-welcome-cgroups-v2>) you can use systemd as well:
+
+```yaml
+kubelet_cgroup_driver: systemd
+```
+
 **Qemu hypervisor configuration**:
 
 The configuration for the Qemu hypervisor uses the following values:
@@ -56,7 +64,7 @@ kata_containers_qemu_overhead_fixed_memory: 290Mi
 Optionally you can select the Kata Containers release version to be installed. The available releases are published in [GitHub](https://github.com/kata-containers/runtime/releases).
 
 ```yaml
-kata_containers_version: 1.11.1
+kata_containers_version: 2.2.2
 ```
 
 ### Optional : Debug

docs/roadmap.md

@@ -1,62 +1,3 @@
 # Kubespray's roadmap
 
-## Self deployment (pull-mode) [#320](https://github.com/kubespray/kubespray/issues/320)
+We are tracking the evolution towards Kubespray 3.0 in [#6400](https://github.com/kubernetes-sigs/kubespray/issues/6400) as well as in other open issue in our [github issues](https://github.com/kubernetes-sigs/kubespray/issues/) section.
-
-- the playbook would install and configure docker and the etcd cluster
-- the following data would be inserted into etcd: certs,tokens,users,inventory,group_vars.
-- a "kubespray" container would be deployed (kubespray-cli, ansible-playbook)
-- to be discussed, a way to provide the inventory
-- **self deployment** of the node from inside a container [#321](https://github.com/kubespray/kubespray/issues/321)
-
-## Provisioning and cloud providers
-
-- [ ] Terraform to provision instances on:
-  - [ ] GCE
-  - [x] AWS (contrib/terraform/aws)
-  - [x] OpenStack (contrib/terraform/openstack)
-  - [x] Equinix Metal
-  - [ ] Digital Ocean
-  - [ ] Azure
-- [ ] On AWS autoscaling, multi AZ
-- [ ] On Azure autoscaling, create loadbalancer [#297](https://github.com/kubespray/kubespray/issues/297)
-- [ ] On GCE be able to create a loadbalancer automatically (IAM ?) [#280](https://github.com/kubespray/kubespray/issues/280)
-- [x] **TLS bootstrap** support for kubelet (covered by kubeadm, but not in standard deployment) [#234](https://github.com/kubespray/kubespray/issues/234)
-  (related issues: <https://github.com/kubernetes/kubernetes/pull/20439> <https://github.com/kubernetes/kubernetes/issues/18112)>
-
-## Tests
-
-- [x] Run kubernetes e2e tests
-- [ ] Test idempotency on single OS but for all network plugins/container engines
-- [ ] single test on AWS per day
-- [ ] test scale up cluster:  +1 etcd, +1 control plane, +1 node
-- [x] Reorganize CI test vars into group var files
-
-## Lifecycle
-
-- [ ] Upgrade granularity: select components to upgrade and skip others
-
-## Networking
-
-- [ ] Opencontrail
-- [ ] Consolidate roles/network_plugin and roles/kubernetes-apps/network_plugin
-
-## Kubespray API
-
-- Perform all actions through an **API**
-- Store inventories / configurations of multiple clusters
-- Make sure that state of cluster is completely saved in no more than one config file beyond hosts inventory
-
-## Addons (helm or native ansible)
-
-- [x] Helm
-- [x] Ingress-nginx
-- [x] kubernetes-dashboard
-
-## Others
-
-- Organize and update documentation (split in categories)
-- Refactor downloads so it all runs in the beginning of deployment
-- Make bootstrapping OS more consistent
-- **consul** -> if officially supported by k8s
-- Flex volumes options (e.g. **torrus** support) [#312](https://github.com/kubespray/kubespray/issues/312)
-- Clusters federation option (aka **ubernetes**) [#329](https://github.com/kubespray/kubespray/issues/329)

docs/vars.md

@@ -125,9 +125,9 @@ Stack](https://github.com/kubernetes-sigs/kubespray/blob/master/docs/dns-stack.m
 * *http_proxy/https_proxy/no_proxy/no_proxy_exclude_workers/additional_no_proxy* - Proxy variables for deploying behind a
   proxy. Note that no_proxy defaults to all internal cluster IPs and hostnames
   that correspond to each node.
-* *kubelet_cgroup_driver* - Allows manual override of the
+* *kubelet_cgroup_driver* - Allows manual override of the cgroup-driver option for Kubelet.
-  cgroup-driver option for Kubelet. By default autodetection is used
+  By default autodetection is used to match container manager configuration.
-  to match Docker configuration.
+  `systemd` is the preferred driver for `containerd` though it can have issues with `cgroups v1` and `kata-containers` in which case you may want to change to `cgroupfs`.
 * *kubelet_rotate_certificates* - Auto rotate the kubelet client certificates by requesting new certificates
   from the kube-apiserver when the certificate expiration approaches.
 * *kubelet_rotate_server_certificates* - Auto rotate the kubelet server certificates by requesting new certificates