[release-0.17] Update docs with cgroups note (#6693)

* Update docs with cgroups note * Add tools section back in --------- Co-authored-by: Christopher Negus <[email protected]>
aws · Sep 15, 2023 · 2f91f04 · 2f91f04
1 parent bfbc88a
commit 2f91f04
Show file tree

Hide file tree

Showing 3 changed files with 56 additions and 8 deletions.
diff --git a/docs/content/en/docs/getting-started/docker/_index.md b/docs/content/en/docs/getting-started/docker/_index.md
@@ -16,14 +16,16 @@ This allows you to try EKS Anywhere on your local machine or laptop before deplo
 
 ### Prerequisites
 
-* Docker 20.x.x
 * Mac OS 10.15+ or Ubuntu 20.04.2+ LTS
+* [Docker 20.x.x](https://docs.docker.com/engine/install/)
+* [`curl`](https://everything.curl.dev/get)
+* [`yq`](https://github.com/mikefarah/yq/#install)
 * Internet access
 * 4 CPU cores
 * 16GB memory
 * 30GB free disk space
 * If you are using Ubuntu, use the Docker CE installation instructions to install Docker and not the Snap installation, as described here.
-* If you are using Ubuntu 21.10 or 22.04, you will need to switch from cgroups v2 to cgroups v1. For details, see Troubleshooting Guide.
+* For EKS Anywhere v0.15 and earlier, if you are using Ubuntu 21.10 or 22.04, you will need to switch from cgroups v2 to cgroups v1. For details, see [Troubleshooting Guide.]({{< relref "../../troubleshooting/troubleshooting.md#for-eks-anywhere-v015-and-earlier-cgroups-v2-is-not-supported-in-ubuntu-2110-and-2204" >}})
 * EKS Anywhere works with x86 and amd64 architectures. It currently will not work on computers with Apple Silicon or Arm based processors.
 
 ### Install EKS Anywhere CLI tools

diff --git a/docs/content/en/docs/getting-started/install/_index.md b/docs/content/en/docs/getting-started/install/_index.md
@@ -28,16 +28,22 @@ See [Create cluster workflow]({{< relref "../overview" >}}) for an overview of t
 - 30GB free disk space
 - Administrative machine must be on the same Layer 2 network as the cluster machines (Bare Metal provider only).
 
+Here are a few other things to keep in mind:
+
+* If you are using Ubuntu, use the Docker CE installation instructions to install Docker and not the Snap installation, as described [here.](https://docs.docker.com/engine/install/ubuntu/)
+
+* If you are using EKS Anywhere v0.15 or earlier and Ubuntu 21.10 or 22.04, you will need to switch from _cgroups v2_ to _cgroups v1_. For details, see [Troubleshooting Guide.]({{< relref "../../troubleshooting/troubleshooting.md#for-eks-anywhere-v015-and-earlier-cgroups-v2-is-not-supported-in-ubuntu-2110-and-2204" >}})
+
+* If you are using Docker Desktop, you need to know that:
+
+  * For EKS Anywhere Bare Metal, Docker Desktop is not supported
+  * For EKS Anywhere vSphere, if you are using EKS Anywhere v0.15 or earlier and Mac OS Docker Desktop 4.4.2 or newer `"deprecatedCgroupv1": true` must be set in `~/Library/Group\ Containers/group.com.docker/settings.json`.
+
 #### Tools
 - [Docker 20.x.x](https://docs.docker.com/engine/install/)
 - [`curl`](https://everything.curl.dev/get)
 - [`yq`](https://github.com/mikefarah/yq/#install)
 
-{{% alert title="Note" color="primary" %}}
-- If you are using Ubuntu, use the Docker CE installation instructions to install Docker as described [here.](https://docs.docker.com/engine/install/ubuntu/) 
-- For EKS Anywhere Bare Metal, Docker Desktop is not supported.
-{{% /alert %}}
-
 ### Install EKS Anywhere CLI tools
 
 #### Via Homebrew (macOS and Linux)
@@ -78,7 +84,7 @@ sudo install -m 0755 ./eksctl-anywhere /usr/local/bin/eksctl-anywhere
 ```
 
 Install the `kubectl` Kubernetes command line tool.
-This can be done by following the instructions [here](https://kubernetes.io/docs/tasks/tools/).
+This can be done by following the instructions [here](https://kubernetes.io/docs/tasks/tools/#kubectl).
 
 Or you can install the latest kubectl directly with the following.
 

diff --git a/docs/content/en/docs/troubleshooting/troubleshooting.md b/docs/content/en/docs/troubleshooting/troubleshooting.md
@@ -48,6 +48,46 @@ Ensure you are running Docker 20.x.x for example:
 % docker --version
 Docker version 20.10.6, build 370c289
 ```
+### Minimum requirements for Docker version have not been met on macOS
+```
+Error: EKS Anywhere does not support Docker Desktop versions between 4.3.0 and 4.4.1 on macOS
+```
+```
+Error: EKS Anywhere requires Docker Desktop to be configured to use CGroups v1. Please  set `deprecatedCgroupv1:true` in your `~/Library/Group\\ Containers/group.com.docker/settings.json` file
+```
+Ensure you are running Docker Desktop 4.4.2 or newer and, if you are running EKS Anywhere v0.15 or earlier, have set `"deprecatedCgroupv1": true` in your settings.json file
+```
+% defaults read /Applications/Docker.app/Contents/Info.plist CFBundleShortVersionString
+4.42
+% docker info --format '{{json .CgroupVersion}}' 
+"1"
+```
+
+### For EKS Anywhere v0.15 and earlier, cgroups v2 is not supported in Ubuntu 21.10+ and 22.04
+```
+ERROR: failed to create cluster: could not find a log line that matches "Reached target .*Multi-User System.*|detected cgroup v1"
+```
+For EKS Anywhere v0.15 and earlier, if you are using Ubuntu it is recommended to use Ubuntu 20.04 for the Administrative Machine. This is because the EKS Anywhere Bootstrap cluster for those versions requires _cgroups v1_. Since Ubuntu 21.10 _cgroups v2_ is enabled by default. You can use Ubuntu 21.10 and 22.04 for the Administrative machine if you configure Ubuntu to use _cgroups v1_ instead. This is not an issue if you are using macOS for your Administrative machine.
+
+To verify cgroups version
+```
+% docker info | grep Cgroup
+ Cgroup Driver: cgroupfs
+ Cgroup Version: 2
+```
+To use _cgroups v1_ you need to _sudo_ and edit _/etc/default/grub_ to set _GRUB_CMDLINE_LINUX_ to "systemd.unified_cgroup_hierarchy=0" and reboot.
+```
+%sudo <editor> /etc/default/grub
+GRUB_CMDLINE_LINUX="systemd.unified_cgroup_hierarchy=0"
+sudo update-grub
+sudo reboot now
+```
+Then verify you are using _cgroups v1_.
+```
+% docker info | grep Cgroup
+ Cgroup Driver: cgroupfs
+ Cgroup Version: 1
+```
 
 ### ECR access denied