How to use the Backstage HCP Consul plugin
Integrating HCP Consul Central with Backstage can enhance your organization’s infrastructure-management capabilities. Here’s how to do it.
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.
![Workflow for the HCP Consul plugin](/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F2885%2F1704831054-backstage-consul-edited.png&w=3840&q=75)
Workflow for the HCP Consul plugin
» 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/
:
hcp-consul-backend.ts
import { createRouter } from '@hashicorp/plugin-hcp-consul-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter(env);
}
Next, modify your packages/backend/src/index.ts
to import and configure the HCP Consul backend plugin:
index.ts
...
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:
app-config.yaml
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 <token>" localhost:7007/api/hcp-consul-backend/2023-10-10/consul/project/<projectId>/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:
App.tsx
import { HcpConsulPluginPage } from '@hashicorp/plugin-hcp-consul';
const routes = (
<FlatRoutes>
...
<Route path="/hcp-consul" element={<HcpConsulPluginPage />} />
);
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:
<HcpConsulPluginPage projectID="f3945084-71ac-495c-84b3-371100d27279"/>
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:
EntityPage.tsx
// In packages/app/src/components/catalog/EntityPage.tsx
import { EntityServiceInstancesTable, isHcpConsulServiceAvailable } from '@hashicorp/plugin-hcp-consul';
const serviceEntityPage = (
...
<EntityLayout.Route
if={isHcpConsulServiceAvailable}
path="/hcp-consul-instances"
title="Instances"
>
<EntityServiceInstancesTable />
</EntityLayout.Route>
)
You need to provide annotations to the component:
-
consul.io/cluster_resource_name
annotation's value is the cluster resource name in HCP. It is required. -
consul.io/name
annotation's value is the service name. It is required. -
consul.io/namespace
is the namespace of the service. If omitted, it defaults todefault.
-
consul.io/partition
is the partition of the service. If omitted, it defaults todefault.
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
![Service instances tab on the EntityPage of Backstage](/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F2885%2F1704830047-frontend-service-backstage-consul.png&w=3840&q=75)
Service instances tab on the EntityPage of Backstage
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.
![Overview page for HCP Consul backstage plugin](/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F2885%2F1704830189-hcp-consul-overview.png&w=3840&q=75)
Overview page for HCP Consul backstage plugin
The Clusters page lists the clusters. You can expand the individual clusters to check more details.
![Clusters page for HCP Consul backstage plugin](/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F2885%2F1704830160-hcp-consul-clusters.png&w=3840&q=75)
Clusters page for HCP Consul backstage plugin
The Services page lists all services across clusters. You can expand a service to see the instance details:
![Services page for HCP Consul backstage plugin](/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F2885%2F1704830399-services-list.png&w=3840&q=75)
Services page for HCP Consul backstage plugin
» 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.
Sign up for the latest HashiCorp news
More blog posts like this one
![Consul 1.19 improves Kubernetes workflows, snapshot support, and Nomad integration](/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F2885%2F1714170780-blog-library-product-consul-dark-gradient.jpg&w=3840&q=75)
Consul 1.19 improves Kubernetes workflows, snapshot support, and Nomad integration
HashiCorp Consul 1.19 simplifies external service registration in Consul on Kubernetes, boosts Nomad support, and adds even more enhancements.
![Mitigate cloud risk with Security Lifecycle Management](/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F2885%2F1713794485-aws-slm-img.png&w=1920&q=75)
Mitigate cloud risk with Security Lifecycle Management
Protect, inspect, and connect your sensitive data with Security Lifecycle Management solutions from HashiCorp.
![Introducing The Infrastructure Cloud](/_next/image?url=https%3A%2F%2Fwww.datocms-assets.com%2F2885%2F1715105078-blog-library-product-ic-infrastructure-cloud-hero-logo-image-edited.png&w=3840&q=75)
Introducing The Infrastructure Cloud
Do cloud right with The Infrastructure Cloud from HashiCorp. Unlock developer potential while controlling cloud costs and risk.