Using the ocm-cli to manage clusters in OpenShift Cluster Manager

Updated 10 Jun 2024

In addition to the OpenShift Cluster Manager user interface, you can use ocm-cli, the OpenShift Cluster Manager command-line interface (CLI), to manage your OpenShift clusters. The ocm-cli tool simplifies the use of the Content from api.openshift.com is not included.OpenShift Cluster Manager API. The ocm-cli command line tool is also useful for managing or configuring multiple clusters at once.

NOTE: The ocm-cli tool is Development Preview. A release that is provided as Development Preview is provided to a limited set of customers for their evaluation of an early version of the product and collection of feedback back to the product development teams. Development Preview releases are not supported in production environments.

Run $ ocm --help or see the Content from github.com is not included.ocm-cli GitHub page for further instructions about using the ocm-cli tool.
See the OpenShift Cluster Manager documentation to learn about using OpenShift Cluster Manager.

Prerequisites

To use ocm-cli to complete the procedures in this article, you need:

The ocm-cli command-line tool downloaded from This content is not included.OpenShift Cluster Manager. You can also find further instructions for your environment on the Content from github.com is not included.ocm-cli GitHub page.
Your offline access token found in This content is not included.OpenShift Cluster Manager.

Creating an OSD cluster using `ocm-cli`

You can create OSD managed clusters quickly using the ocm-cli command line tool.

Procedure

To create a new OSD cluster:

Log in to OpenShift Cluster Manager with your offline access token found in This content is not included.OpenShift Cluster Manager to use ocm-cli:

$ ocm login --token=eyJ...

This uses the provided token to request OpenID access and refresh tokens to sso.redhat.com. The tokens will be saved to the .ocm.json file in your home directory for future use.

Create an OSD cluster named by running the following command. Optionally, you can add flags to configure the cluster:

$ ocm create cluster [flags] <mycluster>

NOTE: Run $ ocm --help to see flags and options for creating an OSD cluster.

The ocm create cluster command returns the cluster ID and other information about the cluster.

Verification steps

OSD clusters are created asynchronously and take time to create before they are ready to use. After running ocm create cluster, you need to periodically check the cluster state attribute to confirm the cluster is ready.

To verify the cluster is ready to use, check the cluster state using the cluster ID:

$ ocm list cluster <id>

When the state is ready, the creation process is complete and you can use your cluster.

Deleting a cluster using `ocm-cli`

You can delete managed clusters quickly using the ocm-cli tool.

Procedure

To delete a managed cluster, use the ocm delete command with the cluster identifier.

Important: if a non-managed cluster is deleted, it will be marked as inactive in OCM.

Log in to OpenShift Cluster Manager with your offline access token found in This content is not included.OpenShift Cluster Manager to use ocm-cli:

$ ocm login --token=eyJ...

This uses the provided token to request OpenID access and refresh tokens to sso.redhat.com. The tokens will be saved to the .ocm.json file in your home directory for future use.

Run ocm delete using the cluster ID:

WARNING: This command deletes the cluster and destroys all of the virtual machines, disks, and any other resources it uses.

# ocm delete cluster <cluster_id>

Verification steps

Cluster deletion happens asynchronously and it takes time to completely delete the cluster.

You can check the cluster status with the ocm list cluster command using the cluster ID:

$ ocm list cluster <id>

When the cluster is deleted, this command will no longer return any information about the cluster.

Viewing cluster information using `ocm-cli`

You can use the ocm-cli to retrieve information about your clusters using the API.

Procedure

Log in to OpenShift Cluster Manager with your offline access token found in This content is not included.OpenShift Cluster Manager to use ocm-cli:

$ ocm login --token=eyJ...

This uses the provided token to request OpenID access and refresh tokens to sso.redhat.com. The tokens will be saved to the .ocm.json file in your home directory for future use.

Run the ocm get command to retrieve the information you want in a JSON file.
For example, to retrieve the list of all clusters with a name that starts with my, run:

$ ocm get /api/clusters_mgmt/v1/clusters --parameter search="name like 'my%'"

This command outputs a JSON file containing the description of those clusters, for example:

{
  "kind": "ClusterList",
  "page": 1,
  "size": 6,
  "total": 10
  "items": [
    {
      "kind": "Cluster",
      "id": "1GUAUWE3E1IS87Q99M0kxO1LpCG",
      "href": "/api/clusters_mgmt/v1/clusters/1GUAUWE3E1IS87Q99M0kxO1LpCG",
      "name": "mycluster",
      "api": {
        "url": "https://mycluster-api.example.com:6443"
      },
      "console": {
        "url": "https://console-openshift-console.apps.mycluster.example.com"
      },
      ...
    },
    ...
  ]
}

NOTE:

The --parameter option specifies query parameters. It is most useful combined with the get command, but can be used with any other command. For detailed information about the query parameters supported by each resource see the Content from api.openshift.com is not included.OpenShift API reference documentation.
The search query parameter is useful to retrieve objects from collections that support searching. The syntax of this parameter is similar to the syntax of the where clause of an SQL statement, but using the names of the attributes of the object instead of the names of the columns of a table.
- You can use the jq tool with the ocm get command to extract the information you need from the JSON cluster description. For example, to list the identifiers of your clusters, run:

$ ocm get /api/clusters_mgmt/v1/clusters | jq -r .items[].id

This command will return output similar to:

1FtmglZGw2byDzO8tb2cCtWxCNf
1FtRj13Fz2DIcm4zaDrcLvKAIyf
...

More examples

To retrieve your clusters with a name starting with my that are created in a DNS domain ending with example.com:

$ ocm get /api/clusters_mgmt/v1/clusters \
--parameter search="name like 'my%' and dns.base_domain like '%.example.com'"

To find the AWS regions in the US:

$ ocm get /api/clusters_mgmt/v1/cloud_providers/aws/regions \
--parameter search="name like 'US %'"

To find your clusters created after March 1, 2021:

$ ocm get /api/clusters_mgmt/v1/clusters \
--parameter search="creation_timestamp >= '2021-03-01'"

To find the clusters that are either ready or installing:

$ ocm get /api/clusters_mgmt/v1/clusters \
--parameter search="state in ('ready', 'installing')"

Viewing cluster object information using `ocm-cli`

You can use the OpenShift Cluster Manager command-line interface tool (ocm-cli) to retrieve information about your clusters using the API.

Procedure

Log in to OpenShift Cluster Manager with your offline access token found in This content is not included.OpenShift Cluster Manager to use ocm-cli:

$ ocm login --token=eyJ...

This uses the provided token to request OpenID access and refresh tokens to sso.redhat.com. The tokens will be saved to the .ocm.json file in your home directory for future use.
2) Use the get command to retrieve information from sub-resources associated to an object, including endpoints such as add-ons, groups, and ingresses. For example, if your cluster identifier is 123, you can see your identity providers (if set) using the following command:

$ ocm get /api/clusters_mgmt/v1/clusters/123/identity_providers

Alternatively, you can use this command to extract the kubeconfig to a file that can then be used directly with the oc command. Get the file by running:

$ ocm get /api/clusters_mgmt/v1/clusters/123/identity_providers \
| jq -r .kubeconfig > mycluster.config

Use the file to retrieve information about the pods on that cluster:

$ oc --config=mycluster.config get pods

NOTE: For a complete definition of the types of objects, and their attributes, see the Content from api.openshift.com is not included.OpenShift API reference documentation.

Downloading the pull secret using the API

You can automate downloading the pull secret needed for installing OpenShift Container Platform by using the OpenShift Cluster Manager API token to authenticate against your OpenShift Cluster Manager account.

This can be useful for automating OpenShift Container Platform cluster installation. However, Red Hat recommends downloading the pull secret every time you install a cluster in case the OpenShift image registries change.

The API for https://console.redhat.com/openshift/ is located at https://api.openshift.com/.
The pull secret endpoint is POST /api/accounts_mgmt/v1/access_token.

Prerequisites

In addition to having the ocm-cli command-line tool installed and your offline access token, you must be logged in as a user with cluster owner privileges to the cluster.

Procedure

Log in to OpenShift Cluster Manager with your offline access token found in This content is not included.OpenShift Cluster Manager to use ocm-cli:

$ ocm login --token=eyJ...

This uses the provided OpenShift Cluster Manager token (also known as a bearer token) to request OpenID access and refresh tokens to sso.redhat.com. The tokens will be saved to the .ocm.json file in your home directory for future use.

NOTE: Run ocm login --help for more information and options.

Export the OpenShift Cluster Manager (bearer) token:

$ export BEARER=$(curl \
--silent \                    
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "client_id=cloud-services" \
--data-urlencode "refresh_token=${OFFLINE_ACCESS_TOKEN}" \
https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token | \
jq -r .access_token)

Run the ocm post command with the following details:

$ echo '{}' | ocm post /api/accounts_mgmt/v1/access_token --header --header "Content-Type:application/json" --header "Authorization: Bearer $BEARER" | jq
{
  "auths": {
    "cloud.openshift.com": {
      "auth": "<snip>",
      "email": "<user's email>"
    },
    "quay.io": {
      "auth": "<snip>",
      "email": "<user's email>"
    },
    "registry.connect.redhat.com": {
      "auth": "<snip>",
      "email": "<user's email>"
    },
    "registry.redhat.io": {
      "auth": "<snip>",
      "email": "<user's email>"
    }
  }
}

The tokens are now saved to the .ocm.json file in your home directory.

See Using image pull secrets in the OpenShift Container Platform documentation.

Additional resources

Run $ ocm --help or see the Content from github.com is not included.ocm-cli GitHub page for further instructions about using the ocm-cli tool.
See Content from stedolan.github.io is not included../jq for information about using and downloading the jq tool.
See the Content from api.openshift.com is not included.OpenShift API reference documentation.
See This content is not included.Downloading the OpenShift Cluster Manager API token for instructions on using tokens.

Give us feedback!

ocm-cli is in development and Red Hat would love your comments and suggestions. You can provide feedback by:

Opening an issue in the Content from github.com is not included.ocm-cli GitHub project
Sending a message to ocm-feedback@redhat.com

SBR

Product(s)

Category

Learn more

Components

Tags

Article Type

General

Using the ocm-cli to manage clusters in OpenShift Cluster Manager

Creating an OSD cluster using ocm-cli

Deleting a cluster using ocm-cli

Viewing cluster information using ocm-cli

Viewing cluster object information using ocm-cli

Downloading the pull secret using the API

Additional resources

Give us feedback!

Creating an OSD cluster using `ocm-cli`

Deleting a cluster using `ocm-cli`

Viewing cluster information using `ocm-cli`

Viewing cluster object information using `ocm-cli`