diff --git a/.changelog/20308.txt b/.changelog/20308.txt new file mode 100644 index 0000000000..3dade6fb0d --- /dev/null +++ b/.changelog/20308.txt @@ -0,0 +1,3 @@ +```release-note:improvement +docs: add Link API documentation +``` diff --git a/website/content/api-docs/api-structure.mdx b/website/content/api-docs/api-structure.mdx index 62bd424fdd..0959e90643 100644 --- a/website/content/api-docs/api-structure.mdx +++ b/website/content/api-docs/api-structure.mdx @@ -41,14 +41,14 @@ $ curl \ ``` **Security Note:** Though you could pass the token through the `?token=` query parameter, -this method is highly discouraged because the token can show up in access logs as part of the URL. +this method is highly discouraged because the token can show up in access logs as part of the URL. The `?token=` query parameter is deprecated and will be removed in a future Consul version. To learn more about the ACL system read the [documentation](/consul/docs/security/acl). ## Version Prefix -All API routes are prefixed with `/v1/`. This documentation is only for the v1 API. +Unless indicated otherwise, all API routes are prefixed with `/v1/`. ## Formatted JSON Output @@ -159,3 +159,8 @@ UUID-format identifiers generated by the Consul API use the These UUID-format strings are generated using high quality, purely random bytes. It is not intended to be RFC compliant, merely to use a well-understood string representation of a 128-bit value. + +## CORS HTTP Response Headers + +As of Consul 1.18, Consul adds an HTTP header `Access-Control-Expose-Headers: x-consul-default-acl-policy` to +all responses in order to support linking self-managed Consul clusters to HCP Consul Central. diff --git a/website/content/api-docs/hcp-link.mdx b/website/content/api-docs/hcp-link.mdx new file mode 100644 index 0000000000..5b1cdfac73 --- /dev/null +++ b/website/content/api-docs/hcp-link.mdx @@ -0,0 +1,190 @@ +--- +layout: api +page_title: HCP Linking HTTP API +description: The Link resource allows for linking your cluster to HCP Consul Central. +--- + +# Link HTTP API + +-> **1.18.0+:** The Link API is available in Consul versions 1.18.0 and newer. + +-> **Note:** This endpoint does not use the `/v1/` prefix. + +The `/api/hcp/v2/link/global` endpoint allows you to link your Consul cluster to [HCP Consul Central](/hcp/docs/consul/concepts/consul-central). + +## Establish or update link to HCP Consul Central + +This endpoint creates or updates a Link, which establishes a connection with HCP Consul Central. + +| Method | Path | Produces | +| ------ | ----------------------------- | ------------------ | +| `PUT` | `/api/hcp/v2/link/global` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). + +| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | +| ---------------- | --------------------- | ------------- | ------------------------------ | +| `NO` | `stale`, `consistent` | `none` | `operator:write`, `acl:write` | + +### Link API vs. configuration-based linking + +The Link API described here is an alternative method to accomplish the same thing as [configuration-based linking](/consul/docs/agent/config/config-files#self-managed-hcp-parameters). You should generally only choose one method or the other for linking your cluster, not both. If you do use both methods, they interract in the following ways: + +* When Consul is started, values set in the `cloud` configuration will take precedence over what was previously set by the API or CLI. +* Clusters can only be unlinked from HCP Consul Central by the API or CLI, regardless of if they were established via configuration, API, or CLI. + +### JSON Request Body Schema + +- `data` `(object: )` + + - `resourceId` `(string: )` - The ID of the HCP Consul Central cluster to link to. Has the format of: + `organization//project//hashicorp.consul.global-network-manager.cluster/` + + - `clientId` `(string: )` - The ID used to authenticate to HCP, which is returned as part of the HCP + Consul Central cluster creation. It can also be obtained by fetching the HCP Consul Central cluster secrets. + + - `clientSecret` `(string: )` - The secret used to authenticate to HCP, which is returned as part of the + HCP Consul Central cluster creation. It can also be obtained by fetching the HCP Consul Central cluster secrets. + +### Sample Payload + +```json +{ + "data": { + "resourceId": "organization/c0bf7aac-7690-4905-a8aa-889df1510314/project/6e82a47b-79af-4920-ad42-c0f74421ab52/hashicorp.consul.global-network-manager.cluster/my-cluster", + "clientId": "3jz6zk2tlr802htzwquczlxlsrohlpm5", + "clientSecret": "07ywcvaqmg1f8ko9eq4julep2tfglnv4o18rz3py9dik4ywox0ytoscycn39o4vs" + } +} +``` + +### Sample Request + +```shell-session +$ curl --request PUT \ + --header "X-Consul-Token: 9cdjse6c-2dia-3720-81fe-5dae3k714a6e" \ + --data @payload.json \ + http://127.0.0.1:8500/api/hcp/v2/link/global +``` + +### Sample Response + +```json +{ + "data": { + "clientId": "3jz6zk2tlr802htzwquczlxlsrohlpm5", + "clientSecret": "07ywcvaqmg1f8ko9eq4julep2tfglnv4o18rz3py9dik4ywox0ytoscycn39o4vs", + "resourceId": "organization/c0bf7aac-7690-4905-a8aa-889df1510314/project/6e82a47b-79af-4920-ad42-c0f74421ab52/hashicorp.consul.global-network-manager.cluster/my-cluster" + }, + "generation": "01HMHTHZND8VJDXHHJBKDR4TTA", + "id": { + "name": "global", + "tenancy": { + "peerName": "local" + }, + "type": { + "group": "hcp", + "groupVersion": "v2", + "kind": "Link" + }, + "uid": "01HMHTHZND8VJDXHHJBGY1KG0F" + }, + "version": "60" +} +``` + +## Read Link + +This endpoint reads a Link so you can view information about your cluster's current linking status. + +| Method | Path | Produces | +| ------ | ----------------------------- | ------------------ | +| `GET` | `/api/hcp/v2/link/global` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). + +| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | +| ---------------- | --------------------- | ------------- | ---------------- | +| `NO` | `stale`, `consistent` | `none` | `operator:read` | + +### Sample Request + +```shell-session +$ curl --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \ + http://127.0.0.1:8500/api/hcp/v2/link/global +``` + +### Sample Response +```json +{ + "data": { + "accessLevel": "ACCESS_LEVEL_GLOBAL_READ_WRITE", + "clientId": "3jz6zk2tlr802htzwquczlxlsrohlpm5", + "clientSecret": "07ywcvaqmg1f8ko9eq4julep2tfglnv4o18rz3py9dik4ywox0ytoscycn39o4vs", + "hcpClusterUrl": "https://portal.cloud.hashicorp.com/services/consul/clusters/self-managed/my-cluster?project_id=6e82a47b-79af-4920-ad42-c0f74421ab52", + "resourceId": "organization/c0bf7aac-7690-4905-a8aa-889df1510314/project/6e82a47b-79af-4920-ad42-c0f74421ab52/hashicorp.consul.global-network-manager.cluster/my-cluster" + }, + "generation": "01HMHTF4K5V27T91FMVHGFE87F", + "id": { + "name": "global", + "tenancy": { + "peerName": "local" + }, + "type": { + "group": "hcp", + "groupVersion": "v2", + "kind": "Link" + }, + "uid": "01HMHS7DJ9FEQH5XK1VD0W0536" + }, + "status": { + "consul.io/hcp/link": { + "conditions": [ + { + "message": "Successfully linked to cluster 'organization/c0bf7aac-7690-4905-a8aa-889df1510314/project/6e82a47b-79af-4920-ad42-c0f74421ab52/hashicorp.consul.global-network-manager.cluster/my-cluster'", + "reason": "SUCCESS", + "state": "STATE_TRUE", + "type": "linked" + } + ], + "observedGeneration": "01HMHS7DN1C417JXJF7DBVS79F", + "updatedAt": "2024-01-19T21:14:59.707744Z" + } + }, + "version": "53" +} +``` + +## Delete Link + +This endpoint deletes a Link, which removes the cluster's connection with HCP Consul Central. + +| Method | Path | Produces | +| --------- | ----------------------------- | ------------------ | +| `DELETE` | `/api/hcp/v2/link/global` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). + +| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | +| ---------------- | ---------------------- | ------------- | -------------------------------- | +| `NO` | `stale`, `consistent` | `none` | `operator:write`, `acl:write` | + +### Sample Request + +```shell-session +$ curl --request DELETE \ + --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \ + http://127.0.0.1:8500/api/hcp/v2/link/global +``` diff --git a/website/content/api-docs/index.mdx b/website/content/api-docs/index.mdx index 20d0021e30..1b972e4425 100644 --- a/website/content/api-docs/index.mdx +++ b/website/content/api-docs/index.mdx @@ -49,6 +49,7 @@ The following API endpoints help you manage Consul operations. - [`/namespace`](/consul/api-docs/namespaces): Create and manage namespaces in Consul. Namespaces isolate groups of resources to lower operational overhead. - [`/snapshot`](/consul/api-docs/snapshot): Save and restore Consul server state in the event of a disaster. - [`/txn`](/consul/api-docs/txn): Apply multiple operations, such as updating the catalog and retrieving multiple KV entries, in a single transaction. +- [`/api/hcp/v2/link/global`](/consul/api-docs/hcp-link): Link cluster to [HCP Consul Central](/hcp/docs/consul/concepts/consul-central). HCP Consul Central is a management plane service hosted by HashiCorp that enables you to monitor and manage Consul clusters. ## Configure your services dynamically diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 63109eb5e2..3d49a9b422 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -131,6 +131,10 @@ "title": "Events", "path": "event" }, + { + "title": "HCP Consul Central Link", + "path": "hcp-link" + }, { "title": "Health", "path": "health"