@ -6,17 +6,17 @@ description: The /acl endpoints manage the Consul's ACL system.
# ACL HTTP API
-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api-docs/acl/legacy).
-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/consul/api-docs/acl/legacy).
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api-docs/acl/tokens) and [policies](/api-docs/acl/policies) with the `/acl` endpoints.
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/consul/api-docs/acl/tokens) and [policies](/consul/api-docs/acl/policies) with the `/acl` endpoints.
For more information on how to setup ACLs, please check
the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
## Bootstrap ACLs
This endpoint does a special one-time bootstrap of the ACL system, making the first
management token if the [`acl.tokens.initial_management`](/docs/agent/config/config-files#acl_tokens_initial_management)
management token if the [`acl.tokens.initial_management`](/consul/docs/agent/config/config-files#acl_tokens_initial_management)
configuration entry is not specified in the Consul server configuration and if the
cluster has not been bootstrapped previously. An operator created token can be provided in the body of the request to
bootstrap the cluster if required. The provided token should be presented in a UUID format.
The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api-docs/acl#check-acl-replication) to learn more about this endpoint.
The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/consul/api-docs/acl#check-acl-replication) to learn more about this endpoint.
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api-docs/acl/legacy).
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/consul/api-docs/acl/legacy).
The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy),
[update](#update-a-policy), [list](#list-policies) and
[delete](#delete-a-policy) ACL policies in Consul.
For more information on how to setup ACLs, please check
the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
## Create a Policy
@ -24,16 +24,16 @@ This endpoint creates a new ACL policy.
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api-docs/acl/legacy).
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/consul/api-docs/acl/legacy).
The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token),
[update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul.
For more information on how to setup ACLs, please check
the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
## Create a Token
@ -23,16 +23,16 @@ This endpoint creates a new ACL token.
The Consul HTTP API is a RESTful interface that allows you to leverage Consul functionality in your network. This topic provides guidance about the essential API endpoints for different workstreams. Refer to the [HTTP API structure](/api-docs/api-structure) docs to learn how to interact with and authenticate against the Consul HTTP API.
The Consul HTTP API is a RESTful interface that allows you to leverage Consul functionality in your network. This topic provides guidance about the essential API endpoints for different workstreams. Refer to the [HTTP API structure](/consul/api-docs/api-structure) docs to learn how to interact with and authenticate against the Consul HTTP API.
## Connect your services
Use the following API endpoints to configure and connect your services.
- [`/catalog`](/api-docs/catalog): Register and deregister nodes, services, and health checks.
- [`/health`](/api-docs/health): Query node health when health checks are enabled.
- [`/query`](/api-docs/query): Create and manage prepared queries in Consul. Prepared queries allow you to register a complex service query and send it later.
- [`/coordinate`](/api-docs/coordinate): Query the network coordinates for nodes in the local datacenter and Consul servers in the local datacenter and remote datacenters.
- [`/catalog`](/consul/api-docs/catalog): Register and deregister nodes, services, and health checks.
- [`/health`](/consul/api-docs/health): Query node health when health checks are enabled.
- [`/query`](/consul/api-docs/query): Create and manage prepared queries in Consul. Prepared queries allow you to register a complex service query and send it later.
- [`/coordinate`](/consul/api-docs/coordinate): Query the network coordinates for nodes in the local datacenter and Consul servers in the local datacenter and remote datacenters.
The following endpoints are specific to service mesh:
- [`/config`](/api-docs/config): Create, update, delete, and query central configuration entries registered with Consul. Configuration entries define the default behavior of resources in the service mesh.
- [`/agent/connect`](/api-docs/agent/connect): Interact with local agents in the service mesh.
- [`/connect`](/api-docs/connect): Manage service mesh-related operations, including service intentions ([`/connect/intentions`](/api-docs/connect/intentions)) and the service mesh certificate authority (CA) ([`/connect/ca`](/api-docs/connect/ca)).
- [`/config`](/consul/api-docs/config): Create, update, delete, and query central configuration entries registered with Consul. Configuration entries define the default behavior of resources in the service mesh.
- [`/agent/connect`](/consul/api-docs/agent/connect): Interact with local agents in the service mesh.
- [`/connect`](/consul/api-docs/connect): Manage service mesh-related operations, including service intentions ([`/connect/intentions`](/consul/api-docs/connect/intentions)) and the service mesh certificate authority (CA) ([`/connect/ca`](/consul/api-docs/connect/ca)).
## Enable zero-trust network security
The following API endpoints give you control over access to services in your network and access to the Consul API.
- [`/acl`](/api-docs/acl): Create and manage tokens that authenticate requests and authorize access to resources in the network. We recommend enabling access control lists (ACL) to secure access to the Consul API, UI, and CLI.
- [`/connect/intentions`](/api-docs/connect/intentions): Create and manage service intentions.
- [`/acl`](/consul/api-docs/acl): Create and manage tokens that authenticate requests and authorize access to resources in the network. We recommend enabling access control lists (ACL) to secure access to the Consul API, UI, and CLI.
- [`/connect/intentions`](/consul/api-docs/connect/intentions): Create and manage service intentions.
## Observe your network
Use the following API endpoints enable network observability.
- [`/status`](/api-docs/status): Debug your Consul datacenter by returning low-level Raft information about Consul server peers.
- [`/agent/metrics`](/api-docs/agent#view-metrics): Retrieve metrics for the most recent intervals that have finished. For more information about metrics, refer to [Telemetry](/docs/agent/telemetry).
- [`/status`](/consul/api-docs/status): Debug your Consul datacenter by returning low-level Raft information about Consul server peers.
- [`/agent/metrics`](/consul/api-docs/agent#view-metrics): Retrieve metrics for the most recent intervals that have finished. For more information about metrics, refer to [Telemetry](/consul/docs/agent/telemetry).
## Manage Consul
The following API endpoints help you manage Consul operations.
- [`/operator`](/api-docs/operator): Perform cluster-level tasks, such as interacting with the Raft subsystem or obtaining license information.
- [`/partition`](/api-docs/admin-partitions): Create and manage administrative or admin partitions in Consul. Admin partitions are supersets of Consul namespaces that isolate groups of resources to lower operational overhead.
- [`/namespace`](/api-docs/namespaces): Create and manage namespaces in Consul. Namespaces isolate groups of resources to lower operational overhead.
- [`/snapshot`](/api-docs/snapshot): Save and restore Consul server state in the event of a disaster.
- [`/txn`](/api-docs/txn): Apply multiple operations, such as updating the catalog and retrieving multiple KV entries, in a single transaction.
- [`/operator`](/consul/api-docs/operator): Perform cluster-level tasks, such as interacting with the Raft subsystem or obtaining license information.
- [`/partition`](/consul/api-docs/admin-partitions): Create and manage administrative or admin partitions in Consul. Admin partitions are supersets of Consul namespaces that isolate groups of resources to lower operational overhead.
- [`/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.
## Configure your services dynamically
The following API endpoints enable you to dynamically configure your services.
- [`/event`](/api-docs/event): Start a custom event that you can use to build scripts and automations.
- [`/kv`](/api-docs/kv): Add, remove, and update metadata stored in the Consul KV store.
- [`/session`](/api-docs/session): Create and manage [sessions](/docs/dynamic-app-config/sessions) in Consul. You can use sessions to build distributed and granular locks to ensure nodes are properly writing to the Consul KV store.
- [`/event`](/consul/api-docs/event): Start a custom event that you can use to build scripts and automations.
- [`/kv`](/consul/api-docs/kv): Add, remove, and update metadata stored in the Consul KV store.
- [`/session`](/consul/api-docs/session): Create and manage [sessions](/consul/docs/dynamic-app-config/sessions) in Consul. You can use sessions to build distributed and granular locks to ensure nodes are properly writing to the Consul KV store.
The corresponding CLI command is [`consul namespace update`](/commands/namespace/update) or [`consul namespace write`](/commands/namespace/write).
The corresponding CLI command is [`consul namespace update`](/consul/commands/namespace/update) or [`consul namespace write`](/consul/commands/namespace/write).
### Path Parameters
@ -258,7 +258,7 @@ The corresponding CLI command is [`consul namespace update`](/commands/namespace
struct is an object with an "ID" and/or "Name" field to identify a policy.
When a name is used instead of an ID, Consul will resolve the name to an ID
and store that internally. The ACL token used in the API request
must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules)
must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules)
to the linked policy.
- `RoleDefaults` `(array<ACLLink>)` - This is the list of default roles
@ -266,7 +266,7 @@ The corresponding CLI command is [`consul namespace update`](/commands/namespace
struct is an object with an "ID" and/or "Name" field to identify a policy.
When a name is used instead of an ID, Consul will resolve the name to an ID
and store that internally. The ACL token used in the API request
must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules)
must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules)
@ -92,7 +92,7 @@ a value of an object specific to that operation.
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
- `Node` `(Node: <required>)` - Specifies the node information to use
for the operation. See the [catalog endpoint](/api-docs/catalog#parameters) for the fields in this object. Note the only the node can be specified here, not any services or checks - separate service or check operations must be used for those.
for the operation. See the [catalog endpoint](/consul/api-docs/catalog#parameters) for the fields in this object. Note the only the node can be specified here, not any services or checks - separate service or check operations must be used for those.
- `Service` operations have the following fields:
@ -102,14 +102,14 @@ a value of an object specific to that operation.
this service operation.
- `Service` `(Service: <required>)` - Specifies the service instance information to use
for the operation. See the [catalog endpoint](/api-docs/catalog#parameters) for the fields in this object.
for the operation. See the [catalog endpoint](/consul/api-docs/catalog#parameters) for the fields in this object.
- `Check` operations have the following fields:
- `Verb` `(string: <required>)` - Specifies the type of operation to perform.
- `Check` `(Service: <required>)` - Specifies the check to use
for the operation. See the [catalog endpoint](/api-docs/catalog#parameters) for the fields in this object.
for the operation. See the [catalog endpoint](/consul/api-docs/catalog#parameters) for the fields in this object.
Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/bootstrap](/api-docs/acl#bootstrap-acls)
Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/bootstrap](/consul/api-docs/acl#bootstrap-acls)
The `acl bootstrap` command generates a new token with unlimited privileges to use
for management purposes and outputs the token's details. Optionally, you can provide a Secret ID to use instead of generating a completely new token. You can create this bootstrapping token only once and afterwards bootstrapping
will be disabled. If all tokens are lost and you need to bootstrap again you can follow the bootstrap
- `-consul-dns-port` - The port of the Consul DNS resolver. If provided, DNS queries will be redirected to the provided IP address for name resolution.
- `-proxy-id` - The [proxy service](/docs/connect/registration/service-registration) ID.
- `-proxy-id` - The [proxy service](/consul/docs/connect/registration/service-registration) ID.
This service ID must already be registered with the local agent.
- `-proxy-inbound-port` - The inbound port that the proxy is listening on.
@ -78,7 +78,7 @@ information when `debug` is running. By default, it captures all information.
| `members` | A list of all the WAN and LAN members in the cluster. |
| `metrics` | Metrics from the in-memory metrics endpoint in the target, captured at the interval. |
| `logs` | `DEBUG` level logs for the target agent, captured for the duration. |
| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/docs/agent/config/config-files#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. |
| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/consul/docs/agent/config/config-files#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. |
@ -16,8 +16,8 @@ this can be used to run the `uptime` command across all machines providing
the `web` service.
Remote execution works by specifying a job, which is stored in the KV store.
Agents are informed about the new job using the [event system](/commands/event),
which propagates messages via the [gossip protocol](/docs/architecture/gossip).
Agents are informed about the new job using the [event system](/consul/commands/event),
which propagates messages via the [gossip protocol](/consul/docs/architecture/gossip).
As a result, delivery is best-effort, and there is **no guarantee** of execution.
While events are purely gossip driven, remote execution relies on the KV store
@ -30,7 +30,7 @@ through the Consul servers and the Raft consensus algorithm, so having a large
number of nodes in the cluster flow a large amount of data through the KV store
could make the cluster unavailable.
The table below shows the [required ACLs](/api-docs/api-structure#authentication) in order to
The table below shows the [required ACLs](/consul/api-docs/api-structure#authentication) in order to
execute this command.
| ACL Required | Scope |
@ -40,7 +40,7 @@ execute this command.
| `key:write` | `"_rexec"` prefix |
| `event:write` | `"_rexec"` prefix |
In addition to the above, the policy associated with the [agent token](/docs/security/acl/acl-tokens#acl-agent-token) should have `write` on `"_rexec"` key prefix. This is for the agents to read the `exec` command and write its output back to the KV store.
In addition to the above, the policy associated with the [agent token](/consul/docs/security/acl/acl-tokens#acl-agent-token) should have `write` on `"_rexec"` key prefix. This is for the agents to read the `exec` command and write its output back to the KV store.
Ashlee M Boyer
2 years ago
committed by