How to use the Backstage HCP Consul plugin

[Hashicorp]

To use Backstage, the popular open platform for building developer portals, with HashiCorp Cloud Platform (HCP) Consul Central requires users to be aware of HCP and related components. This blog post guides you through the steps to install the HCP Consul frontend and backend plugin for Backstage: plugin-hcp-consul and plugin-hcp-consul-backend.

Background

HashiCorp Consul is an identity-based service networking solution offering service discovery, secure communication, and network automation across multiple cloud and runtime environments. HashiCorp Cloud Platform (HCP) Consul Central is a global management platform providing visibility of services and connectivity across datacenters enabling troubleshooting and configuration workflows.

Prerequisites

Before you begin, you will need:

• Backstage set up and running (version 1.18 or later)
• Node.js (version 14 or later)
• Yarn
• A Dev Tier account on HCP. The plugin works only for the Consul clusters connected to HCP Consul.
• An HCP service principal key. Follow this tutorial to generate the client ID and client secret.

Install the backend plugin

The backend plugin, plugin-hcp-consul-backend, facilitates communication between Backstage and HCP Consul.

From your Backstage root directory, add the backend plugin Yarn package:

yarn add --cwd packages/backend @hashicorp/plugin-hcp-consul-backend

Then, create an hcp-consul-backend.ts file inside packages/backend/src/plugins/:

import { createRouter } from '@hashicorp/plugin-hcp-consul-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
 
export default async function createPlugin(
  env: PluginEnvironment,
): Promise {
  return await createRouter(env);
}

Next, modify your packages/backend/src/index.ts to import and configure the HCP Consul backend plugin:

...
 
 import { Config } from '@backstage/config';
 import app from './plugins/app';
+ import consul from './plugins/hcp-consul-backend';
 ...
 
 async function main() {
   ...
 
   const authEnv = useHotMemoize(module, () => createEnv('auth'));
+  const consulBackendEnv = useHotMemoize(module, () => createEnv('consul'));
   ...
 
   const apiRouter = Router();
   apiRouter.use('/catalog', await catalog(catalogEnv));
+  apiRouter.use('/hcp-consul-backend', await consul(consulBackendEnv));

For this backend plugin to work, you must configure Consul in your app-config.yaml file. Here is an example Consul configuration:

consul:
  clientID: abcdefabcdefabcdefabcdefabcdef
  clientSecret: xyxy111xyxy111xyxy111xyxy111xyxy111xyxy111xyxy111
  organizationID: ff14c2a2-a937-4240-bf11-9d23ca01761d
 projectID: f3945084-71ac-495c-84b3-371100d27279

Finally, link the plugin to Backstage to start the HCP Consul backend plugin:

yarn backstage-cli --no-yarn --cwd ./plugins/hcp-consul-backend start

You also need to verify backend connectivity. Ensure that the backend is successfully running and accessible by hitting an internal endpoint using curl, as shown here. Check Authenticate to HCP for getting the token:

curl -H "Authorization: Bearer " localhost:7007/api/hcp-consul-backend/2023-10-10/consul/project//clusters

Install the frontend plugin

The frontend plugin, plugin-hcp-consul, provides a user interface within Backstage for managing Consul configurations.

From your Backstage root directory, add the frontend plugin Yarn package:

yarn add --cwd packages/app @hashicorp/plugin-hcp-consul

Next, modify your packages/app/src/App.tsx to import and configure the HCP Consul frontend plugin. This example adds a cluster overview page to the /hcp-consul path:

import { HcpConsulPluginPage } from '@hashicorp/plugin-hcp-consul';

const routes = (
  
    ...
    } />
);

By default, the frontend plugin uses the Consul configuration you defined in app-config.yaml. This includes the clientID, clientSecret, organizationID, and projectID. You can override the projectID on a component level using this snippet:

Optional: Add EntityServiceInstancesTable to display the HCP Consul service instances in the Backstage component. The following example code adds a /hcp-consul-instances tab to the EntityPage that displays all service instances of the service:

// In packages/app/src/components/catalog/EntityPage.tsx

import { EntityServiceInstancesTable, isHcpConsulServiceAvailable } from '@hashicorp/plugin-hcp-consul';

const serviceEntityPage = (
    ...
    
      
    
)

You need to provide annotations to the component:

1.  consul.io/cluster_resource_name annotation's value is the cluster resource name in HCP. It is required.
2.  consul.io/name annotation's value is the service name. It is required.
3.  consul.io/namespace is the namespace of the service. If omitted, it defaults to default.
4.  consul.io/partition is the partition of the service. If omitted, it defaults to default.

Here is an example configuration (refer to the Backstage documentation for more details):

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  annotations:
    consul.io/cluster_resource_name: consul/project/f3945084-71ac-495c-84b3-371100d27279/cluster/consul-cluster
    consul.io/name: frontend
    consul.io/namespace: default
    consul.io/partition: default

Finally, link the plugin to Backstage to start the HCP Consul frontend plugin:

yarn backstage-cli --no-yarn --cwd ./plugins/hcp-consul start

You have successfully installed both the frontend and backend plugins for HCP Consul integration with Backstage.

Verify HCP Consul plugin for Backstage

Go to your HCP Consul plugin Backstage page. The URL path is <backstage-instance>/hcp-consul.

Navigate to the following sections in the Backstage UI to explore the new Consul integration features: The Overview page provides a high-level overview of the clusters and services, including the instances for your linked clusters. It also shows unhealthy services across the clusters.

The Clusters page lists the clusters. You can expand the individual clusters to check more details.

The Services page lists all services across clusters. You can expand a service to see the instance details:

Next steps

With the plugin-hcp-consul and plugin-hcp-consul-backend installed, you can start leveraging the benefits of HCP Consul within your Backstage environment. Explore the new features, manage configurations, and enhance your infrastructure orchestration capabilities. You are also welcome to contribute to the plugin — visit the plugin repo for more details.

For more detailed information, refer to the official READMEs: plugin-hcp-consul README and plugin-hcp-consul-backend README.

View the full article