Chapter 4. Managing your clusters

In Red Hat OpenShift Cluster Manager, you can view your Red Hat OpenShift clusters and perform various cluster management tasks.

4.1. Viewing cluster information

The OpenShift Cluster Manager Clusters list shows details for all OpenShift Container Platform and OpenShift Dedicated clusters in your organization. From here, you can select a cluster to review its settings, check usage, solve issues, and perform other management tasks.

Procedure

  • Click a cluster from the list to view more details about it, including:

    • The Overview page shows resource usage and basic facts about the cluster
    • The cluster history shows what has happened on this cluster: for example, when it was registered and entitled to a Red Hat subscription
    • The Monitoring tab shows the health of your OpenShift Container Platform cluster and uses the Telemetry service to report the cluster’s status in OpenShift Cluster Manager. The Monitoring area shows critical alerts, for example if a cluster operator is failing. This area also shows resource usage.

Additional resources

4.1.1. Determining your cluster ID

Every OpenShift cluster is assigned an ID (in the form of a UUID) when created, but each cluster also has an internal cluster identifier used by OpenShift Cluster Manager. The internal cluster identifier can be changed to a human-readable name OpenShift Cluster Manager if desired.

You can find this information in OpenShift Cluster Manager, via the command line, or in the OpenShift web console.

Additionally, when OpenShift Container Platform clusters register to OpenShift Cluster Manager, the only identifying information may be the cluster UUID. If multiple OCP clusters have been registered at the same time, it may be necessary to use the cluster UUID to tell them apart.

Prerequisites

  • An OpenShift Container Platform 4.x cluster

Procedure

There are several ways to view your cluster ID:

  • Your clusters are listed by ID in OpenShift Cluster Manager in the Clusters area.

    From here, you can also search for a cluster by name or ID, and filter by cluster type, OpenShift Container Platform (OCP), OpenShift Dedicated (OSD), or Red Hat OpenShift Service on AWS (ROSA).

To rename your cluster to a human-readable name, see See Section 4.2, “Renaming your cluster”.

  • You can also get your OpenShift cluster ID by running the following command locally or on the cluster itself (after logging into the cluster using oc login):
$ oc get clusterversion <version> -o jsonpath='{.spec.clusterID}{"\n"}'
  • You can also find your OpenShift cluster ID in the OpenShift Container Platform web console if you are logged in as an administrator:

    • In the details pane on the Home/Dashboards page
    • On the Administration/Cluster Settings page

4.2. Renaming your cluster

You can give your connected cluster a human-readable name instead of a cluster UUID to make it easier to reference when contacting Red Hat Support or opening a support case, or when reviewing the list of clusters in OpenShift Cluster Manager.

When created, every OpenShift cluster is assigned a 36-character UUID string as a name to differentiate it from other clusters. However, as the UUID can be difficult to search or reference, Red Hat recommends providing a custom name for the cluster to simplify locating resources and managing your OpenShift environment.

Prerequisites

  • An OpenShift Container Platform 4.x or OpenShift Dedicated cluster
  • You must have a Red Hat account with Organization Administrator access or be the creator or owner of the cluster you want to edit.
Note

Organization administrators can edit the display name of all clusters within their organization, and cluster creators or owners of a cluster can change the name of any clusters they created.

Procedure

  1. Go to the Clusters list in OpenShift Cluster Manager.
  2. Click more options (more options) next to the cluster you want to rename.
  3. Click Edit display name and enter a name for the cluster.
  4. Click Edit to save the new name.
Note

You can also rename a cluster from its details page from the Actions menu > Edit display name.

The new cluster name shows in the clusters list on OpenShift Cluster Manager.

Additional resources

4.3. Downloading and updating pull secrets

4.3.1. Downloading the pull secret from OpenShift Cluster Manager

An image pull secret provides authentication for the cluster to access services and registries which serve the container images for OpenShift components. Every individual user gets a single pull secret generated. The pull secret is used when installing an OpenShift Container Platform cluster.

Prerequisites

  • A Red Hat account

Procedure

  1. Go to Downloads in OpenShift Cluster Manager and find your pull secret in the Tokens category.

    • Click Copy to copy your pull secret to the clipboard.
    • Click Download to download your pull secret as a .txt file.
Important

Do not share your pull secret. The pull secret should be treated like a password.

You can now use your pull secret to create an OpenShift Container Platform cluster or transfer cluster ownership.

Additional resources

  • See Using image pull secrets in the OpenShift Container Platform documentation for more details about using pull secrets.

4.3.2. Updating the global pull secret

An image pull secret provides authentication for the cluster to access services and registries which serve the container images for OpenShift components. Every individual user gets a single pull secret generated. The pull secret is used when installing an OpenShift Container Platform cluster.

To transfer a connected cluster to a new owner, you must update the pull secret on a cluster to the new owner’s pull secret after initiating a cluster transfer in OpenShift Cluster Manager. The pull secret must be updated within 5 days of initiating the transfer process, or the process will need to be initiated again from OpenShift Cluster Manager.

Warning

When changing a cluster’s pull secret, the cluster resources must adjust to the new pull secret. This can temporarily limit the usability of the cluster.

Updating the pull secret causes the Machine Config Operator to drain the nodes, apply the change, and uncordon the nodes.

Note

As of OpenShift Container Platform 4.7, changes to the global pull secret no longer trigger a reboot.

Prerequisites

  • An OpenShift Container Platform cluster
  • A new or modified pull secret file to upload. You can download your pull secret as a .txt file from Downloads from the Tokens area.
  • Access to the cluster as a user with Cluster Owner or Organization Administrator privileges.
  • If you are transferring the cluster to a new owner, you must initiate the transfer in OpenShift Cluster Manager before changing the global pull secret to be able to receive Telemetry metrics to monitor the cluster.

Procedure

  1. Run the following command using the pull secret you downloaded from OpenShift Cluster Manager to change the cluster’s pull secret:

    # oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson=pull-secret.txt

    If a secret is not already created, run the following command to create the secret:

# oc create secret generic pull-secret -n openshift-config --type=kubernetes.io/dockerconfigjson --from-file=.dockerconfigjson=/path/to/downloaded/pull-secret

This begins updates to all nodes in the cluster, which can take some time depending on the size of your cluster. During this time, nodes are drained and pods are rescheduled on the remaining nodes.

Verification steps

Log into OpenShift Cluster Manager as new owner of the cluster. You can verify the transfer was successful by checking these details in the cluster Overview:

  • In Details, the Owner has been updated.
  • In Cluster history, details of the transfer appear.

If the cluster was transferred to a different organization, you can log into that organization to verify the update. The cluster now appears in the target Red Hat account’s clusters list, and has been removed from the previous Red Hat account’s clusters list.

Additional resources

4.4. Transferring cluster ownership

You can transfer ownership of an OpenShift Container Platform cluster to another user in your organization or a different organization using OpenShift Cluster Manager.

For example, if you created an OpenShift Container Platform cluster using one Red Hat account but want to move the cluster to a different Red Hat account to register it to the associated subscription, you need to transfer cluster ownership to that user. You can transfer ownership of connected or disconnected clusters.

Connected clusters

Transferring ownership of a connected cluster requires two steps: initiate the transfer in OpenShift Cluster Manager, then change the cluster’s pull secret from the command line. You must change the cluster pull secret within 5 days of initiating the transfer, or you need to restart the transfer procedure.

The transfer is complete when OpenShift Cluster Manager begins receiving Telemetry data from the cluster with the new pull secret. See Transferring ownership of a connected cluster for instructions.

Important

The cluster transfer will not complete successfully if only the pull secret is updated to the new cluster owner. As a result, the cluster may stop reporting Telemetry metrics for monitoring. You must initiate the ownership transfer in OpenShift Cluster Manager in addition to changing the cluster pull secret to complete the transfer.

Disconnected clusters

To transfer ownership of a disconnected cluster, you only need to initiate the transfer in OpenShift Cluster Manager; no pull secret update is required. The transfer is complete when the new cluster owner registers the cluster to OpenShift Cluster Manager. See Transferring ownership of a disconnected cluster for instructions.

4.4.1. Transferring ownership of a connected cluster

You can transfer ownership of a connected OpenShift Container Platform cluster to another user in your organization or a different organization using OpenShift Cluster Manager.

To transfer a connected cluster to another owner, you must:

  1. Initiate the transfer in OpenShift Cluster Manager.
  2. Change the cluster pull secret to the new owner’s pull secret from the command line within five days of initiating the transfer.

Prerequisites

Note

To create a new user to take over cluster ownership, see How to Create and Manage Users on the Red Hat Customer Portal.

Procedure

  1. Log into OpenShift Cluster Manager as the current cluster owner.
  2. Initiate the transfer:

    1. Select the cluster that you want to transfer from the Clusters list.
    2. Click Actions > Transfer cluster ownership at the top of the cluster’s details page.
    3. Click Initiate transfer to confirm this action.
Important

You must change the cluster’s pull secret within five days of initiating the transfer and register the cluster with the new Red Hat account or the transfer will be cancelled.

You can cancel the ownership transfer anytime before the pull secret has been changed by clicking Actions > Cancel ownership transfer.

You have now initiated the ownership transfer. The next step is to change the cluster’s pull secret to the pull secret of the new cluster owner.

4.4.1.1. Updating the global pull secret when transferring cluster ownership

To transfer a connected cluster to a new owner, you must update the pull secret on a cluster to the new owner’s pull secret after initiating a cluster transfer in OpenShift Cluster Manager. The pull secret must be updated within 5 days of initiating the transfer process, or the process will need to be initiated again from OpenShift Cluster Manager.

Warning

When changing a cluster’s pull secret, the cluster resources must adjust to the new pull secret. This can temporarily limit the usability of the cluster.

Updating the pull secret causes the Machine Config Operator to drain the nodes, apply the change, and uncordon the nodes.

Note

As of OpenShift Container Platform 4.7, changes to the global pull secret no longer trigger a reboot.

Prerequisites

  • An OpenShift Container Platform cluster
  • You have access to the cluster as a user with the cluster-admin role. See Authentication and authorization in the OpenShift Container Platform documentation for more information about cluster roles.
  • The cluster ownership transfer was initiated in OpenShift Cluster Manager within the last five days.

Procedure

  1. As the user who is taking ownership of the cluster (the target account):

    1. Log into OpenShift Cluster Manager.
    2. Download or copy your pull secret from the Downloads page under Tokens. (This is not required for disconnected clusters.)

      Important

      Do not share your pull secret. The pull secret should be treated like a password.

  2. Run the following command using the pull secret you downloaded from OpenShift Cluster Manager to change the cluster’s pull secret:

    # oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson=pull-secret.txt

    If a secret is not already created, run the following command to create the secret:

# oc create secret generic pull-secret -n openshift-config --type=kubernetes.io/dockerconfigjson --from-file=.dockerconfigjson=/path/to/downloaded/pull-secret

This begins updates to all nodes in the cluster, which can take some time depending on the size of your cluster. During this time, nodes are drained and pods are rescheduled on the remaining nodes.

Verification steps

Log into OpenShift Cluster Manager as new owner of the cluster. You can verify the transfer was successful by checking these details in the cluster Overview:

  • In Details, the Owner has been updated.
  • In Cluster history, details of the transfer appear.

If the cluster was transferred to a different organization, you can log into that organization to verify the update. The cluster now appears in the target Red Hat account’s clusters list, and has been removed from the previous Red Hat account’s clusters list.

The transfer is complete when OpenShift Cluster Manager receives Telemetry data from the cluster with the new pull secret.

4.4.2. Transferring ownership of a disconnected cluster

You can transfer ownership of a disconnected OpenShift Container Platform cluster to another user in your organization or a different organization using OpenShift Cluster Manager.

To transfer ownership of a disconnected cluster, you only need to initiate the transfer in OpenShift Cluster Manager; no pull secret update is required.

Prerequisites

Procedure

  1. Log into OpenShift Cluster Manager as the current cluster owner.
  2. Initiate the transfer:

    1. Select the cluster that you want to transfer from the Clusters list.
    2. Click Actions > Transfer cluster ownership at the top of the cluster’s details page.
    3. Click Initiate transfer to confirm this action.

      Important

      You must change the cluster’s pull secret within five days of initiating the transfer and register the cluster with the new Red Hat account or the transfer will be cancelled.

      You can cancel the ownership transfer anytime before the pull secret has been changed by clicking Actions > Cancel ownership transfer.

  3. Provide the cluster UUID to the user that you are transferring the cluster to.

    Note

    You can find the cluster UUID on the cluster details page in OpenShift Cluster Manager (Cluster ID), or on thethe About page of the cluster web console in OpenShift Container Platform.

  4. As the new cluster owner, log into OpenShift Cluster Manager.
  5. Register the disconnected cluster with the cluster UUID using the steps in Registering disconnected clusters.

When the cluster registers to OpenShift Cluster Manager successfully, the cluster ownership transfer is complete.

Verification steps

You can verify the transfer was successful by checking:

  • The cluster Overview:

    • In Details, the Owner has been updated.
    • In Cluster history, details of the transfer appear.
  • If the cluster was transferred to a different organization, the cluster now appears in the new Red Hat account’s clusters list, and has been removed from the previous Red Hat account’s clusters list.

4.5. Managing your add-on services

From OpenShift Cluster Manager, you can manage the add-ons installed on your clusters. Add-ons are services that you can install to enhance the capability of your managed OpenShift clusters.

To access your add-ons and find information about them, navigate to your cluster’s Add-ons tab in OpenShift Cluster Manager, and select the add-on.

Additional resources

  • To add a service to your OpenShift Dedicated cluster or manage your existing add-ons, see Add-on Services in the OpenShift Dedicated documentation.
  • To add a service to your Red Hat OpenShift Service on AWS (ROSA) cluster or manage your existing add-ons, see Add-on Services in the Red Hat OpenShift Service on AWS documentation.

4.6. Downloading command line (CLI) tools

The Downloads page in OpenShift Cluster Manager provides a single place to download CLI tools and find your authentication tokens to manage OpenShift.

The Downloads page includes command line tools such as:

  • Command-line interface (CLI) tools to manage and work with OpenShift from your terminal
  • Developer tools to simplify the use of Kubernetes
  • OpenShift installers to create OpenShift Container Platform and CodeReady Containers clusters.
  • Red Hat Enterprise Linux CoreOS (RHCOS) management tools for customizing your RHCOS nodes.
  • Tokens for authentication, including your pull secret and OpenShift Cluster Manager API token.

Procedure

  1. Go to Downloads and find the resource you want to download.
  2. (Optional) Expand the tool or token description to learn more about the download and see links to related documentation.
  3. Specify the operating system and architecture you are using in the OS type and Architecture type dropdowns, and click Download.

Additional resources

4.7. Downloading the OpenShift Cluster Manager API token

Use your OpenShift Cluster Manager API token to authenticate against your OpenShift Cluster Manager account.

The API token is required to connect to OpenShift Cluster Manager to use the rosa CLI and ocm-cli command line tools. You can use the same token with both services.

For security, tokens are hidden from display in OpenShift Cluster Manager by default. You can access your API token on the OpenShift Cluster Manager Downloads page, then view or copy it to use in the command line.

Note

The ocm-cli tool is currently 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.

Prerequisites

  • A Red Hat account

Procedure

  1. Go to Downloads and find the OpenShift Cluster Manager API Token row under Tokens.
  2. Click View API token to go to the OpenShift Cluster Manager API Token page.
  3. Click Load token to display your token. By default, the token is hidden from display.
  4. Click copy clipboard (Copy to clipboard) to copy your token to use in a terminal.

You can also revoke access to existing tokens from this page.