Menu Close

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, OpenShift Dedicated, and Red Hat OpenShift Service on AWS (ROSA) 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 subscribed 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, using 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 OpenShift Container Platform clusters have been registered at the same time, it may be necessary to use the cluster UUID to tell them apart.

Prerequisites

  • A Red Hat login
  • A Red Hat OpenShift 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. You can also filter your search by cluster type: OpenShift Container Platform (OCP), OpenShift Dedicated (OSD), or Red Hat OpenShift Service on AWS (ROSA).

Note

To rename your cluster to a human-readable name, 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

  • A Red Hat login
  • A Red Hat OpenShift cluster
  • You must have the Cluster Owner or Cluster Editor role on the cluster, or Organization Administrator privileges in your Red Hat account to change a cluster’s display name in OpenShift Cluster Manager.
Note

Organization Administrators can edit the display name of any cluster within their organization.

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. It is also used by OpenShift Cluster Manager to identify a specific Red Hat user when transferring cluster ownership. To transfer a cluster to another owner, you need to download the pull secret for the user that will take ownership of the cluster.

Prerequisites

  • A Red Hat login

Procedure

  1. Log in to OpenShift Cluster Manager as the Red Hat user you want to download the pull secret for.

    Important

    Each pull secret is unique to a specific user. If you are downloading the pull secret in order to transfer a cluster to another owner, you must log in to OpenShift Cluster Manager as the user that will take ownership of the cluster, and obtain that user’s pull secret.

  2. 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.
Important

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

You can now use this pull secret to create an OpenShift Container Platform cluster or for transferring cluster ownership.

Additional resources

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 and 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 five days of initiating the transfer process, or the process will need to be initiated again from OpenShift Cluster Manager. See Section 4.4, “Transferring cluster ownership”.

Important

On clusters using OpenShift Container Platform versions earlier than 4.7.4, cluster resources must adjust to the new pull secret. This can temporarily limit the usability of the cluster. This occurs because updating the pull secret causes the Machine Config Operator to drain the nodes, apply the change, and uncordon the nodes.

This does not affect clusters using OpenShift Container Platform versions 4.7.4 and later, where a pull secret change does not cause a node drain or reboot.

Prerequisites

  • An OpenShift Container Platform cluster
  • A Red Hat login with Cluster Owner or Organization Administrator privileges on the cluster in OpenShift Cluster Manager
  • A new or modified pull secret file to upload. You can download your pull secret from Downloads from the Tokens area.
  • 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.
  • 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

  • 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.

Verification steps

Go to Downloads in OpenShift Cluster Manager and find your pull secret in the Tokens category to verify the change:

  • Click Copy to copy your pull secret to the clipboard.
  • Click Download to download your pull secret.

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.

Note

To transfer ownership of an OpenShift Dedicated or Red Hat OpenShift Service on AWS (ROSA) cluster to another user, open a customer support case with Red Hat Support.

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 five 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.

Note

This procedure outlines transferring connected clusters. To transfer a disconnected cluster, see Section 4.4.2, “Transferring ownership of a disconnected cluster”.

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

  • A Red Hat login
  • An OpenShift Container Platform cluster
  • You must be the Cluster Owner on the cluster, or an Organization Administrator in the associated Red Hat account. See User access concepts in OpenShift Cluster Manager for more information.
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 five days of initiating the transfer process, or the process will need to be initiated again from OpenShift Cluster Manager.

Important

On clusters using OpenShift Container Platform versions earlier than 4.7.4, cluster resources must adjust to the new pull secret. This can temporarily limit the usability of the cluster. This occurs because updating the pull secret causes the Machine Config Operator to drain the nodes, apply the change, and uncordon the nodes.

This does not affect clusters using OpenShift Container Platform versions 4.7.4 and later, where a pull secret change does not cause a node drain or reboot.

Prerequisites

  • An OpenShift Container Platform cluster
  • A Red Hat login with Cluster Owner or Organization Administrator privileges on the cluster in OpenShift Cluster Manager
  • 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.

      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.

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

  • A Red Hat login
  • An OpenShift Container Platform cluster
  • You must be the Cluster Owner on the cluster, or an Organization Administrator in the associated Red Hat account. See User access concepts in OpenShift Cluster Manager for more information.

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 the 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. Monitoring clusters

4.5.1. Using Insights Advisor recommendations to manage cluster health

Red Hat Insights Advisor for OpenShift Container Platform allows you to assess and monitor the health of your OpenShift Container Platform clusters from the Red Hat Hybrid Cloud Console.

Insights Advisor highlights service availability, fault tolerance, performance, and security risks for your OpenShift Container Platform clusters based on Red Hat recommendations, so that you can avoid potential problems or solve problems quickly without unplanned downtime.

Recommendations include information about detected issues, including risk level, affected clusters, and steps for resolution where applicable.

To use Insights Advisor, your cluster must be registered to OpenShift Cluster Manager. To register a disconnected cluster, see Registering OpenShift Container Platform clusters to OpenShift Cluster Manager.

Additional resources

4.5.2. Troubleshooting a stale cluster

OpenShift Cluster Manager allows you to manage your clusters and monitor them for potential issues. The Status column in the Clusters list reports each cluster’s state so you can monitor your clusters at a glance.

An OpenShift Container Platform cluster can be shown as Stale in OpenShift Cluster Manager even if it is running and functioning normally. However, when a cluster status becomes Stale, you can no longer view internal information about the cluster in the OpenShift Cluster Manager Monitoring tab, including any alerts firing, cluster operators and resource usage.

In most cases, a cluster reports a Stale status because the telemeter-client cannot contact the Red Hat Telemetry endpoints. Telemetry enables the cluster to communicate with OpenShift Cluster Manager. If a cluster is reporting a Stale status, you can restore it to Ready and resume monitoring cluster health with the steps in this section.

Prerequisites

  • A Red Hat login
  • An OpenShift Container Platform cluster
  • You have access to the cluster as a user with the cluster-admin role.
  • You have installed the OpenShift CLI (oc).

Procedure

To diagnose a stale cluster and restore it to Ready status:

  1. Check that the OpenShift Container Platform cluster can connect to the Telemetry endpoints. If applicable, ensure that the cluster proxy configuration allows access to the Telemetry endpoints. The required Telemetry endpoints can be found in the Configuring your firewall for OpenShift Container Platform in the OpenShift Container Platform Installing documentation.
  2. Review the logs of the telemeter-client pod running in the openshift-monitoring namespace for any errors:

    $ oc get pods -n openshift-monitoring -l app.kubernetes.io/name=telemeter-client
  3. Restart the telemeter-client pod in the openshift-monitoring namespace and the insights-operator pod in the openshift-insights namespace:

    $ oc delete pod -n openshift-monitoring -l app.kubernetes.io/name=telemeter-client
    $ oc delete pod -n openshift-insights -l app=insights-operator
  4. Wait a few minutes after restarting the pods, then locate your cluster in the Clusters list in OpenShift Cluster Manager and check that the Status column shows Ready.

After completing these steps, if you can view the cluster in OpenShift Cluster Manager but the status is still Stale, occasionally this may be because the cluster is owned by an inactive user in your Red Hat organization. If this is the case, you can restore the cluster to Ready by transferring cluster ownership to an active user in your organization.

  1. To determine the cluster owner, check the cluster pull secret using the following command:

    $ oc get secret pull-secret -n openshift-config -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d | jq
    Note

    The jq JSON processor is needed to execute the above command and make the output more readable. You can also run the above command without using jq by removing | jq from the command, but the output will be more difficult to read.

  2. Check that the user account in the secret is still active in the Red Hat Customer Portal.
  3. If the user is no longer active, transfer your cluster to another owner using the steps in Transferring cluster ownership. When the ownership transfer is complete, the cluster will show in OpenShift Cluster Manager as Ready.

Verification steps

  • Locate your cluster in the Clusters list in OpenShift Cluster Manager and check that the Status column shows Ready. In a few minutes, you will also see information appear about the cluster in the OpenShift Cluster Manager Monitoring tab.

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 login

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.

4.8. Managing your add-on services

From OpenShift Cluster Manager, you can manage the add-ons installed on your OpenShift cloud services clusters. Add-ons are services that you can install to enhance the capabilities of your Red Hat OpenShift Dedicated and Red Hat OpenShift Service on AWS (ROSA) 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 ROSA documentation.