Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Open Cluster Management plugin for Backstage

Red Hat Developer Hub 0.1

The Open Cluster Management plugin for Backstage

Red Hat Customer Content Services

Abstract

The Open Cluster Management (OCM) plugin integrates your Backstage instance with the `MultiClusterHub` and `MultiCluster` engines of OCM.

The Open Cluster Management (OCM) plugin integrates your Backstage instance with the MultiClusterHub and MultiCluster engines of OCM.

1.1. Capabilities
Copy link

The OCM plugin has the following capabilities:

  • All clusters represented as ManagedCluster in MultiClusterHub or MCE are discovered and imported into the Backstage catalog, such as:

    • Entity is defined as kind: Resource with spec.type set to kubernetes-cluster.
    • Links to the OpenShift Container Platform (OCP) console, OCM console, and OpenShift Cluster Manager are provided in metadata.links.

  • Shows real-time data from OCM on the Resource entity page, including:

    • Cluster current status (up or down)
    • Cluster nodes status (up or down)
    • Cluster details (console link, OCP, and Kubernetes version)
    • Details about available compute resources on the cluster

1.2. For administrators
Copy link

1.2.1. Installation
Copy link

The OCM plugin is composed of two packages, including:

Note

If you are interested in Resource discovery and do not want any of the front-end components, then you can install and configure the @redhat/backstage-plugin-ocm-backend package only.

1.2.1.1. Prerequisites
Copy link
  • OCM is deployed and configured on a Kubernetes cluster.
  • Kubernetes plugin for Backstage is installed.

  • A ClusterRole is granted to ServiceAccount accessing the hub cluster as follows: 

      kind: ClusterRole
  apiVersion: rbac.authorization.k8s.io/v1
  metadata:
    name: backstage-ocm-plugin
  rules:
    - apiGroups:
        - cluster.open-cluster-management.io
      resources:
        - managedclusters
      verbs:
        - get
        - watch
        - list
    - apiGroups:
        - internal.open-cluster-management.io
      resources:
        - managedclusterinfos
      verbs:
        - get
        - watch
        - list
    Copy to Clipboard Toggle word wrap
1.2.1.2. Setting up the OCM backend package
Copy link

  1. Install the OCM backend plugin using the following command: 

    yarn workspace backend add @redhat/backstage-plugin-ocm-backend
    Copy to Clipboard Toggle word wrap

  2. Configure the OCM backend plugin using one of the following configurations:

    • The OCM configuration provides the information about your hub. To use the OCM configuration, add the following code to your app-config.yaml file: 

      `yaml title="app-config.yaml"
     catalog:
       providers:
         ocm:
           env: # Key is reflected as provider ID. Defines and claims plugin instance ownership of entities
             name: # Name that the hub cluster will assume in Backstage Catalog (in OCM this is always local-cluster which can be confusing)
             url: # Url of the hub cluster API endpoint
             serviceAccountToken: # Token used for querying data from the hub
             skipTLSVerify: # Skip TLS certificate verification, defaults to false
             caData: # Base64-encoded CA bundle in PEM format
      Copy to Clipboard Toggle word wrap

    • If the Backstage Kubernetes plugin is installed and configured to connect to the hub cluster, then you can bind the both hub and Kubernetes configuration by providing the name of the hub in the app-config.yaml as follows: 

      ```yaml title="app-config.yaml"
     kubernetes:
       serviceLocatorMethod:
         type: 'multiTenant'
       clusterLocatorMethods:
         - type: 'config'
           clusters:
             # highlight-next-line
             - name: <cluster-name>
             # ...

     catalog:
       providers:
         ocm:
           env: # Key is reflected as provider ID. Defines and claims plugin instance ownership of entities
             # highlight-next-line
             kubernetesPluginRef: <cluster-name> # Match the cluster name in kubernetes plugin config
      Copy to Clipboard Toggle word wrap

      Ensure that the Backstage uses a ServiceAccount token and the required permissions are granted as mentioned previously.

      This is useful when you already use a Kubernetes plugin in your Backstage instance. Also, the hub cluster must be connected using the ServiceAccount.

      For more information about the configuration, see Backstage Kubernetes plugin documentation.

  3. Create a new plugin instance in packages/backend/src/plugins/ocm.ts file as follows: 

    ```ts title="packages/backend/src/plugins/ocm.ts"
   import { Router } from 'express';

   import { createRouter } from '@redhat/backstage-plugin-ocm-backend';

   import { PluginEnvironment } from '../types';

   export default async function createPlugin(
     env: PluginEnvironment,
   ): Promise<Router> {
     return await createRouter({
       logger: env.logger,
       config: env.config,
     });
   }
    Copy to Clipboard Toggle word wrap

  4. Import and plug the new instance into packages/backend/src/index.ts file: 

    ```ts title="packages/backend/src/index.ts"
   /* highlight-add-next-line */
   import ocm from './plugins/ocm';

   async function main() {
     // ...
     const createEnv = makeCreateEnv(config);
     // ...
     /* highlight-add-next-line */
     const ocmEnv = useHotMemoize(module, () => createEnv('ocm'));
     // ...
     const apiRouter = Router();
     // ...
     /* highlight-add-next-line */
     apiRouter.use('/ocm', await ocm(ocmEnv));
     // ...
   }
```
    Copy to Clipboard Toggle word wrap

  5. Import the cluster Resource entity provider into the catalog plugin in the packages/backend/src/plugins/catalog.ts file. The scheduler also needs to be configured. Two configurations are possible here:

    1. Configure the scheduler inside the app-config.yaml: 

      ```yaml title="app-config.yaml"
      catalog:
        providers:
          ocm:
            env:
              # ...
              # highlight-add-start
              schedule: # optional; same options as in TaskScheduleDefinition
                # supports cron, ISO duration, "human duration" as used in code
                frequency: { minutes: 1 }
                # supports ISO duration, "human duration" as used in code
                timeout: { minutes: 1 }
              # highlight-add-end
+
      Copy to Clipboard Toggle word wrap

      and then use the configured scheduler 

      ```ts title="packages/backend/src/index.ts"
      /* highlight-add-next-line */
      import { ManagedClusterProvider } from '@redhat/backstage-plugin-ocm-backend';

      export default async function createPlugin(
        env: PluginEnvironment,
      ): Promise<Router> {
        const builder = await CatalogBuilder.create(env);
        // ...
        /* highlight-add-start */
        const ocm = ManagedClusterProvider.fromConfig(env.config, {
          logger: env.logger,
          scheduler: env.scheduler,
        });
        builder.addEntityProvider(ocm);
        /* highlight-add-start */
        // ...
      }
      Copy to Clipboard Toggle word wrap

    2. Add a schedule directly inside the packages/backend/src/plugins/catalog.ts file 

      ```ts title="packages/backend/src/index.ts"
      /* highlight-add-next-line */
      import { ManagedClusterProvider } from '@redhat/backstage-plugin-ocm-backend';

      export default async function createPlugin(
        env: PluginEnvironment,
      ): Promise<Router> {
        const builder = await CatalogBuilder.create(env);
        // ...
        /* highlight-add-start */
        const ocm = ManagedClusterProvider.fromConfig(env.config, {
          logger: env.logger,
          schedule: env.scheduler.createScheduledTaskRunner({
            frequency: { minutes: 1 },
            timeout: { minutes: 1 },
          }),
        });
        builder.addEntityProvider(ocm);
        /* highlight-add-start */
        // ...
      }
      Copy to Clipboard Toggle word wrap

  6. Optional: Configure the default owner for the cluster entities in the catalog for a specific environment. For example, use the following code to set foo as the owner for clusters from env in the app-config.yaml catalog section: 

    `yaml title="app-config.yaml"
   catalog:
     providers:
       ocm:
         env:
           # highlight-next-line
           owner: user:foo
    Copy to Clipboard Toggle word wrap

    For more information about the default owner configuration, see upstream string references documentation.

1.2.1.3. Setting up the OCM frontend package
Copy link

  1. Install the OCM frontend plugin using the following command: 

    yarn workspace app add @redhat/backstage-plugin-ocm
    Copy to Clipboard Toggle word wrap

  2. Select the components that you want to use, such as:

    • OcmPage: This is a standalone page or dashboard displaying all clusters as tiles. You can add OcmPage to packages/app/src/App.tsx file as follows: 

      ```tsx title="packages/app/src/App.tsx"
     /* highlight-add-next-line */
     import { OcmPage } from '@redhat/backstage-plugin-ocm';

     const routes = (
       <FlatRoutes>
         {/* ... */}
         {/* highlight-add-next-line */}
         <Route path="/ocm" element={<OcmPage logo={<Logo />} />} />
       </FlatRoutes>
     );
      Copy to Clipboard Toggle word wrap

      You can also update navigation in packages/app/src/components/Root/Root.tsx as follows: 

      ```tsx title="packages/app/src/components/Root/Root.tsx"
     /* highlight-add-next-line */
     import StorageIcon from '@material-ui/icons/Storage';

     export const Root = ({ children }: PropsWithChildren<{}>) => (
       <SidebarPage>
         <Sidebar>
           <SidebarGroup label="Menu" icon={<MenuIcon />}>
             {/* ... */}
             {/* highlight-add-next-line */}
             <SidebarItem icon={StorageIcon} to="ocm" text="Clusters" />
           </SidebarGroup>
           {/* ... */}
         </Sidebar>
         {children}
       </SidebarPage>
     );
      Copy to Clipboard Toggle word wrap

    • ClusterContextProvider: This component is a React context provided for OCM data, which is related to the current entity. The ClusterContextProvider component is used to display any data on the React components mentioned in packages/app/src/components/catalog/EntityPage.tsx: 

      ```tsx title="packages/app/src/components/catalog/EntityPage.tsx"
     /* highlight-add-start */
     import {
       ClusterAvailableResourceCard,
       ClusterContextProvider,
       ClusterInfoCard,
     } from '@redhat/backstage-plugin-ocm';

     /* highlight-add-end */

     const isType = (types: string | string[]) => (entity: Entity) => {
       if (!entity?.spec?.type) {
         return false;
       }
       return typeof types === 'string'
         ? entity?.spec?.type === types
         : types.includes(entity.spec.type as string);
     };

     export const resourcePage = (
       <EntityLayout>
         {/* ... */}
         {/* highlight-add-start */}
         <EntityLayout.Route path="/status" title="status">
           <EntitySwitch>
             <EntitySwitch.Case if={isType('kubernetes-cluster')}>
               <ClusterContextProvider>
                 <Grid container direction="column" xs={6}>
                   <Grid item>
                     <ClusterInfoCard />
                   </Grid>
                   <Grid item>
                     <ClusterAvailableResourceCard />
                   </Grid>
                 </Grid>
               </ClusterContextProvider>
             </EntitySwitch.Case>
           </EntitySwitch>
         </EntityLayout.Route>
         {/* highlight-add-end */}
       </EntityLayout>
     );

     export const entityPage = (
       <EntitySwitch>
         {/* ... */}
         {/* highlight-add-next-line */}
         <EntitySwitch.Case if={isKind('resource')} children={resourcePage} />
       </EntitySwitch>
     );
      Copy to Clipboard Toggle word wrap

      In the previous codeblock, you can place the context provider into your Resource entity renderer, which is usually available in packages/app/src/components/catalog/EntityPage.tsx or in an imported component.

      • <ClusterInfoCard />: This is an entity component displaying details of a cluster in a table:
      • <ClusterAvailableResourceCard />: This is an entity component displaying the available resources on a cluster. For example, see .status.capacity of the ManagedCluster resource.

1.3. For users
Copy link

1.3.1. Using the OCM plugin in Backstage
Copy link

The OCM plugin integrates your Backstage instance with multi-cluster engines and displays real-time data from OCM.

1.3.1.1. Prerequisites
Copy link
1.3.1.2. Procedure
Copy link
  1. Open your Backstage application.

  2. Click the Clusters tab from the left-side panel to view the Managed Clusters page.

    The Managed Clusters page displays the list of clusters with additional information, such as status, infrastructure provider, associated OpenShift version, and available nodes.

    ocm-plugin-ui
    View larger image
    ocm-plugin-ui

    You can also upgrade the OpenShift version for a cluster using the Upgrade available option in the VERSION column.

  3. Select a cluster from the Managed Clusters to view the related cluster information.

    You are redirected to the cluster-specific page, which consists of:

    • Cluster Information, such as name, status, accessed Kubernetes version, associated OpenShift ID and version, and accessed platform.
    • Available cluster capacity, including CPU cores, memory size, and number of pods.
    • Related Links, which enable you to access different consoles directly, such as OpenShift Console, OCM Console, and OpenShift Cluster Manager Console.
    • Relations card, which displays the visual representation of the cluster and associated dependencies.
    ocm-plugin-ui
    View larger image
    ocm-plugin-ui

The Open Cluster Management (OCM) plugin integrates your Backstage instance with OCM.

For more information about OCM plugin, see the Open Cluster Management plugin documentation on GitHub.

The Open Cluster Management (OCM) plugin integrates your Backstage instance with OCM.

For more information about OCM plugin, see the Open Cluster Management plugin documentation on GitHub.

Legal Notice
Copy link

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat