HCP Consul Central API Overview

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:

1. Authenticate to HCP to generate an access token.
2. Use the access token to interact with your desired endpoints.

The HCP Consul Central API uses the following URLs:

In addition, you need the following to authenticate and interact with the API:

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 and HCP_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.

$ curl --location "https://auth.idp.hashicorp.com/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=$HCP_CLIENT_ID" \
--data-urlencode "client_secret=$HCP_CLIENT_SECRET" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "audience=https://api.hashicorp.cloud"

The response should be similar to the following. Notice the access token is only valid for an hour.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

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.

$ export HCP_ACCESS_TOKEN=<access-token>

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.

$ curl --location "https://api.cloud.hashicorp.com/2023-10-10/consul/project/$PROJECT_ID/clusters?pagination.page_size=10" \
--header "authorization: Bearer $HCP_ACCESS_TOKEN"

If you have an HCP Consul cluster in your project, the response should be similar to the following when the operation was successful.

{
  "pagination": {
    "next_page_token": "",
    "previous_page_token": ""
  },
  "data": [
    {
      "resource_id": "00000000-0000-0000-0000-000000000000",
      "resource_name": "consul/project/00000000/cluster/learn-consul",
      "parent_resource_id": "00000000",
      "parent_resource_name": "project/00000000",
      "name": "learn-consul",
      "state": "running",
      "type": "hcp_managed",
      "config": {
        "consul_config": {
            "datacenter":"learn-consul",
            "connect_enabled": false,
            "acl_enabled": false
        },
        "network_config": {
            "private": false,
            "resource_id": "learn-consul",
            "resource_name": "network/project/00000000/hvn/learn-consul",
            "ip_allowlist": []
        },
        "tier": "STANDARD",
        "size": "X_SMALL",
        "dns_names": {
            "public": "learn-consul.consul.00000000.aws.hashicorp.cloud",
            "private": "learn-consul.private.consul.00000000.aws.hashicorp.cloud"
        }
      },
      "consul_version": "1.16.2",
      "meta": {
        "created_at": "2023-09-25T18:19:17.129990Z",
        "updated_at": "2023-10-04T08:46:15.328178Z"
      },
      "region": {
        "provider": "aws",
        "region": "us-west-2"
      }
    }
  ]
}

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:

• HCP Consul Central Overview
• HCP Consul Central API Reference