Listing Your Clusters

You can list the clusters you have created. This action also returns information about their status and time of creation.

Listing Your Clusters Using Cockpit

In the Projects dashboard, click the name of the project whose clusters you want to list.
The project details panel appears.
Click the Clusters tab.
The list of your clusters appears.

Listing Your Clusters Using octl

Listing Clusters Associated With a Project

The ListClustersByProjectID command lists one or more clusters associated with a project. The response can be filtered using the parameters.

Request sample

$ octl kube api ListClustersByProjectID --profile "default" \
  --ProjectId "string" \
  --Name "string" \
  --Status "string" \
  --Version "string" \
  --Deleted=true \
  --Cursor "string" \
  --Page 0 \
  --Limit 1

This command contains the following options that you need to specify:

Cursor: (optional) The token to indicate where the next set of results should start.
Deleted: (optional) If true, returns deleted clusters.
Limit: (optional) The maximum number of results to return in the response.
Minimum value: 1. Maximum value: 100.
Name: (optional) The name of the clusters.
Page: (optional) The page number of results to retrieve.
ProjectId: (optional) The ID of the project.
Status: (optional) The status of the clusters.
Version: (optional) The version of the clusters.

The ListClustersByProjectID command returns the following elements:

ResponseContext: Information about the context of the response.
- RequestId: The ID of the API request.
Pagination: Information used to split large lists of results into multiple responses (either cursor or offset-based).
- cursor: Information used for cursor-based pagination.
  - next_cursor: The pagination token indicating where the next set of results should start.
- offset: Information used for offset-based pagination.
  - page: The page number of the current results.
  - limit: The maximum number of results returned per page.
  - total: The total number of available results.
Clusters: Information about the clusters.
- project_id: The ID of the project this cluster belongs to.
- id: The Universally Unique Identifier (UUID) of the cluster.
- name: A unique name for the cluster within the project.
- description: An optional description of the cluster.
  Default: .
- cp_multi_az: If true, multi-Subregion deployment is enabled for the control plane. If false, it is disabled.
- cp_subregions: The Subregions on which the control plane components are deployed.
- version: The Kubernetes version deployed for the cluster. For more information, see GetKubernetesVersions.
- expected_version: The version of Kubernetes that is expected to be deployed during maintenance.
- cni: The Container Network Interface (CNI) used in the cluster.
- admin_lbu: If true, load balancer administration is enabled for cluster management. If false, it is disabled.
- admission_flags: The configuration for Kubernetes admission controllers.
  - disable_admission_plugins: The list of Kubernetes admission plugins that are disabled.
    Default: [].
  - enable_admission_plugins: The list of Kubernetes admission plugins that are enabled.
    Default: [].
  - applied_admission_plugins: The list of admission plugins that are currently applied to the cluster.
    Default: ["CertificateApproval", "CertificateSigning", "CertificateSubjectRestriction", "ClusterTrustBundleAttest", "DefaultIngressClass", "DefaultStorageClass", "DefaultTolerationSeconds", "LimitRanger", "MutatingAdmissionWebhook", "NamespaceLifecycle", "PersistentVolumeClaimResize", "PodSecurity", "Priority", "ResourceQuota", "RuntimeClass", "ServiceAccount", "StorageObjectInUseProtection", "TaintNodesByCondition", "ValidatingAdmissionPolicy", "ValidatingAdmissionWebhook"].
- cidr_pods: The CIDR block of the Kubernetes pods' network.
- cidr_service: The CIDR block of the Kubernetes services' network.
- cluster_dns: The IP of the cluster’s DNS service.
- tags: The key/value combinations of the tags associated with the cluster, in the following format: "tags":{"TAGKEY1":"TAGVALUE1","TAGKEY2":"TAGVALUE2"}.
  Example: {"key": "value"}.
- auto_maintenances (deprecated): The configuration for automated maintenance windows.
  - minor_upgrade_maintenance: The maintenance window configuration for minor Kubernetes upgrades.
    
    enabled: If true, a maintenance window is enabled.
    Default: true.
    
    duration_hours: The duration of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23. Default: 0.
    
    start_hour: The starting time of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23. Default: 12.
    
    week_day: The weekday on which the maintenance window begins.
    Possible values: Mon | Tue | Wed | Thu | Fri | Sat | Sun | string. Default: Tue.
    
    tz: The timezone for the maintenance window.
    Default: UTC.
  - patch_upgrade_maintenance: The maintenance window configuration for patch Kubernetes upgrades.
    
    enabled: If true, a maintenance window is enabled.
    Default: true.
    
    duration_hours: The duration of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23. Default: 0.
    
    start_hour: The starting time of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23. Default: 12.
    
    week_day: The weekday on which the maintenance window begins.
    Possible values: Mon | Tue | Wed | Thu | Fri | Sat | Sun | string. Default: Tue.
    
    tz: The timezone for the maintenance window.
    Default: UTC.
- maintenance_window: The configuration for automated maintenance windows.
  - duration_hours: The duration of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23.
  - start_hour: The starting time of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23.
  - week_day: The weekday on which the maintenance window begins.
    Possible values: Mon | Tue | Wed | Thu | Fri | Sat | Sun | string.
  - tz: The timezone for the maintenance window.
    Default: UTC.
- control_planes: The control plane sizing of the cluster.
- expected_control_planes: The type of control plane size that is expected.
- admin_whitelist: The list of CIDR blocks or IPs allowed to access the cluster via the Kubernetes API.
- statuses: The status information of the cluster.
  - created_at: The timestamp when the cluster was created.
  - deleted_at: The timestamp when the cluster was deleted (if applicable).
  - updated_at: The timestamp when the cluster was last updated.
  - status: The status of the cluster.
  - available_upgrade: Any available version of Kubernetes for upgrade (if applicable). For more information, see GetKubernetesVersions.
    Default: .
- disable_api_termination: If true, cluster deletion through the API is disabled. If false, it is enabled.
  Default: false.
- auth: The authentication strategy used to access the cluster.
  - oidc: The configuration for authenticating to the cluster using OpenID Connect (OIDC).
    
    issuer-url: The server URL of the OIDC provider, using the HTTPS protocol (https://).
    
    client-id: The client ID provided by the OIDC provider. This will be used by the cluster to connect to the server.
    
    username-claim: A JSON Web Token (JWT) claim provided by the OIDC provider. This will be used to retrieve the username on the Kubernetes side.
    
    username-prefix: A prefix added to the Kubernetes username, to prevent clashing with existing names (for example, oidc:).
    
    groups-claim: A JSON Web Token (JWT) claim provided by the OIDC provider. This will be used to retrieve the user’s group on the Kubernetes side.
    
    groups-prefix: A prefix added to the Kubernetes group, to prevent clashing with existing names (for example, oidc:).
    
    required-claim: The key/value combination of OIDC claims that must be included in the ID token for the user to authenticate. If not specified, no claim-based restrictions are enforced.
    Example: {"claim": "value"}.

Result sample

{
  "ResponseContext": {
    "RequestId": "string"
  },
  "Pagination": {
    "cursor": {
      "next_cursor": "string"
    },
    "offset": {
      "page": 0,
      "limit": 0,
      "total": 0
    }
  },
  "Clusters": [
    {
      "project_id": "string",
      "id": "string",
      "name": "string",
      "description": "",
      "cp_multi_az": true,
      "cp_subregions": [
        "string"
      ],
      "version": "string",
      "expected_version": "string",
      "cni": "string",
      "admin_lbu": true,
      "admission_flags": {
        "disable_admission_plugins": [],
        "enable_admission_plugins": [],
        "applied_admission_plugins": [
          "CertificateApproval",
          "CertificateSigning",
          "CertificateSubjectRestriction",
          "ClusterTrustBundleAttest",
          "DefaultIngressClass",
          "DefaultStorageClass",
          "DefaultTolerationSeconds",
          "LimitRanger",
          "MutatingAdmissionWebhook",
          "NamespaceLifecycle",
          "PersistentVolumeClaimResize",
          "PodSecurity",
          "Priority",
          "ResourceQuota",
          "RuntimeClass",
          "ServiceAccount",
          "StorageObjectInUseProtection",
          "TaintNodesByCondition",
          "ValidatingAdmissionPolicy",
          "ValidatingAdmissionWebhook"
        ]
      },
      "cidr_pods": "string",
      "cidr_service": "string",
      "cluster_dns": "string",
      "tags": {
        "key": "value"
      },
      "auto_maintenances": {
        "minor_upgrade_maintenance": {
          "enabled": true,
          "duration_hours": 0,
          "start_hour": 12,
          "week_day": "Mon",
          "tz": "UTC"
        },
        "patch_upgrade_maintenance": {
          "enabled": true,
          "duration_hours": 0,
          "start_hour": 12,
          "week_day": "Mon",
          "tz": "UTC"
        }
      },
      "maintenance_window": {
        "duration_hours": 23,
        "start_hour": 23,
        "week_day": "Mon",
        "tz": "UTC"
      },
      "control_planes": "string",
      "expected_control_planes": "string",
      "admin_whitelist": [
        "string"
      ],
      "statuses": {
        "created_at": "2019-08-24T14:15:22Z",
        "deleted_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "status": "string",
        "available_upgrade": ""
      },
      "disable_api_termination": false,
      "auth": {
        "oidc": {
          "issuer-url": "string",
          "client-id": "string",
          "username-claim": "string",
          "username-prefix": "string",
          "groups-claim": [
            "string"
          ],
          "groups-prefix": "string",
          "required-claim": {
            "claim": "value"
          }
        }
      }
    }
  ]
}

Listing Your Clusters

The ListAllClusters command lists one or more of your clusters. The response can be filtered using the parameters.

Request sample

$ octl kube api ListAllClusters --profile "default" \
  --Name "string" \
  --Status "string" \
  --Version "string" \
  --Deleted=true \
  --Cursor "string" \
  --Page 0 \
  --Limit 1

This command contains the following options that you need to specify:

Cursor: (optional) The token to indicate where the next set of results should start in cursor-based pagination.
Deleted: (optional) If true, returns deleted clusters.
Limit: (optional) The maximum number of results to return in the response.
Minimum value: 1. Maximum value: 100.
Name: (optional) The name of the clusters.
Page: (optional) The page number of results to retrieve.
Status: (optional) The status of the clusters.
Version: (optional) The version of the clusters.

The ListAllClusters command returns the following elements:

ResponseContext: Information about the context of the response.
- RequestId: The ID of the API request.
Pagination: Information used to split large lists of results into multiple responses (either cursor or offset-based).
- cursor: Information used for cursor-based pagination.
  - next_cursor: The pagination token indicating where the next set of results should start.
- offset: Information used for offset-based pagination.
  - page: The page number of the current results.
  - limit: The maximum number of results returned per page.
  - total: The total number of available results.
Clusters: Information about the clusters.
- project_id: The ID of the project this cluster belongs to.
- id: The Universally Unique Identifier (UUID) of the cluster.
- name: A unique name for the cluster within the project.
- description: An optional description of the cluster.
  Default: .
- cp_multi_az: If true, multi-Subregion deployment is enabled for the control plane. If false, it is disabled.
- cp_subregions: The Subregions on which the control plane components are deployed.
- version: The Kubernetes version deployed for the cluster. For more information, see GetKubernetesVersions.
- expected_version: The version of Kubernetes that is expected to be deployed during maintenance.
- cni: The Container Network Interface (CNI) used in the cluster.
- admin_lbu: If true, load balancer administration is enabled for cluster management. If false, it is disabled.
- admission_flags: The configuration for Kubernetes admission controllers.
  - disable_admission_plugins: The list of Kubernetes admission plugins that are disabled.
    Default: [].
  - enable_admission_plugins: The list of Kubernetes admission plugins that are enabled.
    Default: [].
  - applied_admission_plugins: The list of admission plugins that are currently applied to the cluster.
    Default: ["CertificateApproval", "CertificateSigning", "CertificateSubjectRestriction", "ClusterTrustBundleAttest", "DefaultIngressClass", "DefaultStorageClass", "DefaultTolerationSeconds", "LimitRanger", "MutatingAdmissionWebhook", "NamespaceLifecycle", "PersistentVolumeClaimResize", "PodSecurity", "Priority", "ResourceQuota", "RuntimeClass", "ServiceAccount", "StorageObjectInUseProtection", "TaintNodesByCondition", "ValidatingAdmissionPolicy", "ValidatingAdmissionWebhook"].
- cidr_pods: The CIDR block of the Kubernetes pods' network.
- cidr_service: The CIDR block of the Kubernetes services' network.
- cluster_dns: The IP of the cluster’s DNS service.
- tags: The key/value combinations of the tags associated with the cluster, in the following format: "tags":{"TAGKEY1":"TAGVALUE1","TAGKEY2":"TAGVALUE2"}.
  Example: {"key": "value"}.
- auto_maintenances (deprecated): The configuration for automated maintenance windows.
  - minor_upgrade_maintenance: The maintenance window configuration for minor Kubernetes upgrades.
    
    enabled: If true, a maintenance window is enabled.
    Default: true.
    
    duration_hours: The duration of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23. Default: 0.
    
    start_hour: The starting time of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23. Default: 12.
    
    week_day: The weekday on which the maintenance window begins.
    Possible values: Mon | Tue | Wed | Thu | Fri | Sat | Sun | string. Default: Tue.
    
    tz: The timezone for the maintenance window.
    Default: UTC.
  - patch_upgrade_maintenance: The maintenance window configuration for patch Kubernetes upgrades.
    
    enabled: If true, a maintenance window is enabled.
    Default: true.
    
    duration_hours: The duration of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23. Default: 0.
    
    start_hour: The starting time of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23. Default: 12.
    
    week_day: The weekday on which the maintenance window begins.
    Possible values: Mon | Tue | Wed | Thu | Fri | Sat | Sun | string. Default: Tue.
    
    tz: The timezone for the maintenance window.
    Default: UTC.
- maintenance_window: The configuration for automated maintenance windows.
  - duration_hours: The duration of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23.
  - start_hour: The starting time of the maintenance window, in hours.
    Minimum value: 0. Maximum value: 23.
  - week_day: The weekday on which the maintenance window begins.
    Possible values: Mon | Tue | Wed | Thu | Fri | Sat | Sun | string.
  - tz: The timezone for the maintenance window.
    Default: UTC.
- control_planes: The control plane sizing of the cluster.
- expected_control_planes: The type of control plane size that is expected.
- admin_whitelist: The list of CIDR blocks or IPs allowed to access the cluster via the Kubernetes API.
- statuses: The status information of the cluster.
  - created_at: The timestamp when the cluster was created.
  - deleted_at: The timestamp when the cluster was deleted (if applicable).
  - updated_at: The timestamp when the cluster was last updated.
  - status: The status of the cluster.
  - available_upgrade: Any available version of Kubernetes for upgrade (if applicable). For more information, see GetKubernetesVersions.
    Default: .
- disable_api_termination: If true, cluster deletion through the API is disabled. If false, it is enabled.
  Default: false.
- auth: The authentication strategy used to access the cluster.
  - oidc: The configuration for authenticating to the cluster using OpenID Connect (OIDC).
    
    issuer-url: The server URL of the OIDC provider, using the HTTPS protocol (https://).
    
    client-id: The client ID provided by the OIDC provider. This will be used by the cluster to connect to the server.
    
    username-claim: A JSON Web Token (JWT) claim provided by the OIDC provider. This will be used to retrieve the username on the Kubernetes side.
    
    username-prefix: A prefix added to the Kubernetes username, to prevent clashing with existing names (for example, oidc:).
    
    groups-claim: A JSON Web Token (JWT) claim provided by the OIDC provider. This will be used to retrieve the user’s group on the Kubernetes side.
    
    groups-prefix: A prefix added to the Kubernetes group, to prevent clashing with existing names (for example, oidc:).
    
    required-claim: The key/value combination of OIDC claims that must be included in the ID token for the user to authenticate. If not specified, no claim-based restrictions are enforced.
    Example: {"claim": "value"}.

Result sample

{
  "ResponseContext": {
    "RequestId": "string"
  },
  "Pagination": {
    "cursor": {
      "next_cursor": "string"
    },
    "offset": {
      "page": 0,
      "limit": 0,
      "total": 0
    }
  },
  "Clusters": [
    {
      "project_id": "string",
      "id": "string",
      "name": "string",
      "description": "",
      "cp_multi_az": true,
      "cp_subregions": [
        "string"
      ],
      "version": "string",
      "expected_version": "string",
      "cni": "string",
      "admin_lbu": true,
      "admission_flags": {
        "disable_admission_plugins": [],
        "enable_admission_plugins": [],
        "applied_admission_plugins": [
          "CertificateApproval",
          "CertificateSigning",
          "CertificateSubjectRestriction",
          "ClusterTrustBundleAttest",
          "DefaultIngressClass",
          "DefaultStorageClass",
          "DefaultTolerationSeconds",
          "LimitRanger",
          "MutatingAdmissionWebhook",
          "NamespaceLifecycle",
          "PersistentVolumeClaimResize",
          "PodSecurity",
          "Priority",
          "ResourceQuota",
          "RuntimeClass",
          "ServiceAccount",
          "StorageObjectInUseProtection",
          "TaintNodesByCondition",
          "ValidatingAdmissionPolicy",
          "ValidatingAdmissionWebhook"
        ]
      },
      "cidr_pods": "string",
      "cidr_service": "string",
      "cluster_dns": "string",
      "tags": {
        "key": "value"
      },
      "auto_maintenances": {
        "minor_upgrade_maintenance": {
          "enabled": true,
          "duration_hours": 0,
          "start_hour": 12,
          "week_day": "Mon",
          "tz": "UTC"
        },
        "patch_upgrade_maintenance": {
          "enabled": true,
          "duration_hours": 0,
          "start_hour": 12,
          "week_day": "Mon",
          "tz": "UTC"
        }
      },
      "maintenance_window": {
        "duration_hours": 23,
        "start_hour": 23,
        "week_day": "Mon",
        "tz": "UTC"
      },
      "control_planes": "string",
      "expected_control_planes": "string",
      "admin_whitelist": [
        "string"
      ],
      "statuses": {
        "created_at": "2019-08-24T14:15:22Z",
        "deleted_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "status": "string",
        "available_upgrade": ""
      },
      "disable_api_termination": false,
      "auth": {
        "oidc": {
          "issuer-url": "string",
          "client-id": "string",
          "username-claim": "string",
          "username-prefix": "string",
          "groups-claim": [
            "string"
          ],
          "groups-prefix": "string",
          "required-claim": {
            "claim": "value"
          }
        }
      }
    }
  ]
}

Listing Your Clusters Using OKS CLI

The cluster list command lists all available clusters and allows you to check their status. You can use it with the following syntax:

Request sample

$ oks-cli cluster list \
    --project-name NAME_OF_PROJECT \
    --output json

This command contains the following options that you may need to specify:

project-name: The name of the project containing the clusters that you want to list.
(optional) cluster-name: The name of the cluster.
(optional) deleted: The ability to list deleted clusters.
(optional) output: The output format for the response (json | yaml | wide).

Result sample

+-------------+-------------+--------------+------------+---------+
|     NAME    |   CREATED   |    UPDATED   |   STATUS   | DEFAULT |
+-------------+-------------+--------------+------------+---------+
|  my-cluster |  a day ago  |   a day ago  |   ready    |         |
+-------------+-------------+--------------+------------+---------+

Using the wide output format displays additional information about the listed clusters:

Result sample

+--------------------------------------+-------------+-------------+--------------+------------+---------+---------+--------------------+
|                  ID                  |     NAME    |   CREATED   |    UPDATED   |   STATUS   | DEFAULT | VERSION |   CONTROL PLANE    |
+--------------------------------------+-------------+-------------+--------------+------------+---------+---------+--------------------+
| ee46b46c-c20a-4c56-a791-74e523ec17ae |  my-cluster |  a day ago  |   a day ago  |   ready    |         |   1.31  | cp.3.masters.small |
+--------------------------------------+-------------+-------------+--------------+------------+---------+---------+--------------------+

Related Pages

Corresponding API Methods