mirror of https://github.com/hashicorp/consul
Docs/CE-749-remove-references-from-consul (#21914)
* delete HCP Consul Central references * Path correction * missed listing * Nav updatepull/21919/head
Jeff Boruszak
3 weeks ago
committed by
GitHub
parent
1dfc265abe
commit
f376b6a227
@ -1,190 +0,0 @@
|
|||||||
---
|
|
||||||
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 interact 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: <required>)`
|
|
||||||
|
|
||||||
- `resourceId` `(string: <required>)` - The ID of the HCP Consul Central cluster to link to. Has the format of:
|
|
||||||
`organization/<orgID>/project/<projectID>/hashicorp.consul.global-network-manager.cluster/<clusterName>`
|
|
||||||
|
|
||||||
- `clientId` `(string: <required>)` - 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: <required>)` - 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
|
|
||||||
```
|
|
||||||
Loading…
Reference in new issue