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
.
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.
Before you begin, you will need:
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
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 to default.
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/v1alpha1kind: Componentmetadata: 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.
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:
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.
Do cloud right with The Infrastructure Cloud from HashiCorp. Unlock developer potential while controlling cloud costs and risk.
A recap of HashiCorp infrastructure and security news and developments from Google Cloud Next, from scaling infrastructure as code to fighting secrets sprawl and more.
Try this example method for transitioning from Consul service discovery to service mesh without affecting uptimes or development teams.