diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 7e402b4e7e3e..0bf152e48453 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -22,6 +22,7 @@ - [config cluster](clusterctl/commands/config-cluster.md) - [generate yaml](clusterctl/commands/generate-yaml.md) - [get kubeconfig](clusterctl/commands/get-kubeconfig.md) + - [describe cluster](clusterctl/commands/describe-cluster.md) - [move](./clusterctl/commands/move.md) - [upgrade](clusterctl/commands/upgrade.md) - [delete](clusterctl/commands/delete.md) diff --git a/docs/book/src/clusterctl/commands/commands.md b/docs/book/src/clusterctl/commands/commands.md index 2d651dcde8c7..a6fcdc8bc1e3 100644 --- a/docs/book/src/clusterctl/commands/commands.md +++ b/docs/book/src/clusterctl/commands/commands.md @@ -4,6 +4,7 @@ * [`clusterctl config cluster`](config-cluster.md) * [`clusterctl generate yaml`](generate-yaml.md) * [`clusterctl get kubeconfig`](get-kubeconfig.md) +* [`clusterctl describe cluster`](describe-cluster.md) * [`clusterctl move`](move.md) * [`clusterctl upgrade`](upgrade.md) * [`clusterctl delete`](delete.md) diff --git a/docs/book/src/clusterctl/commands/describe-cluster.md b/docs/book/src/clusterctl/commands/describe-cluster.md new file mode 100644 index 000000000000..8b4fd6243e26 --- /dev/null +++ b/docs/book/src/clusterctl/commands/describe-cluster.md @@ -0,0 +1,45 @@ +# clusterctl describe cluster + +The `clusterctl describe cluster` command provides an "at glance" view of a Cluster API cluster designed +to help the user in quickly understanding if there are problems and where. + +For example `clusterctl describe cluster capi-quickstart` will provide an output similar to: + +![](../../images/describe-cluster.png) + +The "at glance" view is based on the idea that clusterctl should avoid to overload the user with information, +but instead surface problems, if any. + +In practice, if you look at the `ControlPlane` node, you might notice that the underlying machines +are grouped together, because all of them have the same state (Ready equal to True), so it is not +necessary to repeat the same information three times. + +If this is not the case, and machines have different states, the visualization is going to use different lines: + +![](../../images/describe-cluster-how-grouping-works.png) + +You might also notice that the visualization does not represent the infrastructure machine or the +bootstrap object linked to a machine, unless their state differs from the machine's state. + +## Customizing the visualization + +By default the visualization generated by `clusterctl describe cluster` hides details for the sake +of simplicity and shortness. However, if required, the user can ask for showing all the detail: + +By using the `--disable-grouping` flag, the user can force the visualization to show all the machines +on separated lines, no matter if they have the same state or not: + +![](../../images/describe-cluster-disable-grouping.png) + +By using the `--disable-no-echo` flag, the user can force the visualization to show infrastructure machines and +bootstrap objects linked to machines, no matter if they have the same state or not: + +![](../../images/describe-cluster-disable-no-echo.png) + +It is also possible to force the visualization to show all the conditions for an object (instead of showing +only the ready condition). e.g. with `--show-conditions KubeadmControlPlane` you get: + +![](../../images/describe-cluster-show-conditions.png) + +Please note that this option is flexible, and you can pass a comma separated list of `kind` or `kind/name` for +which the command should show all the object's conditions (use 'all' to show conditions for everything). diff --git a/docs/book/src/images/describe-cluster-disable-grouping.png b/docs/book/src/images/describe-cluster-disable-grouping.png new file mode 100644 index 000000000000..cfed83a44751 Binary files /dev/null and b/docs/book/src/images/describe-cluster-disable-grouping.png differ diff --git a/docs/book/src/images/describe-cluster-disable-no-echo.png b/docs/book/src/images/describe-cluster-disable-no-echo.png new file mode 100644 index 000000000000..9b0a6e570be4 Binary files /dev/null and b/docs/book/src/images/describe-cluster-disable-no-echo.png differ diff --git a/docs/book/src/images/describe-cluster-how-grouping-works.png b/docs/book/src/images/describe-cluster-how-grouping-works.png new file mode 100644 index 000000000000..57cde5df3609 Binary files /dev/null and b/docs/book/src/images/describe-cluster-how-grouping-works.png differ diff --git a/docs/book/src/images/describe-cluster-show-conditions.png b/docs/book/src/images/describe-cluster-show-conditions.png new file mode 100644 index 000000000000..1ca48ce2318a Binary files /dev/null and b/docs/book/src/images/describe-cluster-show-conditions.png differ diff --git a/docs/book/src/images/describe-cluster.png b/docs/book/src/images/describe-cluster.png new file mode 100644 index 000000000000..671b69ddb330 Binary files /dev/null and b/docs/book/src/images/describe-cluster.png differ