diff --git a/website/content/api-docs/acl-legacy.mdx b/website/content/api-docs/acl-legacy.mdx deleted file mode 100644 index 678b60ce3..000000000 --- a/website/content/api-docs/acl-legacy.mdx +++ /dev/null @@ -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: )` - 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: )` - 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: )` - 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. diff --git a/website/redirects.next.js b/website/redirects.next.js index 1300162fb..e3db27ff7 100644 --- a/website/redirects.next.js +++ b/website/redirects.next.js @@ -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',