HCP Consul Central API Overview
Note
HCP Consul Central API is in beta: Functionality associated with this API is subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may experience performance and scaling issues and have limited support options.
This topic provides an overview for using the HCP Consul Central API, a RESTful API for the hosted management plane service available through HCP Consul. HCP Consul Central is an interface that centralizes global management operations across all Consul clusters. It provides global visibility and control for both HashiCorp-managed and self-managed Consul clusters, even when you deploy services in multiple cloud environments and regions. For complete operational and technical specifications, refer to HCP Consul Central API reference.
For an explanation of what HCP Consul Central is and the benefits it provides, refer to HCP Consul Central.
The HCP Consul Central API is different from the HTTP API for Consul, which enables you to interact with your Consul clusters. Refer to the Consul API docs to learn more about the Consul HTTP API.
Overview
The following steps describe the procedure for interacting with the HCP Consul Central API:
- Authenticate to HCP to generate an access token.
- Use the access token to interact with your desired endpoints.
The HCP Consul Central API uses the following URLs:
Attribute | Description | Value |
---|---|---|
API base URL | The base endpoint URL for the HCP API service | https://api.cloud.hashicorp.com |
HCP Authentication URL | The URL to authenticate to HCP using a service principal client ID and secret | https://auth.idp.hashicorp.com |
In addition, you need the following to authenticate and interact with the API:
Attribute | Description |
---|---|
Client ID | Service principal client ID used to authenticate to HCP |
Client Secret | Service principal client secret used to authenticate to HCP |
Project ID | HCP project that contains the resources you want to query |
You can use the HCP Consul Central API to retrieve information about the clusters, nodes, services, and service instances within your HCP project. The following provides a description of the available operations:
- Cluster:
ListClusters
retrieves all of the Consul clusters in the HCP project.GetCluster
retrieves information about a specific HCP Consul cluster.
- Node:
ListNodes
retrieves all nodes in the HCP project.ListClusterNodes
retrieves all nodes in a specific HCP Consul cluster.GetNode
retrieves information about a specific node.
- Service:
ListServices
retrieves all services in the HCP project.ListClusterServices
retrieves all the services in a specific HCP Consul cluster.GetService
retrieves information about a specific service.
- Service instance:
ListServiceInstances
retrieves all service instances registered under a service name.GetServiceInstance
retrieves information about a specific service instance.
Refer to HCP Consul Central API Reference to find a description of each operation along with its parameters and responses.
Prerequisites
- An HCP account with HCP Consul Central access. Refer to HCP Account for information about creating an account and HCP Consul Central trial account for information feature availability.
- Your HCP Consul project must have at least one Consul cluster. This cluster can be either a HashiCorp-managed cluster or a self-managed cluster.
- Set the
HCP_CLIENT_ID
andHCP_CLIENT_SECRET
environment variables to a service principal key. Packer uses these values to authenticate to HCP and generate an access key . - Set the
PROJECT_ID
environment variable to your HCP project ID. Refer to HCP Projects for information about creating and managing projects. You can retrieve your project ID from the Project settings page.
Authenticate to HCP
The HCP Consul Central API requires an access token to authorize the request.
Generate the access key with your HCP client ID and secret.
The response should be similar to the following. Notice the access token is only valid for an hour.
Set the HCP_ACCESS_TOKEN
environment variable to the access token. This action makes it easier to reference the token when you are interacting with the API.
Interact with API
After you have retrieved the access token, you are now ready to use the HCP Consul Central API. You need to provide the access token in the Authorization
header as a bearer token in each request.
The following example shows you how to retrieve all clusters in your HCP project. The workflow and authorization process is similar for other HCP Consul Central operations.
If you have an HCP Consul cluster in your project, the response should be similar to the following when the operation was successful.
Limits and constraints
HCP Consul Central API is currently in public beta. The following constraints and limitations apply during the beta phase:
- HCP Consul Central API does not have an SLA or production-grade guarantee of availability. We do not recommend using HCP Consul Central API for critical applications.
- There is a limit of 500 requests per minute for all HCP Consul Central API endpoints.
Next steps
To learn more about what you can do with HCP Consul Central and its API, refer to the following topics: