Last modified August 16, 2021

gsctl list clusters

gsctl and the REST API are being phased out. We don't have an end-of-life date yet. However, we recommend to familiarize yourself with our Management API and the kubectl gs plugin as a future-proof replacement.

The gsctl list clusters command shows all clusters you have access to with a few details like cluster ID, name, creation date, and owner organization.


$ gsctl list clusters
feogv  acme          Staging     3.0.2    2018 Feb 01, 13:59 UTC
pmb9q  acme          Production  3.0.2    2018 Feb 01, 11:12 UTC
z63so  testteam      Dan's Test  2.7.2    2017 Jun 19, 09:12 UTC  

The details displayed are:

  • ID: The unique cluster ID.
  • ORGANIZATION: The cluster’s owner organization.
  • NAME: The name selected for the cluster on creation.
  • RELEASE: The version of the workload cluster release used by the cluster. For older clusters, this may be n/a.
  • CREATED: The date and time when the cluster has been created (UTC).

The --selector flag can be used to filter the output based on a set of requirements.

$ gsctl list clusters --selector environment=testing
z63so  testteam      Dan's Test  2.7.2    2017 Jun 19, 09:12 UTC

In this example, cluster z63so is the only cluster with label environment=testing. More information about possible queries can be found in the Kubernetes Labels and Selectors documentation.

Argument reference

  • --output or -o: Using this flag with the value json, the output can be printed in JSON format. This is convenient for use in automation. The default output format is table, which results in an output like shown above.
  • --show-deleting: Set this flag to also list clusters that are currently being deleted and add a DELETING SINCE column.
  • --selector or -l: Label selector query to filter clusters on. Accepts a single string containing multiple selector requirements which are comma-separated. In the case of multiple requirements, all must be satisfied so the comma separator acts as a logical AND (&&) operator. This feature is only available for clusters with workload cluster release v10.0.0 and above on AWS.
  • --sort or -s: Sort clusters by one of the columns, in ascending order. The default value is id. Accepted values: id, created, name, organization, release, deleting-since. Providing a small part of the column name is also accepted: d/del/deleting are all valid for the deleting-since value.