docs: fix typos, IDs are UUIDs, /acl/token endpoints manage ACL tokens (#5736)
This commit is contained in:
Anthony Scalisi
GitHub
parent
bb207b722e
commit
3616c94935
|
|
@ -3,7 +3,7 @@ layout: api
|
|||
page_title: ACL Policies - HTTP API
|
||||
sidebar_current: api-acl-policies
|
||||
description: |-
|
||||
The /acl/policy endpoints manage Consul's ACL Policies.
|
||||
The /acl/policy endpoints manage Consul's ACL policies.
|
||||
---
|
||||
|
||||
-> **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/acl/legacy.html)
|
||||
|
|
@ -12,7 +12,7 @@ description: |-
|
|||
|
||||
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.
|
||||
[delete](#delete-a-policy) ACL policies in Consul.
|
||||
|
||||
For more information on how to setup ACLs, please see
|
||||
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
|
||||
|
|
@ -49,11 +49,11 @@ The table below shows this endpoint's support for
|
|||
- `Datacenters` `(array<string>)` - Specifies the datacenters the policy is valid within.
|
||||
When no datacenters are provided the policy is valid in all datacenters including
|
||||
those which do not yet exist but may in the future.
|
||||
|
||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||
|
||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||
create the policy. If not provided in the JSON body, the value of
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
||||
### Sample Payload
|
||||
|
|
@ -115,9 +115,9 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `id` `(string: <required>)` - Specifies the UUID of the ACL policy to
|
||||
read. This is required and is specified as part of the URL path.
|
||||
|
||||
|
||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
||||
the policy. This value can be specified as the `ns` URL query
|
||||
the policy. This value can be specified as the `ns` URL query
|
||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||
the namespace will be inherited from the request's ACL token or will default
|
||||
to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
|
@ -165,7 +165,7 @@ The table below shows this endpoint's support for
|
|||
|
||||
### Parameters
|
||||
|
||||
- `ID` `(string: <required>)` - Specifies the ID of the policy to update. This is
|
||||
- `ID` `(string: <required>)` - Specifies the UUID of the policy to update. This is
|
||||
required in the URL path but may also be specified in the JSON body. If specified
|
||||
in both places then they must match exactly.
|
||||
|
||||
|
|
@ -181,11 +181,11 @@ The table below shows this endpoint's support for
|
|||
- `Datacenters` `(array<string>)` - Specifies the datacenters this policy is valid within.
|
||||
When no datacenters are provided the policy is valid in all datacenters including
|
||||
those which do not yet exist but may in the future.
|
||||
|
||||
|
||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||
the policy to update. If not provided in the JSON body, the value of
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
||||
### Sample Payload
|
||||
|
|
@ -246,9 +246,9 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `id` `(string: <required>)` - Specifies the UUID of the ACL policy to
|
||||
delete. This is required and is specified as part of the URL path.
|
||||
|
||||
|
||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
|
||||
policy to delete. This value can be specified as the `ns` URL query
|
||||
policy to delete. This value can be specified as the `ns` URL query
|
||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||
the namespace will be inherited from the request's ACL token or will default
|
||||
to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
|
@ -286,7 +286,7 @@ The table below shows this endpoint's support for
|
|||
### Parameters
|
||||
|
||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
|
||||
the Policies for. This value can be specified as the `ns` URL query
|
||||
the Policies for. This value can be specified as the `ns` URL query
|
||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||
the namespace will be inherited from the request's ACL token or will default
|
||||
to the `default` namespace. The namespace may be specified as '*' and then
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ description: |-
|
|||
# ACL Token HTTP API
|
||||
|
||||
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 policies in Consul.
|
||||
[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 see
|
||||
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
|
||||
|
|
@ -89,11 +89,11 @@ The table below shows this endpoint's support for
|
|||
specified in the form of `"60s"` or `"5m"` (i.e., 60 seconds or 5 minutes,
|
||||
respectively). This value must be no smaller than 1 minute and no longer than
|
||||
24 hours. Added in Consul 1.5.0.
|
||||
|
||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||
|
||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
|
||||
create the token. If not provided in the JSON body, the value of
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
||||
### Sample Payload
|
||||
|
|
@ -169,9 +169,9 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to
|
||||
read. This is required and is specified as part of the URL path.
|
||||
|
||||
|
||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
|
||||
the token. This value can be specified as the `ns` URL query
|
||||
the token. This value can be specified as the `ns` URL query
|
||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||
the namespace will be inherited from the request's ACL token or will default
|
||||
to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
|
@ -343,8 +343,8 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||
the token to update. If not provided in the JSON body, the value of
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
||||
### Sample Payload
|
||||
|
|
@ -431,8 +431,8 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
|
||||
the token to be cloned. If not provided in the JSON body, the value of
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
|
||||
If not provided at all, the namespace will be inherited from the request's ACL
|
||||
token or will default to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
||||
### Sample Payload
|
||||
|
|
@ -503,11 +503,11 @@ The table below shows this endpoint's support for
|
|||
|
||||
### Parameters
|
||||
|
||||
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL policy to
|
||||
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to
|
||||
delete. This is required and is specified as part of the URL path.
|
||||
|
||||
|
||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
|
||||
token to delete. This value can be specified as the `ns` URL query
|
||||
token to delete. This value can be specified as the `ns` URL query
|
||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||
the namespace will be inherited from the request's ACL token or will default
|
||||
to the `default` namespace. Added in Consul 1.7.0.
|
||||
|
|
@ -552,15 +552,15 @@ The table below shows this endpoint's support for
|
|||
|
||||
- `authmethod` `(string: "")` - Filters the token list to those tokens that are
|
||||
linked with the specific named auth method.
|
||||
|
||||
|
||||
- `authmethod-ns` `(string: "")` - **(Enterprise Only)** Specifics the namespace
|
||||
of the `authmethod` being used for token lookup. If not provided, the namespace
|
||||
provided by the `ns` parameter will be used. If neither of those is provided
|
||||
then the namespace will be inherited from the request's ACL token. Added in
|
||||
then the namespace will be inherited from the request's ACL token. Added in
|
||||
Consul 1.7.0.
|
||||
|
||||
|
||||
- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
|
||||
the tokens for. This value can be specified as the `ns` URL query
|
||||
the tokens for. This value can be specified as the `ns` URL query
|
||||
parameter or the `X-Consul-Namespace` header. If not provided by either,
|
||||
the namespace will be inherited from the request's ACL token or will default
|
||||
to the `default` namespace. The namespace may be specified as '*' and then
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ To complete the RPC encryption section, you must have [configured agent certific
|
|||
|
||||
## Gossip Encryption
|
||||
|
||||
To enable gossip encryption, you need to use an encryption key when starting the Consul agent. The key can be simple set with the `encrypt` parameter in the agent configuration file. Alternatively, the encryption key can be placed in a seperate configuration file with only the `encrypt` field, since the agent can merge multiple configuration files. The key must be 32-bytes, Base64 encoded.
|
||||
To enable gossip encryption, you need to use an encryption key when starting the Consul agent. The key can be simple set with the `encrypt` parameter in the agent configuration file. Alternatively, the encryption key can be placed in a separate configuration file with only the `encrypt` field, since the agent can merge multiple configuration files. The key must be 32-bytes, Base64 encoded.
|
||||
|
||||
You can use the Consul CLI command, [`consul keygen`](/docs/commands/keygen.html), to generate a cryptographically suitable key.
|
||||
|
||||
|
|
@ -58,7 +58,7 @@ Note: all nodes within a cluster must share the same encryption key in order to
|
|||
|
||||
### Enable Gossip Encryption: Existing Cluster
|
||||
|
||||
Gossip encryption can also be enabled on an existing cluster, but requires several extra steps. The additional configuration of the agent configuration parameters, [`encrypt_verify_incoming`](/docs/agent/options.html#encrypt_verify_incoming) and [`encrypt_verify_outgoing`](/docs/agent/options.html#encrypt_verify_outgoing) is necessary.
|
||||
Gossip encryption can also be enabled on an existing cluster, but requires several extra steps. The additional configuration of the agent configuration parameters, [`encrypt_verify_incoming`](/docs/agent/options.html#encrypt_verify_incoming) and [`encrypt_verify_outgoing`](/docs/agent/options.html#encrypt_verify_outgoing) is necessary.
|
||||
|
||||
**Step 1**: Generate an encryption key using `consul keygen`.
|
||||
|
||||
|
|
@ -95,9 +95,9 @@ A rolling update can be made by restarting the Consul agents (clients and server
|
|||
"encrypt_verify_incoming": false,
|
||||
"encrypt_verify_outgoing": true
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
**Step 4**: The previous step, enabling verify outgoing, must be completed on all agents before continuing. Update the `encrypt_verify_incoming` setting to `true` and perform a final rolling update of the cluster.
|
||||
**Step 4**: The previous step, enabling verify outgoing, must be completed on all agents before continuing. Update the `encrypt_verify_incoming` setting to `true` and perform a final rolling update of the cluster.
|
||||
|
||||
```javascript
|
||||
{
|
||||
|
|
@ -113,7 +113,7 @@ A rolling update can be made by restarting the Consul agents (clients and server
|
|||
|
||||
All the agents will now be strictly enforcing encrypted gossip. Note, the default
|
||||
behavior of both `encrypt_verify_incoming` and `encrypt_verify_outgoing` is `true`.
|
||||
We have set them in the configuration file as an explicit example.
|
||||
We have set them in the configuration file as an explicit example.
|
||||
|
||||
## TLS Encryption for RPC
|
||||
|
||||
|
|
@ -122,12 +122,12 @@ Consul requires that all servers have certificates that are signed by a single
|
|||
Certificate Authority. Clients may optionally authenticate with a client certificate generated by the same CA. Please see
|
||||
[this tutorial on creating a CA and signing certificates](/docs/guides/creating-certificates.html).
|
||||
|
||||
TLS can be used to verify the authenticity of the servers with [`verify_outgoing`](/docs/agent/options.html#verify_outgoing) and [`verify_server_hostname`](/docs/agent/options.html#verify_server_hostname). It can also optionally verify client certificates when using [`verify_incoming`](/docs/agent/options.html#verify_incoming)
|
||||
TLS can be used to verify the authenticity of the servers with [`verify_outgoing`](/docs/agent/options.html#verify_outgoing) and [`verify_server_hostname`](/docs/agent/options.html#verify_server_hostname). It can also optionally verify client certificates when using [`verify_incoming`](/docs/agent/options.html#verify_incoming)
|
||||
|
||||
Review the [docs for specifics](https://www.consul.io/docs/agent/encryption.html).
|
||||
|
||||
In Consul version 0.8.4 and newer, migrating to TLS encrypted traffic on a running cluster
|
||||
is supported.
|
||||
is supported.
|
||||
|
||||
### Enable TLS: New Cluster
|
||||
|
||||
|
|
@ -151,7 +151,7 @@ After TLS has been configured on all the agents, you can start the agents and RP
|
|||
|
||||
Note, for clients, the default `cert_file` and `key_file` will be named according to their cluster for. For example, `consul-client-dc1-0.pem`.
|
||||
|
||||
The `verify_outgoing` parameter enables agents to verify the authenticity of Consul servers for outgoing connections. The `verify_server_hostname` parameter requires outgoing connections to perform hostname verification and is critically important to prevent compromised client agents from becoming servers and revealing all state to the attacker. Finally, the `verify_incoming` parameter enables the servers to verify the authenticity of all incoming connections.
|
||||
The `verify_outgoing` parameter enables agents to verify the authenticity of Consul servers for outgoing connections. The `verify_server_hostname` parameter requires outgoing connections to perform hostname verification and is critically important to prevent compromised client agents from becoming servers and revealing all state to the attacker. Finally, the `verify_incoming` parameter enables the servers to verify the authenticity of all incoming connections.
|
||||
|
||||
### Enable TLS: Existing Cluster
|
||||
|
||||
|
|
@ -204,5 +204,5 @@ the [agent configuration](https://www.consul.io/docs/agent/options.html#ports).
|
|||
|
||||
## Summary
|
||||
|
||||
In this guide we configured both gossip encryption and TLS for RPC. Securing agent communication is a recommended set in setting up a production ready cluster.
|
||||
In this guide we configured both gossip encryption and TLS for RPC. Securing agent communication is a recommended set in setting up a production ready cluster.
|
||||
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ following are the defaults.
|
|||
```
|
||||
|
||||
All Consul servers should have Autopilot and its features either enabled
|
||||
or disabled to ensure consistency accross servers in case of a failure. Additionally,
|
||||
or disabled to ensure consistency across servers in case of a failure. Additionally,
|
||||
Autopilot must be enabled to use any of the features, but the features themselves
|
||||
can be configured independently. Meaning you can enable or disable any of the features
|
||||
separately, at any time.
|
||||
|
|
|
|||
Loading…
Reference in New Issue