Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📖 Document clusterctl describe #4123

Merged
merged 1 commit into from
Jan 26, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
1 change: 1 addition & 0 deletions docs/book/src/clusterctl/commands/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
45 changes: 45 additions & 0 deletions docs/book/src/clusterctl/commands/describe-cluster.md
Original file line number Diff line number Diff line change
@@ -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).
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/book/src/images/describe-cluster.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.