Skip to content

feat: consul migration #1228

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 4, 2025
Merged

feat: consul migration #1228

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
The diff you're trying to view is too large. We only load the first 3000 changed files.
425 changes: 425 additions & 0 deletions content/consul/v1.10.x/content/api-docs/acl/auth-methods.mdx
View file
Open in desktop

Large diffs are not rendered by default.

425 changes: 425 additions & 0 deletions content/consul/v1.10.x/content/api-docs/acl/binding-rules.mdx
View file
Open in desktop

Large diffs are not rendered by default.

569 changes: 569 additions & 0 deletions content/consul/v1.10.x/content/api-docs/acl/index.mdx
View file
Open in desktop

Large diffs are not rendered by default.

299 changes: 299 additions & 0 deletions content/consul/v1.10.x/content/api-docs/acl/legacy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,299 @@
---
layout: api
page_title: Legacy ACLs - HTTP API
description: >-
The /acl endpoints 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 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.

For more information about ACLs, please check the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).

## 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 detailed in the [ACL Rule documentation](/docs/acl/acl-rules).

### 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

```json
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

The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api/acl/acl#check-acl-replication) to learn more about this endpoint.
Loading
Loading