Merge pull request #11232 from hashicorp/dnephin/acl-legacy-remove-docs
acl: add docs and changelog for the removal of the legacy ACL system
This commit is contained in:
Daniel Nephin
GitHub
commit
f24bad2a52
|
|
@ -0,0 +1,3 @@
|
||||||
|
```release-note:breaking-change
|
||||||
|
acl: The legacy ACL system that was deprecated in Consul 1.4.0 has been removed. Before upgrading you should verify that nothing is still using the legacy ACL system. See the [Migrate Legacy ACL Tokens Learn Guide](https://learn.hashicorp.com/tutorials/consul/access-control-token-migration) for more information.
|
||||||
|
```
|
||||||
|
|
@ -2,7 +2,6 @@ package agent
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"fmt"
|
"fmt"
|
||||||
"io/ioutil"
|
|
||||||
"net/http"
|
"net/http"
|
||||||
"strings"
|
"strings"
|
||||||
|
|
||||||
|
|
@ -74,37 +73,6 @@ func (s *HTTPHandlers) ACLReplicationStatus(resp http.ResponseWriter, req *http.
|
||||||
return out, nil
|
return out, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
func (s *HTTPHandlers) ACLRulesTranslate(resp http.ResponseWriter, req *http.Request) (interface{}, error) {
|
|
||||||
if s.checkACLDisabled(resp, req) {
|
|
||||||
return nil, nil
|
|
||||||
}
|
|
||||||
|
|
||||||
var token string
|
|
||||||
s.parseToken(req, &token)
|
|
||||||
authz, err := s.agent.delegate.ResolveTokenAndDefaultMeta(token, nil, nil)
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
// Should this require lesser permissions? Really the only reason to require authorization at all is
|
|
||||||
// to prevent external entities from DoS Consul with repeated rule translation requests
|
|
||||||
if authz.ACLRead(nil) != acl.Allow {
|
|
||||||
return nil, acl.ErrPermissionDenied
|
|
||||||
}
|
|
||||||
|
|
||||||
policyBytes, err := ioutil.ReadAll(req.Body)
|
|
||||||
if err != nil {
|
|
||||||
return nil, BadRequestError{Reason: fmt.Sprintf("Failed to read body: %v", err)}
|
|
||||||
}
|
|
||||||
|
|
||||||
translated, err := acl.TranslateLegacyRules(policyBytes)
|
|
||||||
if err != nil {
|
|
||||||
return nil, BadRequestError{Reason: err.Error()}
|
|
||||||
}
|
|
||||||
|
|
||||||
resp.Write(translated)
|
|
||||||
return nil, nil
|
|
||||||
}
|
|
||||||
|
|
||||||
func (s *HTTPHandlers) ACLPolicyList(resp http.ResponseWriter, req *http.Request) (interface{}, error) {
|
func (s *HTTPHandlers) ACLPolicyList(resp http.ResponseWriter, req *http.Request) (interface{}, error) {
|
||||||
if s.checkACLDisabled(resp, req) {
|
if s.checkACLDisabled(resp, req) {
|
||||||
return nil, nil
|
return nil, nil
|
||||||
|
|
|
||||||
|
|
@ -45,7 +45,6 @@ func TestACL_Disabled_Response(t *testing.T) {
|
||||||
{"ACLBootstrap", a.srv.ACLBootstrap},
|
{"ACLBootstrap", a.srv.ACLBootstrap},
|
||||||
{"ACLReplicationStatus", a.srv.ACLReplicationStatus},
|
{"ACLReplicationStatus", a.srv.ACLReplicationStatus},
|
||||||
{"AgentToken", a.srv.AgentToken}, // See TestAgent_Token
|
{"AgentToken", a.srv.AgentToken}, // See TestAgent_Token
|
||||||
{"ACLRulesTranslate", a.srv.ACLRulesTranslate},
|
|
||||||
{"ACLPolicyList", a.srv.ACLPolicyList},
|
{"ACLPolicyList", a.srv.ACLPolicyList},
|
||||||
{"ACLPolicyCRUD", a.srv.ACLPolicyCRUD},
|
{"ACLPolicyCRUD", a.srv.ACLPolicyCRUD},
|
||||||
{"ACLPolicyCreate", a.srv.ACLPolicyCreate},
|
{"ACLPolicyCreate", a.srv.ACLPolicyCreate},
|
||||||
|
|
|
||||||
|
|
@ -30,10 +30,6 @@ var ACLCounters = []prometheus.CounterDefinition{
|
||||||
}
|
}
|
||||||
|
|
||||||
var ACLSummaries = []prometheus.SummaryDefinition{
|
var ACLSummaries = []prometheus.SummaryDefinition{
|
||||||
{
|
|
||||||
Name: []string{"acl", "resolveTokenLegacy"},
|
|
||||||
Help: "This measures the time it takes to resolve an ACL token using the legacy ACL system.",
|
|
||||||
},
|
|
||||||
{
|
{
|
||||||
Name: []string{"acl", "ResolveToken"},
|
Name: []string{"acl", "ResolveToken"},
|
||||||
Help: "This measures the time it takes to resolve an ACL token.",
|
Help: "This measures the time it takes to resolve an ACL token.",
|
||||||
|
|
|
||||||
|
|
@ -19,8 +19,6 @@ func init() {
|
||||||
registerEndpoint("/v1/acl/auth-methods", []string{"GET"}, (*HTTPHandlers).ACLAuthMethodList)
|
registerEndpoint("/v1/acl/auth-methods", []string{"GET"}, (*HTTPHandlers).ACLAuthMethodList)
|
||||||
registerEndpoint("/v1/acl/auth-method", []string{"PUT"}, (*HTTPHandlers).ACLAuthMethodCreate)
|
registerEndpoint("/v1/acl/auth-method", []string{"PUT"}, (*HTTPHandlers).ACLAuthMethodCreate)
|
||||||
registerEndpoint("/v1/acl/auth-method/", []string{"GET", "PUT", "DELETE"}, (*HTTPHandlers).ACLAuthMethodCRUD)
|
registerEndpoint("/v1/acl/auth-method/", []string{"GET", "PUT", "DELETE"}, (*HTTPHandlers).ACLAuthMethodCRUD)
|
||||||
registerEndpoint("/v1/acl/rules/translate", []string{"POST"}, (*HTTPHandlers).ACLRulesTranslate)
|
|
||||||
registerEndpoint("/v1/acl/rules/translate/", []string{"GET"}, (*HTTPHandlers).ACLLegacy)
|
|
||||||
registerEndpoint("/v1/acl/tokens", []string{"GET"}, (*HTTPHandlers).ACLTokenList)
|
registerEndpoint("/v1/acl/tokens", []string{"GET"}, (*HTTPHandlers).ACLTokenList)
|
||||||
registerEndpoint("/v1/acl/token", []string{"PUT"}, (*HTTPHandlers).ACLTokenCreate)
|
registerEndpoint("/v1/acl/token", []string{"PUT"}, (*HTTPHandlers).ACLTokenCreate)
|
||||||
registerEndpoint("/v1/acl/token/self", []string{"GET"}, (*HTTPHandlers).ACLTokenSelf)
|
registerEndpoint("/v1/acl/token/self", []string{"GET"}, (*HTTPHandlers).ACLTokenSelf)
|
||||||
|
|
@ -126,4 +124,6 @@ func init() {
|
||||||
registerEndpoint("/v1/acl/info/", []string{"GET"}, (*HTTPHandlers).ACLLegacy)
|
registerEndpoint("/v1/acl/info/", []string{"GET"}, (*HTTPHandlers).ACLLegacy)
|
||||||
registerEndpoint("/v1/acl/clone/", []string{"PUT"}, (*HTTPHandlers).ACLLegacy)
|
registerEndpoint("/v1/acl/clone/", []string{"PUT"}, (*HTTPHandlers).ACLLegacy)
|
||||||
registerEndpoint("/v1/acl/list", []string{"GET"}, (*HTTPHandlers).ACLLegacy)
|
registerEndpoint("/v1/acl/list", []string{"GET"}, (*HTTPHandlers).ACLLegacy)
|
||||||
|
registerEndpoint("/v1/acl/rules/translate", []string{"POST"}, (*HTTPHandlers).ACLLegacy)
|
||||||
|
registerEndpoint("/v1/acl/rules/translate/", []string{"GET"}, (*HTTPHandlers).ACLLegacy)
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,6 @@
|
||||||
package api
|
package api
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"strings"
|
|
||||||
"testing"
|
"testing"
|
||||||
"time"
|
"time"
|
||||||
|
|
||||||
|
|
@ -629,73 +628,3 @@ SxTJANJHqf4BiFtVjN7LZXi3HUIRAsceEbd0TfW5be9SQ0tbDyyGYt/bXtBLGTIh
|
||||||
}
|
}
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestAPI_RulesTranslate_Raw(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
c, s := makeACLClient(t)
|
|
||||||
defer s.Stop()
|
|
||||||
|
|
||||||
acl := c.ACL()
|
|
||||||
|
|
||||||
input := `#start of policy
|
|
||||||
agent "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
node "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
service "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
key "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
session "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
event "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
query "" {
|
|
||||||
policy = "read"
|
|
||||||
}`
|
|
||||||
|
|
||||||
expected := `#start of policy
|
|
||||||
agent_prefix "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
node_prefix "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
service_prefix "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
key_prefix "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
session_prefix "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
event_prefix "" {
|
|
||||||
policy = "read"
|
|
||||||
}
|
|
||||||
|
|
||||||
query_prefix "" {
|
|
||||||
policy = "read"
|
|
||||||
}`
|
|
||||||
|
|
||||||
rules, err := acl.RulesTranslate(strings.NewReader(input))
|
|
||||||
require.NoError(t, err)
|
|
||||||
require.Equal(t, expected, rules)
|
|
||||||
}
|
|
||||||
|
|
|
||||||
|
|
@ -1,421 +0,0 @@
|
||||||
---
|
|
||||||
layout: api
|
|
||||||
page_title: Legacy ACLs - HTTP API
|
|
||||||
description: >-
|
|
||||||
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in
|
|
||||||
Consul.
|
|
||||||
---
|
|
||||||
|
|
||||||
-> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_
|
|
||||||
recommended you do not build anything using the legacy system and consider using
|
|
||||||
the new ACL [Token](/docs/api/acl-token) and [Policy](/docs/api/acl-policy) APIs instead.
|
|
||||||
|
|
||||||
# ACL HTTP API
|
|
||||||
|
|
||||||
These `/acl` endpoints create, update, destroy, and query ACL tokens in Consul. For more information about ACLs, please check the
|
|
||||||
[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/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_master_token`](/docs/agent/options#acl_master_token)
|
|
||||||
is not specified in the Consul server configuration, and if the cluster has not been
|
|
||||||
bootstrapped previously. This is available in Consul 0.9.1 and later, and requires all
|
|
||||||
Consul servers to be upgraded in order to operate.
|
|
||||||
|
|
||||||
This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's
|
|
||||||
configuration files.
|
|
||||||
|
|
||||||
| Method | Path | Produces |
|
|
||||||
| ------ | ---------------- | ------------------ |
|
|
||||||
| `PUT` | `/acl/bootstrap` | `application/json` |
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
|
||||||
[blocking queries](/api/features/blocking),
|
|
||||||
[consistency modes](/api/features/consistency),
|
|
||||||
[agent caching](/api/features/caching), and
|
|
||||||
[required ACLs](/api#authentication).
|
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
|
||||||
| `NO` | `none` | `none` | `none` |
|
|
||||||
|
|
||||||
### Sample Request
|
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ curl \
|
|
||||||
--request PUT \
|
|
||||||
http://127.0.0.1:8500/v1/acl/bootstrap
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Response
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
You can detect if something has interfered with the ACL bootstrapping process by
|
|
||||||
checking the response code. A 200 response means that the bootstrap was a success, and
|
|
||||||
a 403 means that the cluster has already been bootstrapped, at which point you should
|
|
||||||
consider the cluster in a potentially compromised state.
|
|
||||||
|
|
||||||
The returned token will be a management token which can be used to further configure the
|
|
||||||
ACL system. Please check the
|
|
||||||
[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more details.
|
|
||||||
|
|
||||||
## Create ACL Token
|
|
||||||
|
|
||||||
This endpoint makes a new ACL token.
|
|
||||||
|
|
||||||
| Method | Path | Produces |
|
|
||||||
| ------ | ------------- | ------------------ |
|
|
||||||
| `PUT` | `/acl/create` | `application/json` |
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
|
||||||
[blocking queries](/api/features/blocking),
|
|
||||||
[consistency modes](/api/features/consistency),
|
|
||||||
[agent caching](/api/features/caching), and
|
|
||||||
[required ACLs](/api#authentication).
|
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
|
||||||
| `NO` | `none` | `none` | `management` |
|
|
||||||
|
|
||||||
### Parameters
|
|
||||||
|
|
||||||
- `ID` `(string: "")` - Specifies the ID of the ACL. If not provided, a UUID is
|
|
||||||
generated.
|
|
||||||
|
|
||||||
- `Name` `(string: "")` - Specifies a human-friendly name for the ACL token.
|
|
||||||
|
|
||||||
- `Type` `(string: "client")` - Specifies the type of ACL token. Valid values
|
|
||||||
are: `client` and `management`.
|
|
||||||
|
|
||||||
- `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the
|
|
||||||
`Rules` property is documented in the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
||||||
|
|
||||||
### Sample Payload
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"Name": "my-app-token",
|
|
||||||
"Type": "client",
|
|
||||||
"Rules": ""
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Request
|
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ curl \
|
|
||||||
--request PUT \
|
|
||||||
--data @payload.json \
|
|
||||||
http://127.0.0.1:8500/v1/acl/create
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Response
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Update ACL Token
|
|
||||||
|
|
||||||
This endpoint is used to modify the policy for a given ACL token. Instead of
|
|
||||||
generating a new token ID, the `ID` field must be provided.
|
|
||||||
|
|
||||||
| Method | Path | Produces |
|
|
||||||
| ------ | ------------- | ------------------ |
|
|
||||||
| `PUT` | `/acl/update` | `application/json` |
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
|
||||||
[blocking queries](/api/features/blocking),
|
|
||||||
[consistency modes](/api/features/consistency),
|
|
||||||
[agent caching](/api/features/caching), and
|
|
||||||
[required ACLs](/api#authentication).
|
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
|
||||||
| `NO` | `none` | `none` | `management` |
|
|
||||||
|
|
||||||
### Parameters
|
|
||||||
|
|
||||||
The parameters are the same as the _create_ endpoint, except the `ID` field is
|
|
||||||
required.
|
|
||||||
|
|
||||||
### Sample Payload
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
|
|
||||||
"Name": "my-app-token-updated",
|
|
||||||
"Type": "client",
|
|
||||||
"Rules": "# New Rules"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Request
|
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ curl \
|
|
||||||
--request PUT \
|
|
||||||
--data @payload.json \
|
|
||||||
http://127.0.0.1:8500/v1/acl/update
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Response
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Delete ACL Token
|
|
||||||
|
|
||||||
This endpoint deletes an ACL token with the given ID.
|
|
||||||
|
|
||||||
| Method | Path | Produces |
|
|
||||||
| ------ | -------------------- | ------------------ |
|
|
||||||
| `PUT` | `/acl/destroy/:uuid` | `application/json` |
|
|
||||||
|
|
||||||
Even though the return type is application/json, the value is either true or false, indicating whether the delete succeeded.
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
|
||||||
[blocking queries](/api/features/blocking),
|
|
||||||
[consistency modes](/api/features/consistency),
|
|
||||||
[agent caching](/api/features/caching), and
|
|
||||||
[required ACLs](/api#authentication).
|
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
|
||||||
| `NO` | `none` | `none` | `management` |
|
|
||||||
|
|
||||||
### Parameters
|
|
||||||
|
|
||||||
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
|
|
||||||
destroy. This is required and is specified as part of the URL path.
|
|
||||||
|
|
||||||
### Sample Request
|
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ curl \
|
|
||||||
--request PUT \
|
|
||||||
http://127.0.0.1:8500/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Response
|
|
||||||
|
|
||||||
```text
|
|
||||||
true
|
|
||||||
```
|
|
||||||
|
|
||||||
## Read ACL Token
|
|
||||||
|
|
||||||
This endpoint reads an ACL token with the given ID.
|
|
||||||
|
|
||||||
| Method | Path | Produces |
|
|
||||||
| ------ | ----------------- | ------------------ |
|
|
||||||
| `GET` | `/acl/info/:uuid` | `application/json` |
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
|
||||||
[blocking queries](/api/features/blocking),
|
|
||||||
[consistency modes](/api/features/consistency),
|
|
||||||
[agent caching](/api/features/caching), and
|
|
||||||
[required ACLs](/api#authentication).
|
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
|
||||||
| `YES` | `all` | `none` | `none` |
|
|
||||||
|
|
||||||
Note: No ACL is required because the ACL is specified in the URL path.
|
|
||||||
|
|
||||||
### Parameters
|
|
||||||
|
|
||||||
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
|
|
||||||
read. This is required and is specified as part of the URL path.
|
|
||||||
|
|
||||||
### Sample Request
|
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ curl \
|
|
||||||
http://127.0.0.1:8500/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Response
|
|
||||||
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"CreateIndex": 3,
|
|
||||||
"ModifyIndex": 3,
|
|
||||||
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
|
|
||||||
"Name": "Client Token",
|
|
||||||
"Type": "client",
|
|
||||||
"Rules": "..."
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Clone ACL Token
|
|
||||||
|
|
||||||
This endpoint clones an ACL and returns a new token `ID`. This allows a token to
|
|
||||||
serve as a template for others, making it simple to generate new tokens without
|
|
||||||
complex rule management.
|
|
||||||
|
|
||||||
| Method | Path | Produces |
|
|
||||||
| ------ | ------------------ | ------------------ |
|
|
||||||
| `PUT` | `/acl/clone/:uuid` | `application/json` |
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
|
||||||
[blocking queries](/api/features/blocking),
|
|
||||||
[consistency modes](/api/features/consistency),
|
|
||||||
[agent caching](/api/features/caching), and
|
|
||||||
[required ACLs](/api#authentication).
|
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
|
||||||
| `NO` | `none` | `none` | `management` |
|
|
||||||
|
|
||||||
### Parameters
|
|
||||||
|
|
||||||
- `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to
|
|
||||||
be cloned. This is required and is specified as part of the URL path.
|
|
||||||
|
|
||||||
### Sample Request
|
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ curl \
|
|
||||||
--request PUT \
|
|
||||||
http://127.0.0.1:8500/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Response
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## List ACLs
|
|
||||||
|
|
||||||
This endpoint lists all the active ACL tokens.
|
|
||||||
|
|
||||||
| Method | Path | Produces |
|
|
||||||
| ------ | ----------- | ------------------ |
|
|
||||||
| `GET` | `/acl/list` | `application/json` |
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
|
||||||
[blocking queries](/api/features/blocking),
|
|
||||||
[consistency modes](/api/features/consistency),
|
|
||||||
[agent caching](/api/features/caching), and
|
|
||||||
[required ACLs](/api#authentication).
|
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
|
||||||
| `YES` | `all` | `none` | `management` |
|
|
||||||
|
|
||||||
### Sample Request
|
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ curl \
|
|
||||||
http://127.0.0.1:8500/v1/acl/list
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Response
|
|
||||||
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"CreateIndex": 3,
|
|
||||||
"ModifyIndex": 3,
|
|
||||||
"ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
|
|
||||||
"Name": "Client Token",
|
|
||||||
"Type": "client",
|
|
||||||
"Rules": "..."
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Check ACL Replication
|
|
||||||
|
|
||||||
This endpoint returns the status of the ACL replication process in the
|
|
||||||
datacenter. This is intended to be used by operators, or by automation checking
|
|
||||||
the health of ACL replication.
|
|
||||||
|
|
||||||
Please check the [ACL Replication tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters)
|
|
||||||
for more details.
|
|
||||||
|
|
||||||
| Method | Path | Produces |
|
|
||||||
| ------ | ------------------ | ------------------ |
|
|
||||||
| `GET` | `/acl/replication` | `application/json` |
|
|
||||||
|
|
||||||
The table below shows this endpoint's support for
|
|
||||||
[blocking queries](/api/features/blocking),
|
|
||||||
[consistency modes](/api/features/consistency),
|
|
||||||
[agent caching](/api/features/caching), and
|
|
||||||
[required ACLs](/api#authentication).
|
|
||||||
|
|
||||||
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
||||||
| ---------------- | ----------------- | ------------- | ------------ |
|
|
||||||
| `NO` | `consistent` | `none` | `none` |
|
|
||||||
|
|
||||||
### Parameters
|
|
||||||
|
|
||||||
- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
|
|
||||||
the datacenter of the agent being queried. This is specified as part of the
|
|
||||||
URL as a query parameter.
|
|
||||||
|
|
||||||
### Sample Request
|
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ curl \
|
|
||||||
http://127.0.0.1:8500/v1/acl/replication
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sample Response
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"Enabled": true,
|
|
||||||
"Running": true,
|
|
||||||
"SourceDatacenter": "dc1",
|
|
||||||
"ReplicatedIndex": 1976,
|
|
||||||
"LastSuccess": "2016-08-05T06:28:58Z",
|
|
||||||
"LastError": "2016-08-05T06:28:28Z"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- `Enabled` reports whether ACL replication is enabled for the datacenter.
|
|
||||||
|
|
||||||
- `Running` reports whether the ACL replication process is running. The process
|
|
||||||
may take approximately 60 seconds to begin running after a leader election
|
|
||||||
occurs.
|
|
||||||
|
|
||||||
- `SourceDatacenter` is the authoritative ACL datacenter that ACLs are being
|
|
||||||
replicated from, and will match the
|
|
||||||
[`primary_datacenter`](/docs/agent/options#primary_datacenter) configuration.
|
|
||||||
|
|
||||||
- `ReplicatedIndex` is the last index that was successfully replicated. You can
|
|
||||||
compare this to the `X-Consul-Index` header returned by the
|
|
||||||
[`/v1/acl/list`](#list-acls) endpoint to determine if the replication process
|
|
||||||
has gotten all available ACLs. Replication runs as a background process
|
|
||||||
approximately every 30 seconds, and that local updates are rate limited to 100
|
|
||||||
updates/second, so so it may take several minutes to perform the initial sync
|
|
||||||
of a large set of ACLs. After the initial sync, replica lag should be on the
|
|
||||||
order of about 30 seconds.
|
|
||||||
|
|
||||||
- `LastSuccess` is the UTC time of the last successful sync operation. Since ACL
|
|
||||||
replication is done with a blocking query, this may not update for up to 5
|
|
||||||
minutes if there have been no ACL changes to replicate. A zero value of
|
|
||||||
"0001-01-01T00:00:00Z" will be present if no sync has been successful.
|
|
||||||
|
|
||||||
- `LastError` is the UTC time of the last error encountered during a sync
|
|
||||||
operation. If this time is later than `LastSuccess`, you can assume the
|
|
||||||
replication process is not in a good state. A zero value of
|
|
||||||
"0001-01-01T00:00:00Z" will be present if no sync has resulted in an error.
|
|
||||||
|
|
@ -144,7 +144,7 @@ $ curl \
|
||||||
|
|
||||||
- `ReplicationType` - The type of replication that is currently in use.
|
- `ReplicationType` - The type of replication that is currently in use.
|
||||||
|
|
||||||
- `legacy` - ACL replication is in legacy mode and is replicating legacy ACL tokens.
|
- `legacy` - (removed in Consul 1.11.0) ACL replication is in legacy mode and is replicating legacy ACL tokens.
|
||||||
|
|
||||||
- `policies` - ACL replication is only replicating policies as token replication
|
- `policies` - ACL replication is only replicating policies as token replication
|
||||||
is disabled.
|
is disabled.
|
||||||
|
|
@ -181,8 +181,8 @@ $ curl \
|
||||||
|
|
||||||
## Translate Rules
|
## Translate Rules
|
||||||
|
|
||||||
-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system. It
|
-> **Deprecated** - This endpoint was removed in Consul 1.11.0.
|
||||||
will be removed in a future major Consul version when support for legacy ACLs is removed.
|
This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.
|
||||||
|
|
||||||
This endpoint translates the legacy rule syntax into the latest syntax. It is intended
|
This endpoint translates the legacy rule syntax into the latest syntax. It is intended
|
||||||
to be used by operators managing Consul's ACLs and performing legacy token to new policy
|
to be used by operators managing Consul's ACLs and performing legacy token to new policy
|
||||||
|
|
@ -226,8 +226,8 @@ agent_prefix "" {
|
||||||
|
|
||||||
## Translate a Legacy Token's Rules
|
## Translate a Legacy Token's Rules
|
||||||
|
|
||||||
-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.. It
|
-> **Deprecated** - This endpoint was removed in Consul 1.11.0.
|
||||||
will be removed in a future major Consul version when support for legacy ACLs is removed.
|
This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.
|
||||||
|
|
||||||
This endpoint translates the legacy rules embedded within a legacy ACL into the latest
|
This endpoint translates the legacy rules embedded within a legacy ACL into the latest
|
||||||
syntax. It is intended to be used by operators managing Consul's ACLs and performing
|
syntax. It is intended to be used by operators managing Consul's ACLs and performing
|
||||||
|
|
|
||||||
|
|
@ -2,17 +2,17 @@
|
||||||
layout: api
|
layout: api
|
||||||
page_title: Legacy ACLs - HTTP API
|
page_title: Legacy ACLs - HTTP API
|
||||||
description: >-
|
description: >-
|
||||||
The /acl endpoints create, update, destroy, and query Legacy ACL tokens in
|
The legacy /acl endpoints to create, update, destroy, and query legacy ACL tokens in
|
||||||
Consul.
|
Consul.
|
||||||
---
|
---
|
||||||
|
|
||||||
# ACL HTTP API
|
# ACL HTTP API
|
||||||
|
|
||||||
-> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_
|
-> **The legacy ACL system was deprecated in Consul 1.4.0 and removed in Consul 1.11.0.** It's _strongly_
|
||||||
recommended you do not build anything using the legacy system and consider using
|
recommended you do not build anything using the legacy system and use
|
||||||
the new ACL [Token](/api/acl/tokens) and [Policy](/api/acl/policies) APIs instead.
|
the new ACL [Token](/api/acl/tokens) and [Policy](/api/acl/policies) APIs instead.
|
||||||
|
|
||||||
The `/acl` endpoints create, update, destroy, and query ACL tokens in Consul.
|
The legacy `/acl` endpoints to create, update, destroy, and query legacy ACL tokens in Consul.
|
||||||
|
|
||||||
For more information about ACLs, please check the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
For more information about ACLs, please check the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -331,7 +331,6 @@ These metrics are used to monitor the health of the Consul servers.
|
||||||
|
|
||||||
| Metric | Description | Unit | Type |
|
| Metric | Description | Unit | Type |
|
||||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
|
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- |
|
||||||
| `consul.acl.resolveTokenLegacy` | Measures the time it takes to resolve an ACL token using the legacy ACL system. | ms | timer |
|
|
||||||
| `consul.acl.ResolveToken` | Measures the time it takes to resolve an ACL token. | ms | timer |
|
| `consul.acl.ResolveToken` | Measures the time it takes to resolve an ACL token. | ms | timer |
|
||||||
| `consul.acl.ResolveTokenToIdentity` | Measures the time it takes to resolve an ACL token to an Identity. | ms | timer |
|
| `consul.acl.ResolveTokenToIdentity` | Measures the time it takes to resolve an ACL token to an Identity. | ms | timer |
|
||||||
| `consul.acl.token.cache_hit` | Increments if Consul is able to resolve a token's identity, or a legacy token, from the cache. | cache read op | counter |
|
| `consul.acl.token.cache_hit` | Increments if Consul is able to resolve a token's identity, or a legacy token, from the cache. | cache read op | counter |
|
||||||
|
|
|
||||||
|
|
@ -13,8 +13,9 @@ description: >-
|
||||||
-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system).
|
-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/acl/acl-system).
|
||||||
|
|
||||||
~> **Alert: Deprecation Notice**
|
~> **Alert: Deprecation Notice**
|
||||||
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
|
The ACL system described here was Consul's original ACL implementation.
|
||||||
the ACL system was rewritten and the legacy system was deprecated. The new ACL system information can be found [here](/docs/acl/acl-system). For information on how to migrate to the new ACL System, please read the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/tutorials/consul/access-control-token-migration) tutorial.
|
The legacy ACL system was deprecated in Consul 1.4.0 and removed in Consul 1.11.0.
|
||||||
|
The documentation for the new ACL system can be found [here](/docs/acl/acl-system). For information on how to migrate to the new ACL System, please read the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/tutorials/consul/access-control-token-migration) tutorial.
|
||||||
|
|
||||||
The legacy documentation has two sections.
|
The legacy documentation has two sections.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -56,6 +56,11 @@ module.exports = [
|
||||||
destination: '/docs/security/acl/acl-legacy',
|
destination: '/docs/security/acl/acl-legacy',
|
||||||
permanent: true,
|
permanent: true,
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
source: '/api-docs/acl-legacy',
|
||||||
|
destination: '/api-docs/acl/legacy',
|
||||||
|
permanent: true,
|
||||||
|
},
|
||||||
{
|
{
|
||||||
source: '/docs/guides/acl-migrate-tokens',
|
source: '/docs/guides/acl-migrate-tokens',
|
||||||
destination: '/docs/security/acl/acl-migrate-tokens',
|
destination: '/docs/security/acl/acl-migrate-tokens',
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue