luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

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 2021-10-25 18:38:00 -04:00 committed by GitHub
parent e184ccc8e0 bec7664b2f
commit f24bad2a52
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 22 additions and 543 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.changelog/11232.txt Normal file
View File

@ -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.
```

32
agent/acl_endpoint.go
View File

@ -2,7 +2,6 @@ package agent
import (
"fmt"
"io/ioutil"
"net/http"
"strings"
@ -74,37 +73,6 @@ func (s *HTTPHandlers) ACLReplicationStatus(resp http.ResponseWriter, req *http.
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) {
if s.checkACLDisabled(resp, req) {
return nil, nil

1
agent/acl_endpoint_test.go
View File

@ -45,7 +45,6 @@ func TestACL_Disabled_Response(t *testing.T) {
{"ACLBootstrap", a.srv.ACLBootstrap},
{"ACLReplicationStatus", a.srv.ACLReplicationStatus},
{"AgentToken", a.srv.AgentToken}, // See TestAgent_Token
{"ACLRulesTranslate", a.srv.ACLRulesTranslate},
{"ACLPolicyList", a.srv.ACLPolicyList},
{"ACLPolicyCRUD", a.srv.ACLPolicyCRUD},
{"ACLPolicyCreate", a.srv.ACLPolicyCreate},

4
agent/consul/acl.go
View File

@ -30,10 +30,6 @@ var ACLCounters = []prometheus.CounterDefinition{
}
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"},
Help: "This measures the time it takes to resolve an ACL token.",

4
agent/http_register.go
View File

@ -19,8 +19,6 @@ func init() {
registerEndpoint("/v1/acl/auth-methods", []string{"GET"}, (*HTTPHandlers).ACLAuthMethodList)
registerEndpoint("/v1/acl/auth-method", []string{"PUT"}, (*HTTPHandlers).ACLAuthMethodCreate)
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/token", []string{"PUT"}, (*HTTPHandlers).ACLTokenCreate)
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/clone/", []string{"PUT"}, (*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)
}

71
api/acl_test.go
View File

@ -1,7 +1,6 @@
package api
import (
"strings"
"testing"
"time"
@ -629,73 +628,3 @@ SxTJANJHqf4BiFtVjN7LZXi3HUIRAsceEbd0TfW5be9SQ0tbDyyGYt/bXtBLGTIh
}
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)
}

421
website/content/api-docs/acl-legacy.mdx
View File

@ -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.

10
website/content/api-docs/acl/index.mdx
View File

@ -144,7 +144,7 @@ $ curl \
- `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
is disabled.
@ -181,8 +181,8 @@ $ curl \
## Translate Rules
-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system. It
will be removed in a future major Consul version when support for legacy ACLs is removed.
-> **Deprecated** - This endpoint was removed in Consul 1.11.0.
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
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
-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.. It
will be removed in a future major Consul version when support for legacy ACLs is removed.
-> **Deprecated** - This endpoint was removed in Consul 1.11.0.
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
syntax. It is intended to be used by operators managing Consul's ACLs and performing

8
website/content/api-docs/acl/legacy.mdx
View File

@ -2,17 +2,17 @@
layout: api
page_title: Legacy ACLs - HTTP API
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.
---
# ACL HTTP API
-> **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 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 use
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).

1
website/content/docs/agent/telemetry.mdx
View File

@ -331,7 +331,6 @@ These metrics are used to monitor the health of the Consul servers.
| 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.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 |

5
website/content/docs/security/acl/acl-legacy.mdx
View File

@ -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).
~> **Alert: Deprecation Notice**
The ACL system described here was Consul's original ACL implementation. In Consul 1.4.0
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 ACL system described here was Consul's original ACL implementation.
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.

5
website/redirects.next.js
View File

@ -56,6 +56,11 @@ module.exports = [
destination: '/docs/security/acl/acl-legacy',
permanent: true,
},
{
source: '/api-docs/acl-legacy',
destination: '/api-docs/acl/legacy',
permanent: true,
},
{
source: '/docs/guides/acl-migrate-tokens',
destination: '/docs/security/acl/acl-migrate-tokens',