Add troubleshooting advice when running Quick Start with CAPD on Linux

Adds information about ulimit and inotify for Linux. The default values
where too low on Ubuntu 22.04 LTS for the Machines to start.

docs/book/src/introduction.md

@@ -6,7 +6,7 @@ Started by the Kubernetes Special Interest Group (SIG) [Cluster Lifecycle](https
 
 ## Getting started
 
-* [Quick start](./user/quick-start.md)
+* [Quick Start](./user/quick-start.md)
 * [Concepts](./user/concepts.md)
 * [Developer guide](./developer/guide.md)
 * [Contributing](./CONTRIBUTING.md)

docs/book/src/tasks/certs/using-custom-certificates.md

@@ -12,7 +12,7 @@ Each certificate must be stored in a single secret named one of:
 | *[cluster name]***-sa**  | Key Pair | openssl genrsa -out tls.key 2048 && openssl rsa -in tls.key -pubout -out tls.crt |
 
 
-<aside class="note warn">
+<aside class="note warning">
 
 <h1>CA Key Age</h1>
 

docs/book/src/user/quick-start.md

@@ -47,7 +47,9 @@ a target [management cluster] on the selected [infrastructure provider].
 
    **Minimum [kind] supported version**: v0.14.0
 
-   Note for macOS users: you may need to [increase the memory available](https://docs.docker.com/docker-for-mac/#resources) for containers (recommend 6Gb for CAPD).
+   Note for macOS users: you may need to [increase the memory available](https://docs.docker.com/docker-for-mac/#resources) for containers (recommend 6 GB for CAPD).
+
+   Note for Linux users: you may need to increase `ulimit` and `inotify` when using Docker (CAPD). Machines can fail to start if limits such as `fs.inotify.max_user_instances` are too low.
 
    </aside>
 
@@ -944,6 +946,40 @@ You can also get an "at glance" view of the cluster and its resources by running
 clusterctl describe cluster capi-quickstart
 ```
 
+<aside class="note warning">
+
+<h1>If machines fail to start using Docker</h1>
+
+In the example below we can see that the Machine `capi-quickstart-6587k-xtvnz` has failed to start. The reason provided is `BootstrapFailed`.
+
+```shell
+clusterctl describe cluster capi-quickstart
+NAME                                                           READY  SEVERITY  REASON                       SINCE  MESSAGE
+Cluster/capi-quickstart                                        False  Warning   ScalingUp                    57s    Scaling up control plane to 3 replicas (actual 2)
+├─ClusterInfrastructure - DockerCluster/capi-quickstart-n5w87  True                                          110s
+├─ControlPlane - KubeadmControlPlane/capi-quickstart-6587k     False  Warning   ScalingUp                    57s    Scaling up control plane to 3 replicas (actual 2)
+│ ├─Machine/capi-quickstart-6587k-fgc6m                        True                                          81s
+│ └─Machine/capi-quickstart-6587k-xtvnz                        False  Warning   BootstrapFailed              52s    1 of 2 completed
+└─Workers
+  └─MachineDeployment/capi-quickstart-md-0-5whtj               False  Warning   WaitingForAvailableMachines  110s   Minimum availability requires 3 replicas, current 0 available
+    └─3 Machines...                                            False  Info      Bootstrapping                77s    See capi-quickstart-md-0-5whtj-5d8c9746c9-f8sw8, capi-quickstart-md-0-5whtj-5d8c9746c9-hzxc2, ...
+```
+
+To investigate why a machine fails to start you can inspect the logs using `docker logs <MACHINE-NAME>`. For example:
+
+```shell
+docker logs capi-quickstart-6587k-xtvnz
+(...)
+Failed to create control group inotify object: Too many open files
+Failed to allocate manager object: Too many open files
+[!!!!!!] Failed to allocate manager object.
+Exiting PID 1...
+```
+
+To resolve this error we need to increase `fs.inotify.max_user_instances`. After increasing the limit, perform a [clean up](#clean-up) and restart the Quick Start from the beginning.
+
+</aside>
+
 To verify the first control plane is up:
 
 ```bash