status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: add documentation for all secure acl introduction work (#5640)

This commit is contained in:
R.B. Boyer 2019-05-01 16:11:23 -05:00 committed by GitHub
parent e31c285565
commit c649243f7c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
96 changed files with 4240 additions and 963 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
command/acl/acl.go
View File

@ -35,11 +35,11 @@ Usage: consul acl <subcommand> [options] [args]
$ consul acl bootstrap
List all ACL Tokens:
List all ACL tokens:
$ consul acl token list
Create a new ACL Policy:
Create a new ACL policy:
$ consul acl policy create -name "new-policy" \
-description "This is an example policy" \

4
command/acl/authmethod/authmethod.go
View File

@ -23,11 +23,11 @@ func (c *cmd) Help() string {
return flags.Usage(help, nil)
}
const synopsis = "Manage Consul's ACL Auth Methods"
const synopsis = "Manage Consul's ACL auth methods"
const help = `
Usage: consul acl auth-method <subcommand> [options] [args]
This command has subcommands for managing Consul's ACL Auth Methods.
This command has subcommands for managing Consul's ACL auth methods.
Here are some simple examples, and more detailed examples are available in
the subcommands or the documentation.

6
command/acl/authmethod/create/authmethod_create.go
View File

@ -45,7 +45,7 @@ func (c *cmd) init() {
"meta",
false,
"Indicates that auth method metadata such "+
"as the content hash and raft indices should be shown for each entry.",
"as the raft indices should be shown for each entry.",
)
c.flags.StringVar(
@ -86,7 +86,7 @@ func (c *cmd) init() {
&c.k8sServiceAccountJWT,
"kubernetes-service-account-jwt",
"",
"A kubernetes service account JWT used to access the TokenReview API to "+
"A Kubernetes service account JWT used to access the TokenReview API to "+
"validate other JWTs during login. "+
"This flag is required for type=kubernetes.",
)
@ -170,7 +170,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Create an ACL Auth Method"
const synopsis = "Create an ACL auth method"
const help = `
Usage: consul acl auth-method create -name NAME -type TYPE [options]

2
command/acl/authmethod/delete/authmethod_delete.go
View File

@ -72,7 +72,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Delete an ACL Auth Method"
const synopsis = "Delete an ACL auth method"
const help = `
Usage: consul acl auth-method delete -name NAME [options]

4
command/acl/authmethod/list/authmethod_list.go
View File

@ -32,7 +32,7 @@ func (c *cmd) init() {
"meta",
false,
"Indicates that auth method metadata such "+
"as the content hash and raft indices should be shown for each entry.",
"as the raft indices should be shown for each entry.",
)
c.http = &flags.HTTPFlags{}
@ -73,7 +73,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Lists ACL Auth Methods"
const synopsis = "Lists ACL auth methods"
const help = `
Usage: consul acl auth-method list [options]

4
command/acl/authmethod/read/authmethod_read.go
View File

@ -34,7 +34,7 @@ func (c *cmd) init() {
"meta",
false,
"Indicates that auth method metadata such "+
"as the content hash and raft indices should be shown for each entry.",
"as the raft indices should be shown for each entry.",
)
c.flags.StringVar(
@ -86,7 +86,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Read an ACL Auth Method"
const synopsis = "Read an ACL auth method"
const help = `
Usage: consul acl auth-method read -name NAME [options]

6
command/acl/authmethod/update/authmethod_update.go
View File

@ -46,7 +46,7 @@ func (c *cmd) init() {
"meta",
false,
"Indicates that auth method metadata such "+
"as the content hash and raft indices should be shown for each entry.",
"as the raft indices should be shown for each entry.",
)
c.flags.StringVar(
@ -82,7 +82,7 @@ func (c *cmd) init() {
&c.k8sServiceAccountJWT,
"kubernetes-service-account-jwt",
"",
"A kubernetes service account JWT used to access the TokenReview API to "+
"A Kubernetes service account JWT used to access the TokenReview API to "+
"validate other JWTs during login. "+
"This flag is required for type=kubernetes.",
)
@ -202,7 +202,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Update an ACL Auth Method"
const synopsis = "Update an ACL auth method"
const help = `
Usage: consul acl auth-method update -name NAME [options]

4
command/acl/bindingrule/bindingrule.go
View File

@ -23,11 +23,11 @@ func (c *cmd) Help() string {
return flags.Usage(help, nil)
}
const synopsis = "Manage Consul's ACL Binding Rules"
const synopsis = "Manage Consul's ACL binding rules"
const help = `
Usage: consul acl binding-rule <subcommand> [options] [args]
This command has subcommands for managing Consul's ACL Binding Rules. Here
This command has subcommands for managing Consul's ACL binding rules. Here
are some simple examples, and more detailed examples are available in the
subcommands or the documentation.

4
command/acl/bindingrule/create/bindingrule_create.go
View File

@ -39,7 +39,7 @@ func (c *cmd) init() {
"meta",
false,
"Indicates that binding rule metadata such "+
"as the content hash and raft indices should be shown for each entry.",
"as the raft indices should be shown for each entry.",
)
c.flags.StringVar(
@ -133,7 +133,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Create an ACL Binding Rule"
const synopsis = "Create an ACL binding rule"
const help = `
Usage: consul acl binding-rule create [options]

2
command/acl/bindingrule/delete/bindingrule_delete.go
View File

@ -81,7 +81,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Delete an ACL Binding Rule"
const synopsis = "Delete an ACL binding rule"
const help = `
Usage: consul acl binding-rule delete -id ID [options]

4
command/acl/bindingrule/list/bindingrule_list.go
View File

@ -34,7 +34,7 @@ func (c *cmd) init() {
"meta",
false,
"Indicates that binding rule metadata such "+
"as the content hash and raft indices should be shown for each entry.",
"as the raft indices should be shown for each entry.",
)
c.flags.StringVar(
@ -82,7 +82,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Lists ACL Binding Rules"
const synopsis = "Lists ACL binding rules"
const help = `
Usage: consul acl binding-rule list [options]

4
command/acl/bindingrule/read/bindingrule_read.go
View File

@ -34,7 +34,7 @@ func (c *cmd) init() {
"meta",
false,
"Indicates that binding rule metadata such "+
"as the content hash and raft indices should be shown for each entry.",
"as the raft indices should be shown for each entry.",
)
c.flags.StringVar(
@ -95,7 +95,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Read an ACL Binding Rule"
const synopsis = "Read an ACL binding rule"
const help = `
Usage: consul acl binding-rule read -id ID [options]

4
command/acl/bindingrule/update/bindingrule_update.go
View File

@ -40,7 +40,7 @@ func (c *cmd) init() {
"meta",
false,
"Indicates that binding rule metadata such "+
"as the content hash and raft indices should be shown for each entry.",
"as the raft indices should be shown for each entry.",
)
c.flags.StringVar(
@ -193,7 +193,7 @@ func isFlagSet(flags *flag.FlagSet, name string) bool {
return found
}
const synopsis = "Update an ACL Binding Rule"
const synopsis = "Update an ACL binding rule"
const help = `
Usage: consul acl binding-rule update -id ID [options]

4
command/acl/policy/create/policy_create.go
View File

@ -131,7 +131,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Create an ACL Policy"
const synopsis = "Create an ACL policy"
const help = `
Usage: consul acl policy create -name NAME [options]
@ -151,6 +151,6 @@ Usage: consul acl policy create -name NAME [options]
Creation a policy from a legacy token:
$ consul acl policy create -name "legacy-policy" \
-description "Token Converted to Policy" \
-description "Token Converted to policy" \
-from-token "c1e34113-e7ab-4451-b1a6-336ddcc58fc6"
`

2
command/acl/policy/delete/policy_delete.go
View File

@ -81,7 +81,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Delete an ACL Policy"
const synopsis = "Delete an ACL policy"
const help = `
Usage: consul acl policy delete [options] -id POLICY

2
command/acl/policy/list/policy_list.go
View File

@ -67,7 +67,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Lists ACL Policies"
const synopsis = "Lists ACL policies"
const help = `
Usage: consul acl policy list [options]

6
command/acl/policy/policy.go
View File

@ -23,15 +23,15 @@ func (c *cmd) Help() string {
return flags.Usage(help, nil)
}
const synopsis = "Manage Consul's ACL Policies"
const synopsis = "Manage Consul's ACL policies"
const help = `
Usage: consul acl policy <subcommand> [options] [args]
This command has subcommands for managing Consul's ACL Policies.
This command has subcommands for managing Consul's ACL policies.
Here are some simple examples, and more detailed examples are available
in the subcommands or the documentation.
Create a new ACL Policy:
Create a new ACL policy:
$ consul acl policy create -name "new-policy" \
-description "This is an example policy" \

2
command/acl/policy/read/policy_read.go
View File

@ -84,7 +84,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Read an ACL Policy"
const synopsis = "Read an ACL policy"
const help = `
Usage: consul acl policy read [options] POLICY

4
command/acl/policy/update/policy_update.go
View File

@ -159,7 +159,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Update an ACL Policy"
const synopsis = "Update an ACL policy"
const help = `
Usage: consul acl policy update [options]
@ -167,7 +167,7 @@ Usage: consul acl policy update [options]
current state so that you do not have to provide all parameters. This
behavior can be disabled by passing -no-merge.
Rename the Policy:
Rename the policy:
$ consul acl policy update -id abcd -name "better-name"

2
command/acl/role/create/role_create.go
View File

@ -118,7 +118,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Create an ACL Role"
const synopsis = "Create an ACL role"
const help = `
Usage: consul acl role create -name NAME [options]

2
command/acl/role/delete/role_delete.go
View File

@ -81,7 +81,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Delete an ACL Role"
const synopsis = "Delete an ACL role"
const help = `
Usage: consul acl role delete [options] -id ROLE

2
command/acl/role/list/role_list.go
View File

@ -67,7 +67,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Lists ACL Roles"
const synopsis = "Lists ACL roles"
const help = `
Usage: consul acl role list [options]

2
command/acl/role/read/role_read.go
View File

@ -97,7 +97,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Read an ACL Role"
const synopsis = "Read an ACL role"
const help = `
Usage: consul acl role read [options] ROLE

6
command/acl/role/role.go
View File

@ -23,15 +23,15 @@ func (c *cmd) Help() string {
return flags.Usage(help, nil)
}
const synopsis = "Manage Consul's ACL Roles"
const synopsis = "Manage Consul's ACL roles"
const help = `
Usage: consul acl role <subcommand> [options] [args]
This command has subcommands for managing Consul's ACL Roles.
This command has subcommands for managing Consul's ACL roles.
Here are some simple examples, and more detailed examples are available
in the subcommands or the documentation.
Create a new ACL Role:
Create a new ACL role:
$ consul acl role create -name "new-role" \
-description "This is an example role" \

4
command/acl/role/update/role_update.go
View File

@ -203,7 +203,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Update an ACL Role"
const synopsis = "Update an ACL role"
const help = `
Usage: consul acl role update [options]
@ -211,7 +211,7 @@ Usage: consul acl role update [options]
current state so that you do not have to provide all parameters. This
behavior can be disabled by passing -no-merge.
Rename the Role:
Rename the role:
$ consul acl role update -id abcd -name "better-name"

2
command/acl/token/clone/token_clone.go
View File

@ -79,7 +79,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Clone an ACL Token"
const synopsis = "Clone an ACL token"
const help = `
Usage: consul acl token clone [options]

2
command/acl/token/create/token_create.go
View File

@ -148,7 +148,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Create an ACL Token"
const synopsis = "Create an ACL token"
const help = `
Usage: consul acl token create [options]

2
command/acl/token/delete/token_delete.go
View File

@ -75,7 +75,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Delete an ACL Token"
const synopsis = "Delete an ACL token"
const help = `
Usage: consul acl token delete [options] -id TOKEN

4
command/acl/token/list/token_list.go
View File

@ -72,11 +72,11 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "List ACL Tokens"
const synopsis = "List ACL tokens"
const help = `
Usage: consul acl token list [options]
List all the ALC tokens
List all the ACL tokens
$ consul acl token list
`

2
command/acl/token/read/token_read.go
View File

@ -91,7 +91,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Read an ACL Token"
const synopsis = "Read an ACL token"
const help = `
Usage: consul acl token read [options] -id TOKENID

4
command/acl/token/token.go
View File

@ -23,7 +23,7 @@ func (c *cmd) Help() string {
return flags.Usage(help, nil)
}
const synopsis = "Manage Consul's ACL Tokens"
const synopsis = "Manage Consul's ACL tokens"
const help = `
Usage: consul acl token <subcommand> [options] [args]
@ -31,7 +31,7 @@ Usage: consul acl token <subcommand> [options] [args]
Here are some simple examples, and more detailed examples are available
in the subcommands or the documentation.
Create a new ACL Token:
Create a new ACL token:
$ consul acl token create \
-description "This is an example token" \

2
command/acl/token/update/token_update.go
View File

@ -278,7 +278,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Update an ACL Token"
const synopsis = "Update an ACL token"
const help = `
Usage: consul acl token update [options]

4
command/login/login.go
View File

@ -136,13 +136,13 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Login to Consul using an Auth Method"
const synopsis = "Login to Consul using an auth method"
const help = `
Usage: consul login [options]
The login command will exchange the provided third party credentials with the
requested auth method for a newly minted Consul ACL Token. The companion
requested auth method for a newly minted Consul ACL token. The companion
command 'consul logout' should be used to destroy any tokens created this way
to avoid a resource leak.
`

2
command/logout/logout.go
View File

@ -60,7 +60,7 @@ func (c *cmd) Help() string {
return flags.Usage(c.help, nil)
}
const synopsis = "Destroy a Consul Token created with Login"
const synopsis = "Destroy a Consul token created with login"
const help = `
Usage: consul logout [options]

3
website/raw-assets/README Normal file
View File

@ -0,0 +1,3 @@
The files in this directory are source material for files in the source/assets directory.
Files that end in *.fig are usable in: https://www.figma.com

BIN
website/raw-assets/auth-methods.fig Normal file
View File

Binary file not shown.

16
website/source/api/acl-legacy.html.md
View File

@ -41,7 +41,7 @@ The table below shows this endpoint's support for
### Sample Request
```text
```sh
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/acl/bootstrap
@ -106,7 +106,7 @@ The table below shows this endpoint's support for
### Sample Request
```text
```sh
$ curl \
--request PUT \
--data @payload.json \
@ -158,7 +158,7 @@ required.
### Sample Request
```text
```sh
$ curl \
--request PUT \
--data @payload.json \
@ -200,7 +200,7 @@ The table below shows this endpoint's support for
### Sample Request
```text
```sh
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
@ -240,7 +240,7 @@ Note: No ACL is required because the ACL is specified in the URL path.
### Sample Request
```text
```sh
$ curl \
http://127.0.0.1:8500/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
@ -287,7 +287,7 @@ The table below shows this endpoint's support for
### Sample Request
```text
```sh
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
@ -321,7 +321,7 @@ The table below shows this endpoint's support for
### Sample Request
```text
```sh
$ curl \
http://127.0.0.1:8500/v1/acl/list
```
@ -372,7 +372,7 @@ The table below shows this endpoint's support for
### Sample Request
```text
```sh
$ curl \
http://127.0.0.1:8500/v1/acl/replication
```

112
website/source/api/acl/acl.html.md
View File

@ -12,7 +12,8 @@ description: |-
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api/acl/tokens.html) and [policies](/api/acl/policies.html) with the `/acl` endpoints.
For more information about ACLs, please see the [ACL Guide](/docs/guides/acl.html).
For more information on how to setup ACLs, please see
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
## Bootstrap ACLs
@ -263,3 +264,112 @@ agent_prefix "" {
policy = "read"
}
```
## Login to Auth Method
This endpoint was added in Consul 1.5.0 and is used to exchange an [auth
method](/docs/acl/acl-auth-methods.html) bearer token for a newly-created
Consul ACL token.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `POST` | `/acl/login` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `none` |
### Parameters
- `AuthMethod` `(string: <required>)` - The name of the auth method to use for login.
- `BearerToken` `(string: <required>)` - The bearer token to present to the
auth method during login for authentication purposes. For the Kubernetes auth
method this is a [Service Account Token
(JWT)](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens).
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
linked to the token. Can be useful to track origins.
### Sample Payload
```json
{
"AuthMethod": "minikube",
"BearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
}
```
### Sample Request
```sh
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/login
```
### Sample Response
```json
{
"AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b",
"SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586",
"Description": "token created via login",
"Roles": [
{
"ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7",
"Name": "demo"
}
],
"ServiceIdentities": [
{
"ServiceName": "example"
}
],
"Local": true,
"AuthMethod": "minikube",
"CreateTime": "2019-04-29T10:08:08.404370762-05:00",
"Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=",
"CreateIndex": 36,
"ModifyIndex": 36
}
```
## Logout from Auth Method
This endpoint was added in Consul 1.5.0 and is used to destroy a token created
via the [login endpoint](#login-to-auth-method). The token deleted is specified
with the `X-Consul-Token` header or the `token` query parameter.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `POST` | `/acl/logout` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `none` |
-> **Note** - This endpoint requires no specific privileges as it is just
deleting a token for which you already must possess its secret.
### Sample Request
```sh
$ curl \
-H "X-Consul-Token: b78d37c7-0ca7-5f4d-99ee-6d9975ce4586" \
--request POST \
http://127.0.0.1:8500/v1/acl/logout
```

310
website/source/api/acl/auth-methods.html.md Normal file
View File

@ -0,0 +1,310 @@
---
layout: api
page_title: ACL Auth Methods - HTTP API
sidebar_current: api-acl-auth-methods
description: |-
The /acl/auth-method endpoints manage Consul's ACL Auth Methods.
---
-> **1.5.0+:** The auth method APIs are available in Consul versions 1.5.0 and newer.
# ACL Auth Method HTTP API
The `/acl/auth-method` endpoints [create](#create-an-auth-method),
[read](#read-an-auth-method), [update](#update-an-auth-method),
[list](#list-auth-methods) and [delete](#delete-an-auth-method)
ACL auth methods 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).
## Create an Auth Method
This endpoint creates a new ACL auth method.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/auth-method` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `Name` `(string: <required>)` - Specifies a name for the ACL auth method. The
name can contain alphanumeric characters, dashes `-`, and underscores `_`.
This field is immutable and must be unique.
- `Type` `(string: <required>)` - The type of auth method being configured.
The only allowed value in Consul 1.5.0 is `"kubernetes"`. This field is
immutable.
- `Description` `(string: "")` - Free form human readable description of the
auth method.
- `Config` `(map[string]string: <required>)` - The raw configuration to use for
the chosen auth method. Contents will vary depending upon the type chosen.
For more information on configuring specific auth method types, see the [auth
method documentation](/docs/acl/acl-auth-methods.html).
### Sample Payload
```json
{
"Name": "minikube",
"Type": "kubernetes",
"Description": "dev minikube cluster",
"Config": {
"Host": "https://192.0.2.42:8443",
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
}
}
```
### Sample Request
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/auth-method
```
### Sample Response
```json
{
"Name": "minikube",
"Type": "kubernetes",
"Description": "dev minikube cluster",
"Config": {
"Host": "https://192.0.2.42:8443",
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
},
"CreateIndex": 15,
"ModifyIndex": 15
}
```
## Read an Auth Method
This endpoint reads an ACL auth method with the given name. If no
auth method exists with the given name, a 404 is returned instead of a
200 response.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/auth-method/:name` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
### Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
read. This is required and is specified as part of the URL path.
### Sample Request
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/auth-method/minikube
```
### Sample Response
```json
{
"Name": "minikube",
"Type": "kubernetes",
"Description": "dev minikube cluster",
"Config": {
"Host": "https://192.0.2.42:8443",
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
},
"CreateIndex": 15,
"ModifyIndex": 224
}
```
## Update an Auth Method
This endpoint updates an existing ACL auth method.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/auth-method/:name` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `Name` `(string: <required>)` - Specifies the name of the auth method 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.
- `Type` `(string: <required>)` - Specifies the type of the auth method being
updated. This field is immutable so if present in the body then it must
match the existing value. If not present then the value will be filled in by
Consul.
- `Description` `(string: "")` - Free form human readable description of the
auth method.
- `Config` `(map[string]string: <required>)` - The raw configuration to use for
the chosen auth method. Contents will vary depending upon the type chosen.
For more information on configuring specific auth method types, see the [auth
method documentation](/docs/acl/acl-auth-methods.html).
### Sample Payload
```json
{
"Name": "minikube",
"Description": "updated name",
"Config": {
"Host": "https://192.0.2.42:8443",
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
}
}
```
### Sample Request
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/auth-method/minikube
```
### Sample Response
```json
{
"Name": "minikube",
"Description": "updated name",
"Type": "kubernetes",
"Config": {
"Host": "https://192.0.2.42:8443",
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
},
"CreateIndex": 15,
"ModifyIndex": 224
}
```
## Delete an Auth Method
This endpoint deletes an ACL auth method.
~> Deleting an auth method will also immediately delete all associated
[binding rules](/api/acl/binding-rules.html) as well as any
outstanding [tokens](/api/acl/tokens.html) created from this auth method.
| Method | Path | Produces |
| -------- | ------------------------- | -------------------------- |
| `DELETE` | `/acl/auth-method/:name` | `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.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
delete. This is required and is specified as part of the URL path.
### Sample Request
```sh
$ curl -X DELETE \
http://127.0.0.1:8500/v1/acl/auth-method/minikube
```
### Sample Response
```json
true
```
## List Auth Methods
This endpoint lists all the ACL auth methods.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/auth-methods` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
## Sample Request
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/auth-methods
```
### Sample Response
-> **Note** - The contents of the `Config` field are not included in the
listing and must be retrieved by the [auth method reading endpoint](#read-an-auth-method).
```json
[
{
"Name": "minikube-1",
"Type": "kubernetes",
"Description": "",
"CreateIndex": 14,
"ModifyIndex": 14
},
{
"Name": "minikube-2",
"Type": "kubernetes",
"Description": "",
"CreateIndex": 15,
"ModifyIndex": 15
}
]
```

372
website/source/api/acl/binding-rules.html.md Normal file
View File

@ -0,0 +1,372 @@
---
layout: api
page_title: ACL Binding Rules - HTTP API
sidebar_current: api-acl-binding-rules
description: |-
The /acl/binding-rule endpoints manage Consul's ACL Binding Rules.
---
-> **1.5.0+:** The binding rule APIs are available in Consul versions 1.5.0 and newer.
# ACL Binding Rule HTTP API
The `/acl/binding-rule` endpoints [create](#create-a-binding-rule),
[read](#read-a-binding-rule), [update](#update-a-binding-rule),
[list](#list-binding-rules) and [delete](#delete-a-binding-rule) ACL binding
rules 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).
## Create a Binding Rule
This endpoint creates a new ACL binding rule.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/binding-rule` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `Description` `(string: "")` - Free form human readable description of the binding rule.
- `AuthMethod` `(string: <required>)` - The name of the auth method that this
rule applies to. This field is immutable.
- `Selector` `(string: "")` - Specifies the expression used to match this rule
against valid identities returned from an auth method validation. If empty
this binding rule matches all valid identities returned from the auth method. For example:
```text
serviceaccount.namespace==default and serviceaccount.name!=vault
```
- `BindType` `(string: <required>)` - Specifies the way the binding rule
affects a token created at login.
- `BindType=service` - The computed bind name value is used as an
`ACLServiceIdentity.ServiceName` field in the token that is created.
```json
{ ...other fields...
"ServiceIdentities": [
{ "ServiceName": "<computed BindName>" }
]
}
```
- `BindType=role` - The computed bind name value is used as a `RoleLink.Name`
field in the token that is created. This binding rule will only apply if a
role with the given name exists at login-time. If it does not then this
rule is ignored.
```json
{ ...other fields...
"Roles": [
{ "Name": "<computed BindName>" }
]
}
```
- `BindName` `(string: <required>)` - The name to bind to a token at
login-time. What it binds to can be adjusted with different values of the
`BindType` field. This can either be a plain string or lightly templated
using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same
values that are usable by the `Selector` syntax. For example:
```text
prefixed-${serviceaccount.name}
```
### Sample Payload
```json
{
"Description": "example rule",
"AuthMethod": "minikube",
"Selector": "serviceaccount.namespace==default",
"BindType": "service",
"BindName": "{{ serviceaccount.name }}"
}
```
### Sample Request
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/binding-rule
```
### Sample Response
```json
{
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
"Description": "example rule",
"AuthMethod": "minikube",
"Selector": "serviceaccount.namespace==default",
"BindType": "service",
"BindName": "{{ serviceaccount.name }}",
"CreateIndex": 17,
"ModifyIndex": 17
}
```
## Read a Binding Rule
This endpoint reads an ACL binding rule with the given ID. If no
binding rule exists with the given ID, a 404 is returned instead of a 200
response.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/binding-rule/:id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
### Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule
to read. This is required and is specified as part of the URL path.
### Sample Request
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d
```
### Sample Response
```json
{
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
"Description": "example rule",
"AuthMethod": "minikube",
"Selector": "serviceaccount.namespace==default",
"BindType": "service",
"BindName": "{{ serviceaccount.name }}",
"CreateIndex": 17,
"ModifyIndex": 17
}
```
## Update a Binding Rule
This endpoint updates an existing ACL binding rule.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/binding-rule/:id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `ID` `(string: <required>)` - Specifies the ID of the binding rule 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.
- `Description` `(string: "")` - Free form human readable description of the binding rule.
- `AuthMethod` `(string: <required>)` - Specifies the name of the auth
method that this rule applies to. This field is immutable so if present in
the body then it must match the existing value. If not present then the value
will be filled in by Consul.
- `Selector` `(string: "")` - Specifies the expression used to match this rule
against valid identities returned from an auth method validation. If empty
this binding rule matches all valid identities returned from the auth method. For example:
```text
serviceaccount.namespace==default and serviceaccount.name!=vault
```
- `BindType` `(string: <required>)` - Specifies the way the binding rule
affects a token created at login.
- `BindType=service` - The computed bind name value is used as an
`ACLServiceIdentity.ServiceName` field in the token that is created.
```json
{ ...other fields...
"ServiceIdentities": [
{ "ServiceName": "<computed BindName>" }
]
}
```
- `BindType=role` - The computed bind name value is used as a `RoleLink.Name`
field in the token that is created. This binding rule will only apply if a
role with the given name exists at login-time. If it does not then this
rule is ignored.
```json
{ ...other fields...
"Roles": [
{ "Name": "<computed BindName>" }
]
}
```
- `BindName` `(string: <required>)` - The name to bind to a token at
login-time. What it binds to can be adjusted with different values of the
`BindType` field. This can either be a plain string or lightly templated
using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same
values that are usable by the `Selector` syntax. For example:
```text
prefixed-${serviceaccount.name}
```
### Sample Payload
```json
{
"Description": "updated rule",
"Selector": "serviceaccount.namespace=dev",
"BindType": "role",
"BindName": "{{ serviceaccount.name }}"
}
```
### Sample Request
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d
```
### Sample Response
```json
{
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
"Description": "updated rule",
"AuthMethod": "minikube",
"Selector": "serviceaccount.namespace=dev",
"BindType": "role",
"BindName": "{{ serviceaccount.name }}",
"CreateIndex": 17,
"ModifyIndex": 18
}
```
## Delete a Binding Rule
This endpoint deletes an ACL binding rule.
| Method | Path | Produces |
| -------- | ------------------------- | -------------------------- |
| `DELETE` | `/acl/binding-rule/:id` | `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.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to
delete. This is required and is specified as part of the URL path.
### Sample Request
```sh
$ curl -X DELETE \
http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d
```
### Sample Response
```json
true
```
## List Binding Rules
This endpoint lists all the ACL binding rules.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/binding-rules` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
## Parameters
- `authmethod` `(string: "")` - Filters the binding rule list to those binding
rules that are linked with the specific named auth method.
## Sample Request
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/binding-rules
```
### Sample Response
```json
[
{
"ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
"Description": "example 1",
"AuthMethod": "minikube-1",
"BindType": "service",
"BindName": "k8s-{{ serviceaccount.name }}",
"CreateIndex": 17,
"ModifyIndex": 17
},
{
"ID": "b4f0a0a3-69f2-7a4f-6bef-326034ace9fa",
"Description": "example 2",
"AuthMethod": "minikube-2",
"Selector": "serviceaccount.namespace==default",
"BindName": "k8s-{{ serviceaccount.name }}",
"CreateIndex": 18,
"ModifyIndex": 18
}
]
```

6
website/source/api/acl/legacy.html.md
View File

@ -12,7 +12,9 @@ the new ACL [Token](/api/acl/tokens.html) and [Policy](/api/acl/policies.html) A
# ACL HTTP API
The `/acl` endpoints create, update, destroy, and query ACL tokens in Consul. For more information about ACLs, please see the [ACL Guide](/docs/guides/acl-legacy.html).
The `/acl` endpoints create, update, destroy, and query ACL tokens in Consul.
For more information about ACLs, please see the [ACL Guide](/docs/guides/acl-legacy.html).
## Create ACL Token
@ -289,4 +291,4 @@ $ curl \
"Rules": "..."
}
]
```
```

29
website/source/api/acl/policies.html.md
View File

@ -11,8 +11,11 @@ description: |-
# ACL Policy HTTP API
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.
For more information about ACLs, please see the [ACL Guide](/docs/guides/acl.html).
[update](#update-a-policy), [list](#list-policies) and
[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).
## Create a Policy
@ -35,8 +38,8 @@ The table below shows this endpoint's support for
### Parameters
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name
can only contain alphanumeric characters as well as `-` and `_` and must be
unique.
can contain alphanumeric characters, dashes `-`, and underscores `_`.
This name must be unique.
- `Description` `(string: "")` - Free form human readable description of the policy.
@ -60,9 +63,8 @@ The table below shows this endpoint's support for
### Sample Request
```text
$ curl \
--request PUT \
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/policy
```
@ -110,7 +112,7 @@ The table below shows this endpoint's support for
### Sample Request
```text
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9fdc78f5
```
@ -181,9 +183,8 @@ The table below shows this endpoint's support for
### Sample Request
```text
$ curl \
--request PUT \
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/policy/c01a1f82-44be-41b0-a686-685fb6e0f485
```
@ -230,8 +231,8 @@ The table below shows this endpoint's support for
### Sample Request
```text
$ curl -X DELETE
```sh
$ curl -X DELETE \
http://127.0.0.1:8500/v1/acl/policy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
@ -260,7 +261,7 @@ The table below shows this endpoint's support for
## Sample Request
```text
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/policies
```

456
website/source/api/acl/roles.html.md Normal file
View File

@ -0,0 +1,456 @@
---
layout: api
page_title: ACL Roles - HTTP API
sidebar_current: api-acl-roles
description: |-
The /acl/role endpoints manage Consul's ACL Roles.
---
-> **1.5.0+:** The role APIs are available in Consul versions 1.5.0 and newer.
# ACL Role HTTP API
The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role),
[update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles 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).
## Create a Role
This endpoint creates a new ACL role.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/role` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
can contain alphanumeric characters, dashes `-`, and underscores `_`.
This name must be unique.
- `Description` `(string: "")` - Free form human readable description of the role.
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
applied to the role. A PolicyLink is an object with an "ID" and/or "Name"
field to specify a policy. With the PolicyLink, roles can be linked to
policies either by the policy name or by the policy ID. When policies are
linked by name they will be internally resolved to the policy ID. With
linking roles internally by IDs, Consul enables policy renaming without
breaking tokens.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
applied to the role. Added in Consul 1.5.0.
- `ServiceName` `(string: <required>)` - The name of the service. The name
must be no longer than 256 characters, must start and end with a lowercase
alphanumeric character, and can only contain lowercase alphanumeric
characters as well as `-` and `_`.
- `Datacenters` `(array<string>)` - Specifies the datacenters the effective
policy is valid within. When no datacenters are provided the effective
policy is valid in all datacenters including those which do not yet exist
but may in the future.
### Sample Payload
```json
{
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765"
},
{
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": [
"dc1"
]
}
]
}
```
### Sample Request
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/role
```
### Sample Response
```json
{
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": [
"dc1"
]
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
```
## Read a Role
This endpoint reads an ACL role with the given ID. If no role exists with the
given ID, a 404 is returned instead of a 200 response.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/role/:id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
### Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
read. This is required and is specified as part of the URL path.
### Sample Request
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4
```
### Sample Response
```json
{
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": [
"dc1"
]
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
```
## Read a Role by Name
This endpoint reads an ACL role with the given name. If no role exists with the
given name, a 404 is returned instead of a 200 response.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/role/name/:name` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
### Parameters
- `name` `(string: <required>)` - Specifies the Name of the ACL role to
read. This is required and is specified as part of the URL path.
### Sample Request
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/role/name/example-role
```
### Sample Response
```json
{
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": [
"dc1"
]
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
```
## Update a Role
This endpoint updates an existing ACL role.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `PUT` | `/acl/role/:id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `ID` `(string: <required>)` - Specifies the ID of the role 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.
- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
can only contain alphanumeric characters as well as `-` and `_` and must be
unique.
- `Description` `(string: "")` - Free form human readable description of the role.
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
applied to the role. A PolicyLink is an object with an "ID" and/or "Name"
field to specify a policy. With the PolicyLink, roles can be linked to
policies either by the policy name or by the policy ID. When policies are
linked by name they will be internally resolved to the policy ID. With
linking roles internally by IDs, Consul enables policy renaming without
breaking tokens.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
applied to the role. Added in Consul 1.5.0.
### Sample Payload
```json
{
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
"Name": "example-two",
"Policies": [
{
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "db"
}
]
}
```
### Sample Request
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/role/8bec74a4-5ced-45ed-9c9d-bca6153490bb
```
### Sample Response
```json
{
"ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
"Name": "example-two",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "db"
}
],
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
"CreateIndex": 14,
"ModifyIndex": 28
}
```
## Delete a Role
This endpoint deletes an ACL role.
| Method | Path | Produces |
| -------- | ------------------------- | -------------------------- |
| `DELETE` | `/acl/role/:id` | `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.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO` | `none` | `none` | `acl:write` |
### Parameters
- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
delete. This is required and is specified as part of the URL path.
### Sample Request
```sh
$ curl -X DELETE \
http://127.0.0.1:8500/v1/acl/role/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
### Sample Response
```json
true
```
## List Roles
This endpoint lists all the ACL roles.
| Method | Path | Produces |
| ------ | ---------------------------- | -------------------------- |
| `GET` | `/acl/roles` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/features/blocking.html),
[consistency modes](/api/features/consistency.html),
[agent caching](/api/features/caching.html), and
[required ACLs](/api/index.html#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `YES` | `all` | `none` | `acl:read` |
## Parameters
- `policy` `(string: "")` - Filters the role list to those roles that are
linked with the specific policy ID.
## Sample Request
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/roles
```
### Sample Response
```json
[
{
"ID": "5e52a099-4c90-c067-5478-980f06be9af5",
"Name": "node-read",
"Description": "",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"Hash": "K6AbfofgiZ1BEaKORBloZf7WPdg45J/PipHxQiBlK1U=",
"CreateIndex": 50,
"ModifyIndex": 50
},
{
"ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
"Name": "example-role",
"Description": "Showcases all input parameters",
"Policies": [
{
"ID": "783beef3-783f-f41f-7422-7087dc272765",
"Name": "node-read"
}
],
"ServiceIdentities": [
{
"ServiceName": "web"
},
{
"ServiceName": "db",
"Datacenters": [
"dc1"
]
}
],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
}
]
```

140
website/source/api/acl/tokens.html.md
View File

@ -1,9 +1,9 @@
---
layout: api
page_title: ACL Policies - HTTP API
page_title: ACL Tokens - HTTP API
sidebar_current: api-acl-tokens
description: |-
The /acl/token endpoints manage Consul's ACL Policies.
The /acl/token endpoints manage Consul's ACL Tokens.
---
-> **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)
@ -13,7 +13,8 @@ description: |-
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.
For more information about ACLs, please see the [ACL Guide](/docs/guides/acl.html).
For more information on how to setup ACLs, please see
the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
## Create a Token
@ -45,15 +46,49 @@ The table below shows this endpoint's support for
- `Description` `(string: "")` - Free form human readable description of the token.
- `Policies` `(array<PolicyLink>)` - The list of policies that should
be applied to the token. A PolicyLink is an object with an "ID" and/or "Name" field
to specify a policy. With the PolicyLink, tokens can be linked to policies either by the
policy name or by the policy ID. When policies are linked by name they will be
internally resolved to the policy ID. With linking tokens internally by IDs,
Consul enables policy renaming without breaking tokens.
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
applied to the token. A PolicyLink is an object with an "ID" and/or "Name"
field to specify a policy. With the PolicyLink, tokens can be linked to
policies either by the policy name or by the policy ID. When policies are
linked by name they will be internally resolved to the policy ID. With
linking tokens internally by IDs, Consul enables policy renaming without
breaking tokens.
- `Local` `(bool: false)` - If true, indicates that the token should not be replicated
globally and instead be local to the current datacenter.
- `Roles` `(array<RoleLink>)` - The list of roles that should be applied to the
token. A RoleLink is an object with an "ID" and/or "Name" field to specify a
role. With the RoleLink, tokens can be linked to roles either by the role
name or by the role ID. When roles are linked by name they will be internally
resolved to the role ID. With linking tokens internally by IDs, Consul
enables role renaming without breaking tokens. Added in Consul 1.5.0.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
applied to the token. Added in Consul 1.5.0.
- `ServiceName` `(string: <required>)` - The name of the service. The name
must be no longer than 256 characters, must start and end with a lowercase
alphanumeric character, and can only contain lowercase alphanumeric
characters as well as `-` and `_`.
- `Datacenters` `(array<string>)` - Specifies the datacenters the effective
policy is valid within. When no datacenters are provided the effective
policy is valid in all datacenters including those which do not yet exist
but may in the future.
- `Local` `(bool: false)` - If true, indicates that the token should not be
replicated globally and instead be local to the current datacenter.
- `ExpirationTime` `(time: "")`- If set this represents the point after which a
token should be considered revoked and is eligible for destruction. The
default unset value represents NO expiration. This value must be between 1
minute and 24 hours in the future. Added in Consul 1.5.0.
- `ExpirationTTL` `(duration: 0s)` - This is a convenience field and if set
will initialize the `ExpirationTime` field to a value of `CreateTime +
ExpirationTTL`. This field is not persisted beyond its initial use. Can be
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.
### Sample Payload
@ -74,9 +109,8 @@ The table below shows this endpoint's support for
### Sample Request
```text
$ curl \
--request PUT \
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/token
```
@ -132,7 +166,7 @@ The table below shows this endpoint's support for
### Sample Request
```text
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511
```
@ -191,7 +225,7 @@ retrieving the data for a token that you must already possess its secret.
### Sample Request
```text
```sh
$ curl -H "X-Consul-Token: 6a1253d2-1785-24fd-91c2-f8e78c745511" \
http://127.0.0.1:8500/v1/acl/token/self
```
@ -254,15 +288,47 @@ The table below shows this endpoint's support for
- `Description` `(string: "")` - Free form human readable description of this token.
- `Policies` `(array<PolicyLink>)` - This is the list of policies that should
be applied to this token. A PolicyLink is an object with an "ID" and/or "Name" field
to specify a policy. With this tokens can be linked to policies either by the
policy name or by the policy ID. When policies are linked by name they will
internally be resolved to the policy ID. With linking tokens internally by IDs,
Consul enables policy renaming without breaking tokens.
be applied to this token. A PolicyLink is an object with an "ID" and/or
"Name" field to specify a policy. With the PolicyLink tokens can be linked to policies
either by the policy name or by the policy ID. When policies are linked by
name they will internally be resolved to the policy ID. With linking tokens
internally by IDs, Consul enables policy renaming without breaking tokens.
- `Roles` `(array<RoleLink>)` - The list of roles that should be applied to the
token. A RoleLink is an object with an "ID" and/or "Name" field to specify a
role. With the RoleLink, tokens can be linked to roles either by the role
name or by the role ID. When roles are linked by name they will be internally
resolved to the role ID. With linking tokens internally by IDs, Consul
enables role renaming without breaking tokens.
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
identities](/docs/acl/acl-system.html#acl-service-identities) that should be
applied to the token. Added in Consul 1.5.0.
- `ServiceName` `(string: <required>)` - The name of the service. The name
must be no longer than 256 characters, must start and end with a lowercase
alphanumeric character, and can only contain lowercase alphanumeric
characters as well as `-` and `_`.
- `Datacenters` `(array<string>)` - Specifies the datacenters the effective
policy is valid within. When no datacenters are provided the effective
policy is valid in all datacenters including those which do not yet exist
but may in the future.
- `Local` `(bool: false)` - If true, indicates that this token should not be
replicated globally and instead be local to the current datacenter. This
value must match the existing value or the request will return an error.
- `AuthMethod` `(string: "")` - Specifies the name of the auth method that
created this token. This field is immutable so if present in the body then it
must match the existing value. If not present then the value will be filled
in by Consul.
- `ExpirationTime` `(time: "")` - Specifies the expiration time for the token
being updated. This field is immutable so if present in the body then it must
match the existing value. If not present then the value will be filled in by
Consul.
- `Local` `(bool: false)` - If true, indicates that this token should not be replicated
globally and instead be local to the current datacenter. This value must match the
existing value or the request will return an error.
### Sample Payload
@ -286,9 +352,8 @@ The table below shows this endpoint's support for
### Sample Request
```text
$ curl \
--request PUT \
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511
```
@ -357,9 +422,8 @@ The table below shows this endpoint's support for
### Sample Request
```text
$ curl \
--request PUT \
```sh
$ curl -X PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511/clone
```
@ -421,8 +485,8 @@ The table below shows this endpoint's support for
### Sample Request
```text
$ curl -XDELETE
```sh
$ curl -X DELETE \
http://127.0.0.1:8500/v1/acl/token/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
```
@ -451,12 +515,18 @@ The table below shows this endpoint's support for
## Parameters
- `policy` `(string: "")` - Filters the token list to those tokens that
are linked with the specific policy ID.
- `policy` `(string: "")` - Filters the token list to those tokens that are
linked with the specific policy ID.
- `role` `(string: "")` - Filters the token list to those tokens that are
linked with the specific role ID.
- `authmethod` `(string: "")` - Filters the token list to those tokens that are
linked with the specific named auth method.
## Sample Request
```text
```sh
$ curl -X GET http://127.0.0.1:8500/v1/acl/tokens
```

43
website/source/assets/images/auth-methods.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

127
website/source/docs/acl/acl-auth-methods.html.md Normal file
View File

@ -0,0 +1,127 @@
---
layout: "docs"
page_title: "ACL Auth Methods"
sidebar_current: "docs-acl-auth-methods"
description: |-
An auth method is a component in Consul that performs authentication against a trusted external party to authorize the creation of an ACL tokens usable within the local datacenter.
---
-> **1.5.0+:** This guide only applies in Consul versions 1.5.0 and newer.
# ACL Auth Methods
An auth method is a component in Consul that performs authentication against a
trusted external party to authorize the creation of an ACL tokens usable within
the local datacenter.
The only supported type of auth method in Consul 1.5.0 is
[`kubernetes`](/docs/acl/auth-methods/kubernetes.html).
## Overview
Without an auth method a trusted operator is critically involved in the
creation and secure introduction of each ACL token to every application that
needs one, while ensuring that the policies assigned to these tokens follow the
principle of least-privilege.
When running in environments such as a public cloud or when supervised by a
cluster scheduler, applications may already have access to uniquely identifying
credentials that were delivered securely by the platform. Consul auth method
integrations allow for these credentials to be used to create ACL tokens with
properly-scoped policies without additional operator intervention.
In Consul 1.5.0 the focus is around simplifying the creation of tokens with the
privileges necessary to participate in a [Connect](/docs/connect/index.html)
service mesh with minimal operator intervention.
## Operator Configuration
An operator needs to configure each auth method that is to be trusted by
using the API or command line before they can be used by applications.
* **Authentication** - One or more **auth methods** should be configured with
details about how to authenticate application credentials. Successful
validation of application credentials will return a set of trusted identity
attributes (such as a username). These can be managed with the `consul acl
auth-method` subcommands or the corresponding [API
endpoints](/api/acl/auth-methods.html). The specific details of
configuration are type dependent and described in their own documentation
pages.
* **Authorization** - One or more **binding rules** must be configured to define
how to translate trusted identity attributes from each auth method into
privileges assigned to the ACL token that is created. These can be managed
with the `consul acl binding-rule` subcommands or the corresponding [API
endpoints](/api/acl/binding-rules.html).
## Binding Rules
Binding rules allow an operator to express a systematic way of automatically
linking [roles](/docs/acl/acl-system.html#acl-roles) and [service
identities](/docs/acl/acl-system.html#acl-service-identities) to newly created
tokens without operator intervention.
Successful authentication with an auth method returns a set of trusted
identity attributes corresponding to the authenticated identity. Those
attributes are matched against all configured binding rules for that auth
method to determine what privileges to grant the the Consul ACL token it will
ultimately create.
Each binding rule is composed of two portions:
- **Selector** - A logical query that must match the trusted identity
attributes for the binding rule to be applicable to a given login attempt.
The syntax uses github.com/hashicorp/go-bexpr which is shared with the [API
filtering feature](/api/features/filtering.html). For example:
`"serviceaccount.namespace==default and serviceaccount.name!=vault"`
- **Bind Type and Name** - A binding rule can bind a token to a
[role](/docs/acl/acl-system.html#acl-roles) or to a [service
identity](/docs/acl/acl-system.html#acl-service-identities) by name. The name
can be specified with a plain string or the bind name can be lightly
templated using [HIL syntax](https://github.com/hashicorp/hil) to interpolate
the same values that are usable by the `Selector` syntax. For example:
`"dev-${serviceaccount.name}"`
When multiple binding rules match, then all roles and service identities are
jointly linked to the token created by the login process.
## Overall Login Process
Applications are responsible for exchanging their auth method specific secret
bearer token for a Consul ACL token by using the login process:
![diagram of auth method login](/assets/images/auth-methods.svg)
1. Applications use the `consul login` subcommand or the [login API
endpoint](/api/acl/acl.html#login-to-auth-method) to authenticate to a
specific auth method using their local Consul client. Applications provide
both the name of the auth method and a secret bearer token during login.
2. The Consul client forwards login requests to the leading Consul server.
3. The Consul leader then uses auth method specific mechanisms to validate the
provided bearer token credentials.
4. Successful validation returns trusted identity attributes to the Consul
leader.
5. The Consul leader consults the configured set of binding rules associated
with the specified auth method and selects only those rules that match the
trusted identity attributes.
6. The Consul leader uses the matching binding rules to generate a list of
roles and service identities and assigns them to a token created exclusively
in the _local_ datacenter. If none are generated the login attempt fails.
7. The relevant `SecretID` and remaining details about the token are returned to
the originating Consul client.
8. The Consul client returns the token details back to the application.
9. (later) Applications SHOULD use the `consul logout` subcommand or the
[logout API endpoint](/api/acl/acl.html#logout-from-auth-method) to destroy
their token when it is no longer required.
For more details about specific auth methods and how to configure them, click
on the name of the auth method type in the sidebar.

28
website/source/docs/acl/acl-legacy.html.md
View File

@ -41,7 +41,7 @@ The most significant change is that rules with selectors _no longer prefix match
by default_. In the legacy system the following rules would grant access to
nodes, services and keys _prefixed_ with foo.
```
```hcl
node "foo" { policy = "write" }
service "foo" { policy = "write" }
key "foo" { policy = "write" }
@ -58,7 +58,7 @@ Prefix matching can be expressed in the new ACL system explicitly, making the
following rules in the new system exactly the same as the rules above in the
old.
```
```hcl
node_prefix "foo" { policy = "write" }
service_prefix "foo" { policy = "write" }
key_prefix "foo" { policy = "write" }
@ -218,7 +218,7 @@ In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via
Since the [`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0):
```text
```hcl
agent "<node name of agent>" {
policy = "write"
}
@ -240,7 +240,7 @@ The [`acl_agent_token`](/docs/agent/options.html#acl_agent_token) is a special t
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
```text
```hcl
node "mynode" {
policy = "write"
}
@ -617,7 +617,7 @@ machine-generate. Rules can make use of one or more policies.
Specification in the HCL format looks like:
```text
```hcl
# These control access to the key/value store.
key "" {
policy = "read"
@ -702,7 +702,7 @@ and [`service`](#service-rules) policies instead.
Agent rules look like this:
```text
```hcl
agent "" {
policy = "read"
}
@ -731,7 +731,7 @@ firing events and listing events.
Event rules look like this:
```text
```hcl
event "" {
policy = "read"
}
@ -754,7 +754,7 @@ give agents a token with access to this event prefix, in addition to configuring
The `key` policy controls access to key/value store operations in the [KV API](/api/kv.html). Key
rules look like this:
```text
```hcl
key "" {
policy = "read"
}
@ -777,7 +777,7 @@ Consul 1.0 introduces a new `list` policy for keys that is only enforced when op
`list` controls access to recursively list entries and keys, and enables more fine grained policies. With "acl_enable_key_list_policy",
recursive reads via [the KV API](/api/kv.html#recurse) with an invalid token result in a 403. Example:
```text
```hcl
key "" {
policy = "deny"
}
@ -801,7 +801,7 @@ Consul Enterprise supports additional optional fields for key write policies for
[Sentinel](https://docs.hashicorp.com/sentinel/app/consul/) integration. An example key rule with a
Sentinel code policy looks like this:
```text
```hcl
key "foo" {
policy = "write"
sentinel {
@ -838,7 +838,7 @@ operations like fetching the list of cluster members.
Node rules look like this:
```text
```hcl
node "" {
policy = "read"
}
@ -911,7 +911,7 @@ policies, as will be explained below.
Query rules look like this:
```text
```hcl
query "" {
policy = "read"
}
@ -1030,7 +1030,7 @@ and service discovery with the [Health API](/api/health.html).
Service rules look like this:
```text
```hcl
service "" {
policy = "read"
}
@ -1086,7 +1086,7 @@ The `session` policy controls access to [Session API](/api/session.html) operati
Session rules look like this:
```text
```hcl
session "" {
policy = "read"
}

6
website/source/docs/acl/acl-migrate-tokens.html.md
View File

@ -82,7 +82,7 @@ The simplest and most automatic strategy is to create one new policy for every
existing token. This is easy to automate, but may result in a lot of policies
with exactly the same rules and with non-human-readable names which will make
managing policies harder. This approach can be accomplished using the [`consul
acl policy create`](/docs/commands/acl/acl-policy.html#create) command with
acl policy create`](/docs/commands/acl/policy/create.html) command with
`-from-token` option.
| Pros | Cons |
@ -112,7 +112,7 @@ semantics of the old ACL system.
To assist with this approach, there is a CLI tool and corresponding API that can
translate a legacy ACL token's rules into a new ACL policy that is exactly
equivalent. See [`consul acl
translate-rules`](/docs/commands/acl/acl-translate-rules.html).
translate-rules`](/docs/commands/acl/translate-rules.html).
| Pros | Cons |
| ---- | ---- |
@ -141,7 +141,7 @@ endpoint. Specifically, ensure that the `Rules` field is omitted or empty. Empty
#### Update via CLI
Use the [`consul acl token update`](/docs/commands/acl/acl-token.html#update)
Use the [`consul acl token update`](/docs/commands/acl/token/update.html)
command to update the token. Specifically you need to use `-upgrade-legacy`
which will ensure that legacy rules are removed as well as the new policies
added.

28
website/source/docs/acl/acl-rules.html.md
View File

@ -57,7 +57,7 @@ machine-generate. Rules can make use of one or more policies.
Specification in the HCL format looks like:
```text
```hcl
# These control access to the key/value store.
key_prefix "" {
policy = "read"
@ -79,7 +79,7 @@ operator = "read"
This is equivalent to the following JSON input:
```javascript
```json
{
"key_prefix": {
"": {
@ -154,7 +154,7 @@ The `acl` resource controls access to ACL operations in the
ACL rules look like this:
```text
```hcl
acl = "write"
```
@ -170,7 +170,7 @@ and [`service` or `service_prefix`](#service-rules) policies instead.
Agent rules look like this:
```text
```hcl
agent_prefix "" {
policy = "read"
}
@ -199,7 +199,7 @@ firing events and listing events.
Event rules look like this:
```text
```hcl
event_prefix "" {
policy = "read"
}
@ -221,7 +221,7 @@ give agents a token with access to this event prefix, in addition to configuring
The `key` and `key_prefix` resources control access to key/value store operations in the [KV API](/api/kv.html). Key
rules look like this:
```text
```hcl
key_prefix "" {
policy = "read"
}
@ -242,7 +242,7 @@ Consul 1.0 introduces a new `list` policy for keys that is only enforced when op
`list` controls access to recursively list entries and keys, and enables more fine grained policies. With "acl.enable_key_list_policy",
recursive reads via [the KV API](/api/kv.html#recurse) with an invalid token result in a 403. Example:
```text
```hcl
key_prefix "" {
policy = "deny"
}
@ -266,7 +266,7 @@ Consul Enterprise supports additional optional fields for key write policies for
[Sentinel](https://docs.hashicorp.com/sentinel/app/consul/) integration. An example key rule with a
Sentinel code policy looks like this:
```text
```hcl
key "foo" {
policy = "write"
sentinel {
@ -288,7 +288,7 @@ The `keyring` resource controls access to keyring operations in the
Keyring rules look like this:
```text
```hcl
keyring = "write"
```
@ -303,7 +303,7 @@ operations like fetching the list of cluster members.
Node rules look like this:
```text
```hcl
node_prefix "" {
policy = "read"
}
@ -358,7 +358,7 @@ The `operator` resource controls access to cluster-level operations in the
Operator rules look like this:
```text
```hcl
operator = "read"
```
@ -374,7 +374,7 @@ policies, as will be explained below.
Query rules look like this:
```text
```hcl
query_prefix "" {
policy = "read"
}
@ -491,7 +491,7 @@ and service discovery with the [Health API](/api/health.html).
Service rules look like this:
```text
```hcl
service_prefix "" {
policy = "read"
}
@ -546,7 +546,7 @@ The `session` and `session_prefix` resources controls access to [Session API](/a
Session rules look like this:
```text
```hcl
session_prefix "" {
policy = "read"
}

94
website/source/docs/acl/acl-system.html.md
View File

@ -27,16 +27,35 @@ At the highest level, there are two major components to the ACL system:
Accessor ID which is used to name a token, and a Secret ID which is used as the bearer token used to
make requests to Consul.
ACL tokens and policies are managed by Consul operators via Consul's
[ACL API](/api/acl/acl.html), [ACL CLI](/docs/commands/acl.html), or systems like
For many scenarios policies and tokens are sufficient, but more advanced setups
may benefit from additional components in the ACL system:
* **ACL Roles** - Roles allow for the grouping of a set of policies and service
identities into a reusable higher-level entity that can be applied to many
tokens. (Added in Consul 1.5.0)
* **ACL Service Identities** - Service identities are a policy template for
expressing a link to a policy suitable for use in [Consul
Connect](/docs/connect/index.html). At authorization time this acts like an
additional policy was attached, the contents of which are described further
below. These are directly attached to tokens and roles and are not
independently configured. (Added in Consul 1.5.0)
* **ACL Auth Methods and Binding Rules** - To learn more about these topics,
see the [dedicated auth methods documentation page](/docs/acl/acl-auth-methods.html).
ACL tokens, policies, roles, auth methods, and binding rules are managed by
Consul operators via Consul's [ACL API](/api/acl/acl.html),
[ACL CLI](/docs/commands/acl.html), or systems like
[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul/index.html).
### ACL Policies
An ACL policy is a named set of rules and is composed of the following elements:
* **ID** - The policies auto-generated public identifier.
* **ID** - The policy's auto-generated public identifier.
* **Name** - A unique meaningful name for the policy.
* **Description** - A human readable description of the policy. (Optional)
* **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules.html#rule-specification) documentation for more details.
* **Datacenters** - A list of datacenters the policy is valid within.
@ -46,6 +65,59 @@ An ACL policy is a named set of rules and is composed of the following elements:
and will be assigned the reserved ID of `00000000-0000-0000-0000-000000000001`. This policy can be renamed but modification
of anything else including the rule set and datacenter scoping will be prevented by Consul.
### ACL Service Identities
-> Added in Consul 1.5.0
An ACL service identity is an [ACL policy](/docs/acl/acl-system.html#acl-policies) template for expressing a link to a policy
suitable for use in [Consul Connect](/docs/connect/index.html). They are usable
on both tokens and roles and are composed of the following elements:
* **Service Name** - The name of the service.
* **Datacenters** - A list of datacenters the effective policy is valid within. (Optional)
Services participating in the service mesh will need privileges to both _be
discovered_ and to _discover other healthy service instances_. Suitable
policies tend to all look nearly identical so a service identity is a policy
template to aid in avoiding boilerplate policy creation.
At authorization time a service identity acts like an additional policy was
attached to the token with the following contents:
```hcl
// Allow the service and its sidecar proxy to register into the catalog.
service "<Service Name>" {
policy = "write"
}
service "<Service Name>-sidecar-proxy" {
policy = "write"
}
// Allow for any potential upstreams to be resolved.
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
```
The [API documentation for roles](/api/acl/roles.html#sample-payload) has some
examples of using a service identity.
### ACL Roles
-> Added in Consul 1.5.0
An ACL role is a named set of policies and service identities and is composed
of the following elements:
* **ID** - The role's auto-generated public identifier.
* **Name** - A unique meaningful name for the role.
* **Description** - A human readable description of the role. (Optional)
* **Policy Set** - The list of policies that are applicable for the role.
* **Service Identity Set** - The list of service identities that are applicable for the role.
### ACL Tokens
ACL tokens are used to determine if the caller is authorized to perform an action. An ACL token is composed of the following
@ -55,8 +127,11 @@ elements:
* **Secret ID** -The bearer token used when making requests to Consul.
* **Description** - A human readable description of the token. (Optional)
* **Policy Set** - The list of policies that are applicable for the token.
* **Role Set** - The list of roles that are applicable for the token. (Added in Consul 1.5.0)
* **Service Identity Set** - The list of service identities that are applicable for the token. (Added in Consul 1.5.0)
* **Locality** - Indicates whether the token should be local to the datacenter it was created within or created in
the primary datacenter and globally replicated.
* **Expiration Time** - The time at which this token is revoked. (Optional; Added in Consul 1.5.0)
#### Builtin Tokens
@ -64,7 +139,7 @@ During cluster bootstrapping when ACLs are enabled both the special `anonymous`
injected.
* **Anonymous Token** - The anonymous token is used when a request is made to Consul without specifying a bearer token.
The anonymous token's description and policies may be updated but Consul will prevent this tokens deletion. When created,
The anonymous token's description and policies may be updated but Consul will prevent this token's deletion. When created,
it will be assigned `00000000-0000-0000-0000-000000000002` for its Accessor ID and `anonymous` for its Secret ID.
* **Master Token** - When a master token is present within the Consul configuration, it is created and will be linked
@ -78,7 +153,9 @@ The token Secret ID is passed along with each RPC request to the servers. Consul
query string parameter, the `X-Consul-Token` request header, or an
[RFC6750](https://tools.ietf.org/html/rfc6750) authorization bearer token. Consul's
[CLI commands](/docs/commands/index.html) can accept tokens via the
`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable.
`token` argument, or the `CONSUL_HTTP_TOKEN` environment variable. The CLI
commands can also accept token values stored in files with the `token-file`
argument, or the `CONSUL_HTTP_TOKEN_FILE` environment variable.
If no token is provided for an HTTP request then Consul will use the default ACL token
if it has been configured. If no default ACL token was configured then the anonymous
@ -86,7 +163,7 @@ token will be used.
#### ACL Rules and Scope
The rules from all policies linked with a token are combined to form that token's
The rules from all policies, roles, and service identities linked with a token are combined to form that token's
effective rule set. Policy rules can be defined in either a whitelist or blacklist
mode depending on the configuration of [`acl_default_policy`](/docs/agent/options.html#acl_default_policy).
If the default policy is to "deny" access to all resources, then policy rules can be set to
@ -137,6 +214,7 @@ as to whether they are set on servers, clients, or both.
| [`acl.enabled`](/docs/agent/options.html#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled |
| [`acl.default_policy`](/docs/agent/options.html#acl_default_policy) | `OPTIONAL` | `N/A` | Determines whitelist or blacklist mode |
| [`acl.down_policy`](/docs/agent/options.html#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails |
| [`acl.role_ttl`](/docs/agent/options.html#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles |
| [`acl.policy_ttl`](/docs/agent/options.html#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies |
| [`acl.token_ttl`](/docs/agent/options.html#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens |
@ -156,7 +234,7 @@ All of these tokens except the `master` token can all be introduced or updated v
Since the [`acl.tokens.agent_master`](/docs/agent/options.html#acl_tokens_agent_master) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it
```text
```hcl
agent "<node name of agent>" {
policy = "write"
}
@ -175,7 +253,7 @@ The [`acl.tokens.agent`](/docs/agent/options.html#acl_tokens_agent) is a special
Here's an example policy sufficient to accomplish the above for a node called `mynode`:
```text
```hcl
node "mynode" {
policy = "write"
}

137
website/source/docs/acl/auth-methods/kubernetes.html.md Normal file
View File

@ -0,0 +1,137 @@
---
layout: "docs"
page_title: "Kubernetes Auth Method"
sidebar_current: "docs-acl-auth-methods-kubernetes"
description: |-
The Kubernetes auth method type allows for a Kubernetes service account token to be used to authenticate to Consul. This method of authentication makes it easy to introduce a Consul token into a Kubernetes pod.
---
-> **1.5.0+:** This guide only applies in Consul versions 1.5.0 and newer.
# Kubernetes Auth Method
The `kubernetes` auth method type allows for a Kubernetes service account token
to be used to authenticate to Consul. This method of authentication makes it
easy to introduce a Consul token into a Kubernetes pod.
This page assumes general knowledge of [Kubernetes](https://kubernetes.io/) and
the concepts described in the main [auth method
documentation](/docs/acl/acl-auth-methods.html).
## Config Parameters
The following auth method [`Config`](/api/acl/auth-methods.html#config)
parameters are required to properly configure an auth method of type
`kubernetes`:
- `Host` `(string: <required>)` - Must be a host string, a host:port pair, or a
URL to the base of the Kubernetes API server.
- `CACert` `(string: <required>)` - PEM encoded CA cert for use by the TLS
client used to talk with the Kubernetes API. NOTE: Every line must end with a
newline (`\n`).
- `ServiceAccountJWT` `(string: <required>)` - A Service Account Token
([JWT](https://jwt.io/ "JSON Web Token")) used by the Consul leader to
validate application JWTs during login.
### Sample Config
```json
{
...other fields...
"Config": {
"Host": "https://192.0.2.42:8443",
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
}
}
```
## RBAC
The Kubernetes service account corresponding to the configured
[`ServiceAccountJWT`](/docs/acl/auth-methods/kubernetes.html#serviceaccountjwt)
needs to have access to two Kubernetes APIs:
- [**TokenReview**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#create-tokenreview-v1-authentication-k8s-io)
-> Kubernetes should be running with `--service-account-lookup`. This is
defaulted to true in Kubernetes 1.7, but any versions prior should ensure
the Kubernetes API server is started with this setting.
- [**ServiceAccount**](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#read-serviceaccount-v1-core)
(`get`)
The following is an example
[RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
configuration snippet to grant the necessary permissions to a service account
named `consul-auth-method-example`:
```yaml
---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: review-tokens
namespace: default
subjects:
- kind: ServiceAccount
name: consul-auth-method-example
namespace: default
roleRef:
kind: ClusterRole
name: system:auth-delegator
apiGroup: rbac.authorization.k8s.io
---
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: service-account-getter
namespace: default
rules:
- apiGroups: [""]
resources: ["serviceaccounts"]
verbs: ["get"]
---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: get-service-accounts
namespace: default
subjects:
- kind: ServiceAccount
name: consul-auth-method-example
namespace: default
roleRef:
kind: ClusterRole
name: service-account-getter
apiGroup: rbac.authorization.k8s.io
```
## Trusted Identity Attributes
The authentication step returns the following trusted identity attributes for
use in binding rule selectors and bind name interpolation.
| Attributes | Supported Selector Operations | Can be Interpolated |
| -------------------------- | ---------------------------------- | ------------------- |
| `serviceaccount.namespace` | Equal, Not Equal | yes |
| `serviceaccount.name` | Equal, Not Equal | yes |
| `serviceaccount.uid` | Equal, Not Equal | yes |
## Kubernetes Authentication Details
Initially the
[`ServiceAccountJWT`](/docs/acl/auth-methods/kubernetes.html#serviceaccountjwt)
given to the Consul leader uses the TokenReview API to validate the provided
JWT. The trusted attributes of `serviceaccount.namespace`,
`serviceaccount.name`, and `serviceaccount.uid` are populated directly from the
Service Account metadata.
The Consul leader makes an additional query, this time to the ServiceAccount
API to check for the existence of an annotation of
`consul.hashicorp.com/service-name` on the ServiceAccount object. If one is
found its value will override the trusted attribute of `serviceaccount.name`
for the purposes of evaluating any binding rules.

6
website/source/docs/agent/options.html.md
View File

@ -529,6 +529,12 @@ default will automatically work with some tooling.
it reduces the number of refreshes. However, because the caches are not actively invalidated,
ACL policy may be stale up to the TTL value.
* <a name="acl_role_ttl"></a><a href="#acl_role_ttl">`role_ttl`</a> - Used to control
Time-To-Live caching of ACL roles. By default, this is 30 seconds. This setting has a
major performance impact: reducing it will cause more frequent refreshes while increasing
it reduces the number of refreshes. However, because the caches are not actively invalidated,
ACL role may be stale up to the TTL value.
* <a name="acl_token_ttl"></a><a href="#acl_token_ttl">`token_ttl`</a> - Used to control
Time-To-Live caching of ACL tokens. By default, this is 30 seconds. This setting has a
major performance impact: reducing it will cause more frequent refreshes while increasing

5
website/source/docs/commands/_http_api_options_client.html.md
View File

@ -29,3 +29,8 @@
* `-token=<value>` - ACL token to use in the request. This can also be specified
via the `CONSUL_HTTP_TOKEN` environment variable. If unspecified, the query
will default to the token of the Consul agent at the HTTP address.
* `-token-file=<value>` - File containing the ACL token to use in the request
instead of one specified via the `-token` argument or `CONSUL_HTTP_TOKEN`
environment variable. This can also be specified via the
`CONSUL_HTTP_TOKEN_FILE` environment variable.

13
website/source/docs/commands/acl.html.md
View File

@ -75,11 +75,11 @@ Usage: consul acl <subcommand> [options] [args]
$ consul acl bootstrap
List all ACL Tokens:
List all ACL tokens:
$ consul acl token list
Create a new ACL Policy:
Create a new ACL policy:
$ consul acl policy create -name "new-policy" \
-description "This is an example policy" \
@ -94,10 +94,13 @@ Usage: consul acl <subcommand> [options] [args]
For more examples, ask for subcommand help or view the documentation.
Subcommands:
auth-method Manage Consul's ACL auth methods
binding-rule Manage Consul's ACL binding rules
bootstrap Bootstrap Consul's ACL system
policy Manage Consul's ACL Policies
set-agent-token Interact with the Consul's ACLs
token Manage Consul's ACL Tokens
policy Manage Consul's ACL policies
role Manage Consul's ACL roles
set-agent-token Assign tokens for the Consul Agent's usage
token Manage Consul's ACL tokens
translate-rules Translate the legacy rule syntax into the current syntax
```

433
website/source/docs/commands/acl/acl-policy.html.md.erb
View File

@ -1,433 +0,0 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Management"
sidebar_current: "docs-commands-acl-policy"
---
# Consul ACL Policies
Command: `consul acl policy`
The `acl policy` command is used to manage Consul's ACL policies. There are
subcommands for the individual operations that can be performed.
* [`create`](#create)
* [`read`](#read)
* [`update`](#update)
* [`delete`](#delete)
* [`list`](#list)
ACL policies are also accessible via the [HTTP API](/api/acl/acl.html).
Usage: `consul acl policy <subcommand> [options] [args]`
-> **Note:** All of the examples show for the subcommands will require a valid Consul token with the appropriate permissions.
Either set the `CONSUL_HTTP_TOKEN` environment variable to the tokens secret ID or pass the secret ID as the value of the `-token`
parameter.
## Identifying Policies
In several of the subcommands a policy will have to be identified to be read, modified or deleted. Those subcommands support
specifying the policy by its ID using the `-id` parameter or by name using the `-name` parameter. When specifying the policy
by its ID a unique policy ID prefix may be specified instead of the entire UUID. As long as it is unique it will be resolved
to the full UUID and used. Additionally builtin policy names will be accepted as the value to the `-id` parameter. Even if
the builtin policies are renamed their original name can be used to operate on them.
Builtin Policies:
| Policy UUID | Policy Name |
| ------------------------------------ | ----------------- |
| 00000000-0000-0000-0000-000000000001 | global-management |
## Common Subcommand Options
All of the `consul acl policy` subcommands support the following options:
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
## `create`
Command: `consul acl policy create`
This command creates new policies. The policies rules can either be set explicitly or the
`-from-token` parameter may be used to load the rules from a legacy ACL token. When loading
the rules from an existing legacy ACL token, the rules get translated from the legacy syntax
to the new syntax.
Both the `-rules` and `-from-token` parameter values allow loading the value
from stdin, a file or the raw value. To use stdin pass `-` as the value.
To load the value from a file prefix the value with an `@`. Any other
values will be used directly.
-> **Deprecated:** The `-from-token` and `-token-secret` arguments exist only as a convenience
to make legacy ACL migration easier. These will be removed in a future major release when
support for the legacy ACL system is removed.
### Usage
Usage: `consul acl policy create [options] [args]`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-description=<string>` - A description of the policy.
* `-from-token=<string>` - The legacy token to retrieve the rules for when creating this
policy. When this is specified no other rules should be given.
Similar to the -rules option the token to use can be loaded from
stdin or from a file.
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The new policy's name. This flag is required.
* `-rules=<string>` - The policy rules. May be prefixed with '@' to indicate that the
value is a file path to load the rules from. '-' may also be given
to indicate that the rules are available on stdin.
* `-token-secret` - Indicates the token provided with -from-token is a SecretID and not
an AccessorID.
* `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
This flag may be specified multiple times.
### Examples
Create a new policy that is valid in all datacenters:
```sh
$ consul acl policy create -name "acl-replication" -description "Policy capable of replicating ACL policies" -rules 'acl = "read"'
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Name: acl-replication
Description: Policy capable of replicating ACL policies
Datacenters:
Rules:
acl = "read"
```
Create a new policy valid only in specific datacenters with rules read from a file:
```sh
$ consul acl policy create -name "replication" -description "Replication" -rules @rules.hcl -valid-datacenter dc1 -valid-datacenter dc2
ID: ca44555b-a2d8-94de-d763-88caffdaf11f
Name: replication
Description: Replication
Datacenters: dc1, dc2
Rules:
acl = "read"
service_prefix "" {
policy = "read"
intentions = "read"
}
```
Create a new policy with rules equivalent to that of a legacy ACL token:
```sh
$ consul acl policy create -name "node-services-read" -from-token 5793a5ce -description "Can read any node and service"
ID: 06acc965-df4b-5a99-58cb-3250930c6324
Name: node-services-read
Description: Can read any node and service
Datacenters:
Rules:
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
```
## `read`
Command: `consul acl policy read`
This command reads and displays a policies details.
### Usage
Usage: `consul acl policy read [options] [args]`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple policy IDs.
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The name of the policy to read.
### Examples
Get policy details:
```sh
$ consul acl policy read -id 00000000-0000-0000-0000-000000000001
ID: 00000000-0000-0000-0000-000000000001
Name: global-management
Description: Builtin Policy that grants unlimited access
Datacenters:
Rules:
acl = "write"
agent_prefix "" {
policy = "write"
}
event_prefix "" {
policy = "write"
}
key_prefix "" {
policy = "write"
}
keyring = "write"
node_prefix "" {
policy = "write"
}
operator = "write"
query_prefix "" {
policy = "write"
}
service_prefix "" {
policy = "write"
intentions = "write"
}
session_prefix "" {
policy = "write"
}
```
Get policy details by name:
```sh
$ consul acl policy read -name "acl-replication"
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Name: acl-replication
Description: Token capable of replicating ACL policies
Datacenters:
Rules:
acl = "read"
```
Get policy details (Builtin Policies):
Builtin policies can be accessed by specifying their original name as the value to the `-id` parameter.
```sh
$ consul acl policy read -id global-management
ID: 00000000-0000-0000-0000-000000000001
Name: global-management
Description: Builtin Policy that grants unlimited access
Datacenters:
Hash: b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69
Create Index: 4
Modify Index: 4
Rules:
acl = "write"
agent_prefix "" {
policy = "write"
}
event_prefix "" {
policy = "write"
}
key_prefix "" {
policy = "write"
}
keyring = "write"
node_prefix "" {
policy = "write"
}
operator = "write"
query_prefix "" {
policy = "write"
}
service_prefix "" {
policy = "write"
intentions = "write"
}
session_prefix "" {
policy = "write"
}
```
## `update`
Command: `consul acl policy update`
This command is used to update a policy. The default operations is to merge the current policy
with those values provided to the command invocation. Therefore to update just one field, only
the `-id` or `-name` options and the option to modify must be provided. Note that renaming
policies requires both the `-id` and `-name` as the new name cannot yet be used to lookup the
policy.
### Usage
Usage: `consul acl policy update [options] [args]`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-description=<string>` - A description of the policy.
* `-id=<string>` - The ID of the policy to update. It may be specified as a
unique ID prefix but will error if the prefix matches multiple policy IDs
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry
* `-name=<string>` - The policies name.
* `-no-merge` - Do not merge the current policy information with what is provided
to the command. Instead overwrite all fields with the exception of
the policy ID which is immutable.
* `-rules=<string>` - The policy rules. May be prefixed with `@` to indicate that
the value is a file path to load the rules from. `-` may also be given to
indicate that the rules are available on stdin.
* `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
This flag may be specified multiple times.
### Examples
Update a policy:
```sh
$ consul acl policy update -id 35b8 -name "replication" -description "Policy capable of replication ACL policies and Intentions" -rules @rules.hcl
Policy updated successfully
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Name: replication
Description: Policy capable of replication ACL policies and Intentions
Datacenters:
Rules:
acl = "read"
service_prefix "" {
policy = "read"
intentions = "read"
}
```
Rename a policy:
```sh
$ consul acl policy update -id 35b8 -name "dc1-replication"
Policy updated successfully
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Name: dc1-replication
Description: Policy capable of replication ACL policies and Intentions
Datacenters: dc1
Rules:
acl = "read"
service_prefix "" {
policy = "read"
intentions = "read"
}
```
## `delete`
Command: `consul acl policy delete`
This command deletes a policy. Policies may be deleted by their ID or by name.
### Usage
Usage: `consul acl policy delete [options]`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-id=<string>` - The ID of the policy to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple policy IDs.
* `-name=<string>` - The Name of the policy to delete.
### Examples
Delete a policy:
```sh
$ consul acl policy delete -id 35b8
Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully
```
Delete a policy by name:
```sh
$ consul acl policy delete -name acl-replication
Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully
```
## `list`
Command: `consul acl policy list`
This command lists all policies. By default it will not show metadata.
### Usage
Usage: `consul acl policy list`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-meta` - Indicates that policy metadata such as the content hash and
Raft indices should be shown for each entry.
### Examples
Default listing.
```sh
$ consul acl policy list
global-management:
ID: 00000000-0000-0000-0000-000000000001
Description: Builtin Policy that grants unlimited access
Datacenters:
acl-replication:
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Description: Policy capable of replicating ACL policies
Datacenters:
```
Show Metadata.
```sh
$ consul acl policy list -meta
global-management:
ID: 00000000-0000-0000-0000-000000000001
Description: Builtin Policy that grants unlimited access
Datacenters:
Hash: b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69
Create Index: 4
Modify Index: 4
node-services-read:
ID: 06acc965-df4b-5a99-58cb-3250930c6324
Description: Can read any node and service
Datacenters:
Hash: 19d2a73dcd315506af73bfff1492779a0dc0235066fcac07f432fb2cc3402133
Create Index: 244
Modify Index: 244
acl-replication:
ID: ca44555b-a2d8-94de-d763-88caffdaf11f
Description: Token capable of replicating ACL policies
Datacenters: dc1, dc2
Hash: b94669679cc24e0d064412e4aa90b470b7f900a8e0801f65feaf1f7d716a5390
Create Index: 198
Modify Index: 198
```

363
website/source/docs/commands/acl/acl-token.html.md.erb
View File

@ -1,363 +0,0 @@
---
layout: "docs"
page_title: "Commands: ACL Token Management"
sidebar_current: "docs-commands-acl-token"
---
# Consul ACL Tokens
Command: `consul acl token`
The `acl token` command is used to manage Consul's ACL tokens. There are
subcommands for the individual operations that can be performed.
* [`create`](#create)
* [`clone`](#clone)
* [`read`](#read)
* [`update`](#update)
* [`delete`](#delete)
* [`list`](#list)
ACL tokens are also accessible via the [HTTP API](/api/acl/acl.html).
Usage: `consul acl token <subcommand> [options] [args]`
-> **Note:** All of the examples show for the subcommands will require a valid Consul token with the appropriate permissions.
Either set the `CONSUL_HTTP_TOKEN` environment variable to the tokens secret ID or pass the secret ID as the value of the `-token`
parameter.
## Identifying Tokens
In several of the subcommands a token will have to be identified to be read, modified or deleted. Those subcommands support
specifying the token by its ID using the `-id` parameter. The ID may be specified as a unique UUID prefix instead of the entire
UUID. As long as it is unique it will be resolve to the full UUID and used. Additionally builtin token names will be accepted as
the value of the `-id`.
Builtin Tokens:
| Token UUID | Token Name |
| ------------------------------------ | ----------------- |
| 00000000-0000-0000-0000-000000000002 | anonymous |
## Common Subcommand Options
All of the `consul acl token` subcommands support the following options:
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
## `create`
Command: `consul acl token create`
This command creates new tokens. When creating a new token, policies may be linked using
either the `-policy-id` or the `-policy-name options. When specifying policies by IDs you
may use a unique prefix of the UUID as a shortcut for specifying the entire UUID.
### Usage
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-accessor=<string>` - Create the token with this Accessor ID. It must be a UUID. If not
specified one will be auto-generated
* `-description=<string>` - A description of the token.
* `-local` - Create this as a datacenter local token.
* `-policy-id=<value>` - ID of a policy to use for this token. May be specified multiple times.
* `-policy-name=<value>` - Name of a policy to use for this token. May be specified multiple times.
* `-meta` - Indicates that token metadata such as the content hash and raft indices should be shown
for each entry.
* `-secret=<string>` - Create the token with this Secret ID. It must be a UUID. If not
specified one will be auto-generated.
**Note**: The SecretID is used to authorize operations against Consul and should
be generated from an appropriate cryptographic source.
### Examples
Create a new token:
```sh
$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
Description: Read Nodes and Services
Local: false
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
Create a new local token:
```sh
$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 -local
AccessorID: 4fdf0ec8-d251-3865-079c-7247c974fc50
SecretID: 02143514-abf2-6c23-0aa1-ec2107e68f6b
Description: Read Nodes and Services
Local: true
Create Time: 2018-10-22 15:34:19.330265 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
Create a new policy and link with policies by name:
```sh
$ consul acl token create -description "Super User" -policy-name global-management
AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa
SecretID: ada7f751-f654-8872-7f93-498e799158b6
Description: Super User
Local: false
Create Time: 2018-10-22 15:35:28.787003 -0400 EDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```
## `clone`
Command: `consul acl token clone`
This command clones an existing token.
### Usage
Usage: `consul acl token clone [options]
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-description=<string>` - A description of the new cloned token.
* `-id=<string>` - The Accessor ID of the token to clone. It may be specified
as a unique ID prefix but will error if the prefix matches multiple token
Accessor IDs. The special value of 'anonymous' may be provided instead of
the anonymous tokens accessor ID
### Examples
Clone a token:
```sh
$ consul acl token clone -id 59f8 -description "Clone of Super User"
Token cloned successfully.
AccessorID: dcfa52ed-9288-b3ff-056d-255ef69d2d88
SecretID: 0005d17e-5bb2-7e8b-7bfa-15f2eee9ad14
Description: Clone of Super User
Local: false
Create Time: 2018-10-22 16:26:02.909096 -0400 EDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```
## `read`
Command: `consul acl token read`
This command reads and displays a token details.
### Usage
Usage: `consul acl token read [options] [args]`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple policy IDs.
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
* `-self` - Indicates that the current HTTP token should be read by secret ID
instead of expecting a -id option.
### Examples
Get token details:
```sh
$ consul acl token read -id 986
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
Description: Read Nodes and Services
Local: false
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
Get token details using the token secret ID:
```sh
$consul acl token read -self
AccessorID: 4d123dff-f460-73c3-02c4-8dd64d136e01
SecretID: 86cddfb9-2760-d947-358d-a2811156bf31
Description: Bootstrap Token (Global Management)
Local: false
Create Time: 2018-10-22 11:27:04.479026 -0400 EDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```
Get token details (Builtin Tokens)
```sh
$ consul acl token read -id anonymous
AccessorID: 00000000-0000-0000-0000-000000000002
SecretID: anonymous
Description: Anonymous Token
Local: false
Create Time: 0001-01-01 00:00:00 +0000 UTC
Policies:
```
## `update`
Command: `consul acl token update`
This command will update a token. Some parts of the token like whether the
token is local to the datacenter cannot be changed.
### Usage
Usage: `consul acl token update [options]`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-description=<string>` - A description of the token
* `-id=<string>` - The Accessor ID of the token to read. It may be specified as a
unique ID prefix but will error if the prefix matches multiple token Accessor IDs
* `-merge-policies` - Merge the new policies with the existing policies
* `-meta` - Indicates that token metadata such as the content hash and Raft indices should be
shown for each entry.
* `-policy-id=<value>` - ID of a policy to use for this token. May be specified multiple times.
* `-policy-name=<value>` - Name of a policy to use for this token. May be specified multiple times.
### Examples
Update the anonymous token:
```sh
$ consul acl token update -id anonymous -policy-id 06acc
Token updated successfully.
AccessorID: 00000000-0000-0000-0000-000000000002
SecretID: anonymous
Description: Anonymous Token
Local: false
Create Time: 0001-01-01 00:00:00 +0000 UTC
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
Update a token description and take the policies from the existing token:
```sh
$ consul acl token update -id 986193 -description "WonderToken" -merge-policies
Token updated successfully.
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
Description: WonderToken
Local: false
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
## `delete`
Command: `consul acl token delete`
This command deletes a token.
### Usage
Usage: `consul acl token delete [options]`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-id=<string>` - The ID of the token to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple token IDs.
### Examples
Delete a token:
```sh
$ consul acl token delete -id 35b8
Token "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully
```
## `list`
Command: `consul acl token list`
This command lists all tokens. By default it will not show metadata.
### Usage
Usage: `consul acl token list`
#### Options
* [Common Subcommand Options](#common-subcommand-options)
* `-meta` - Indicates that token metadata such as the content hash and
Raft indices should be shown for each entry.
### Examples
Default listing.
```sh
$ consul acl token list
AccessorID: 4d123dff-f460-73c3-02c4-8dd64d136e01
Description: Bootstrap Token (Global Management)
Local: false
Create Time: 2018-10-22 11:27:04.479026 -0400 EDT
Legacy: false
Policies:
00000000-0000-0000-0000-000000000001 - global-management
AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa
Description: Super User
Local: false
Create Time: 2018-10-22 15:35:28.787003 -0400 EDT
Legacy: false
Policies:
00000000-0000-0000-0000-000000000001 - global-management
AccessorID: 00000000-0000-0000-0000-000000000002
Description: Anonymous Token
Local: false
Create Time: 0001-01-01 00:00:00 +0000 UTC
Legacy: false
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
Description: WonderToken
Local: false
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Legacy: false
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```

84
website/source/docs/commands/acl/auth-method.html.md.erb Normal file
View File

@ -0,0 +1,84 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Methods"
sidebar_current: "docs-commands-acl-auth-method"
---
# Consul ACL Auth Methods
Command: `consul acl auth-method`
The `acl auth-method` command is used to manage Consul's ACL auth methods.
It exposes commands for creating, updating, reading, deleting, and listing auth methods.
This command is available in Consul 1.5.0 and newer.
ACL auth methods may also be managed via the [HTTP API](/api/acl/auth-methods.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
## Usage
Usage: `consul acl auth-method <subcommand>`
For the exact documentation for your Consul version, run `consul acl
auth-method -h` to view the complete list of subcommands.
```text
Usage: consul acl auth-method <subcommand> [options] [args]
...
Subcommands:
create Create an ACL auth method
delete Delete an ACL auth method
list Lists ACL auth methods
read Read an ACL auth method
update Update an ACL auth method
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.
## Basic Examples
Create a new auth method:
```sh
$ consul acl auth-method create -type "kubernetes" \
-name "my-k8s" \
-description "This is an example kube auth method" \
-kubernetes-host "https://apiserver.example.com:8443" \
-kubernetes-ca-file /path/to/kube.ca.crt \
-kubernetes-service-account-jwt "JWT_CONTENTS"
```
List all auth methods:
```sh
$ consul acl auth-method list
```
Update all editable fields of the auth method:
```sh
$ consul acl auth-method update -name "my-k8s" \
-description "new description" \
-kubernetes-host "https://new-apiserver.example.com:8443" \
-kubernetes-ca-file /path/to/new-kube.ca.crt \
-kubernetes-service-account-jwt "NEW_JWT_CONTENTS"
```
Read an auth method:
```sh
$ consul acl auth-method read -name my-k8s
```
Delete an auth method:
```sh
$ consul acl auth-method delete -name my-k8s
```

64
website/source/docs/commands/acl/auth-method/create.html.md.erb Normal file
View File

@ -0,0 +1,64 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method Create"
sidebar_current: "docs-commands-acl-auth-method-create"
---
# Consul ACL Auth Method Create
Command: `consul acl auth-method create`
The `acl auth-method create` command creates new auth methods.
## Usage
Usage: `consul acl auth-method create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-description=<string>` - A description of the auth method.
* `-meta` - Indicates that auth method metadata such as the raft indices should
be shown for each entry.
* `-name=<string>` - The new auth method's name. This flag is required.
* `-type=<string>` - The new auth method's type. This flag is required.
* `-kubernetes-ca-cert=<string>` - PEM encoded CA cert for use by the TLS
client used to talk with the Kubernetes API. May be prefixed with '@' to
indicate that the value is a file path to load the cert from. This flag is
required for `-type=kubernetes`.
* `-kubernetes-host=<string>` - Address of the Kubernetes API server. This flag
is required for `-type=kubernetes`.
* `-kubernetes-service-account-jwt=<string>` - A Kubernetes service account JWT
used to access the TokenReview API to validate other JWTs during login. This
flag is required for `-type=kubernetes`.
## Examples
Create a new Kubernetes auth method:
```sh
$ consul acl auth-method create -name minikube -type kubernetes \
-description 'minikube auth method' \
-kubernetes-host 'https://192.0.2.42:8443' \
-kubernetes-ca-cert '@minikube-ca.crt' \
-kubernetes-service-account-jwt 'eyJhbGciOiJSUzI1NiIsImtpZCI...'
Name: minikube
Type: kubernetes
Description: minikube auth method
Config:
{
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"Host": "https://192.0.2.42:8443",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI..."
}
```

33
website/source/docs/commands/acl/auth-method/delete.html.md.erb Normal file
View File

@ -0,0 +1,33 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method Delete"
sidebar_current: "docs-commands-acl-auth-method-delete"
---
# Consul ACL Auth Method Delete
Command: `consul acl auth-method delete`
The `acl auth-method delete` command deletes an auth method.
## Usage
Usage: `consul acl auth-method delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-name=<string>` - The Name of the auth method to delete.
## Examples
Delete an auth method:
```sh
$ consul acl auth-method delete -name minikube
Auth-method "minikube" deleted successfully
```

55
website/source/docs/commands/acl/auth-method/list.html.md.erb Normal file
View File

@ -0,0 +1,55 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method List"
sidebar_current: "docs-commands-acl-auth-method-list"
---
# Consul ACL Auth Method List
Command: `consul acl auth-method list`
The `acl auth-method list`s command lists all auth methods. By default it will not show metadata.
## Usage
Usage: `consul acl auth-method list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-meta` - Indicates that auth method metadata such as the raft indices should
be shown for each entry.
## Examples
Default listing.
```sh
$ consul acl auth-method list
minikube:
Type: kubernetes
Description: minikube auth method
minikube-two:
Type: kubernetes
Description: dev cluster
```
Show Metadata.
```sh
$ consul acl auth-method list -meta
minikube:
Type: kubernetes
Description: minikube auth method
Create Index: 443
Modify Index: 443
minikube-two:
Type: kubernetes
Description: dev cluster
Create Index: 445
Modify Index: 445
```

44
website/source/docs/commands/acl/auth-method/read.html.md.erb Normal file
View File

@ -0,0 +1,44 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method Read"
sidebar_current: "docs-commands-acl-auth-method-read"
---
# Consul ACL Auth Method Read
Command: `consul acl auth-method read`
The `acl auth-method read` command reads and displays an auth method's details.
## Usage
Usage: `consul acl auth-method read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-meta` - Indicates that auth method metadata such as the raft
indices should be shown for each entry.
* `-name=<string>` - The name of the auth method to read.
## Examples
Get auth method details:
```sh
$ consul acl auth-method read -name minikube
Name: minikube
Type: kubernetes
Description: minikube auth method
Config:
{
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"Host": "https://192.0.2.42:8443",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI..."
}
```

67
website/source/docs/commands/acl/auth-method/update.html.md.erb Normal file
View File

@ -0,0 +1,67 @@
---
layout: "docs"
page_title: "Commands: ACL Auth Method Update"
sidebar_current: "docs-commands-acl-auth-method-update"
---
# Consul ACL Auth Method Update
Command: `consul acl auth-method update`
The `acl auth-method update` command is used to update an auth method. The
default operations is to merge the current auth method with those values
provided to the command invocation. Therefore to update just one field, only
the `-name` options and the option to modify must be provided.
## Usage
Usage: `consul acl auth-method update [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-description=<string>` - A description of the auth method.
* `-kubernetes-ca-cert=<string>` - PEM encoded CA cert for use by the TLS
client used to talk with the Kubernetes API. May be prefixed with '@' to
indicate that the value is a file path to load the cert from. This flag is
required for `-type=kubernetes`.
* `-kubernetes-host=<string>` - Address of the Kubernetes API server. This flag
is required for `-type=kubernetes`.
* `-kubernetes-service-account-jwt=<string>` - A Kubernetes service account JWT
used to access the TokenReview API to validate other JWTs during login. This
flag is required for `-type=kubernetes`.
* `-meta` - Indicates that auth method metadata such as the raft
indices should be shown for each entry
* `-name=<string>` - The name of the auth method to update.
* `-no-merge` - Do not merge the current auth method information with what is provided
to the command. Instead overwrite all fields with the exception of the auth method
ID which is immutable.
## Examples
Update an auth method:
```sh
$ consul acl auth-method update -name minikube \
-description 'dev cluster' \
-kubernetes-host 'https://192.0.2.44:8443'
Name: minikube
Type: kubernetes
Description: dev cluster
Config:
{
"CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
"Host": "https://192.0.2.44:8443",
"ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI..."
}
```

91
website/source/docs/commands/acl/binding-rule.html.md.erb Normal file
View File

@ -0,0 +1,91 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule"
sidebar_current: "docs-commands-acl-binding-rule"
---
# Consul ACL Binding Rules
Command: `consul acl binding-rule`
The `acl binding-rule` command is used to manage Consul's ACL binding rules.
It exposes commands for creating, updating, reading, deleting, and listing binding rules.
This command is available in Consul 1.5.0 and newer.
ACL binding rules may also be managed via the [HTTP API](/api/acl/binding-rules.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
## Usage
Usage: `consul acl binding-rule <subcommand>`
For the exact documentation for your Consul version, run `consul acl
binding-rule -h` to view the complete list of subcommands.
```text
Usage: consul acl binding-rule <subcommand> [options] [args]
...
Subcommands:
create Create an ACL binding rule
delete Delete an ACL binding rule
list Lists ACL binding rules
read Read an ACL binding rule
update Update an ACL binding rule
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.
## Identifying Binding Rules
Several of the subcommands need to operate on a specific binding rule. Those
subcommands support specifying the binding rule by its ID using the `-id`
parameter.
When specifying the binding rule by its ID a unique binding rule ID prefix may
be specified instead of the entire UUID. As long as it is unique it will be
resolved to the full UUID and used.
## Basic Examples
Create a new binding rule:
```sh
$ consul acl binding-rule create \
-method=minikube \
-bind-type=service \
-bind-name='k8s-${serviceaccount.name}' \
-selector='serviceaccount.namespace==default and serviceaccount.name==web'
```
List all binding rules:
```sh
$ consul acl binding-rule list
```
Update a binding rule:
```sh
$ consul acl binding-rule update -id=43cb72df-9c6f-4315-ac8a-01a9d98155ef \
-bind-name='k8s-${serviceaccount.name}'
```
Read a binding rule:
```sh
$ consul acl binding-rule read -id fdabbcb5-9de5-4b1a-961f-77214ae88cba
```
Delete a binding rule:
```sh
$ consul acl binding-rule delete -id b6b856da-5193-4e78-845a-7d61ca8371ba
```

72
website/source/docs/commands/acl/binding-rule/create.html.md.erb Normal file
View File

@ -0,0 +1,72 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule Create"
sidebar_current: "docs-commands-acl-binding-rule-create"
---
# Consul ACL Binding Rule Create
Command: `consul acl binding-rule create`
The `acl binding-rule create` command creates new binding rules.
## Usage
Usage: `consul acl binding-rule create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-bind-name=<string>` - Name to bind on match. Can use `${var}`
interpolation. This flag is required.
* `-bind-type=<string>` - Type of binding to perform (`"service"` or `"role"`).
* `-description=<string>` - A description of the binding rule.
* `-meta` - Indicates that binding rule metadata such as the raft
indices should be shown for each entry.
* `-method=<string>` - The auth method's name for which this binding rule
applies. This flag is required.
* `-selector=<string>` - Selector is an expression that matches against
verified identity attributes returned from the auth method during login.
## Examples
Create a new binding rule that binds to a service identity:
```sh
$ consul acl binding-rule create -method 'minikube' \
-description 'wildcard service' \
-bind-type 'service' \
-bind-name 'k8s-${serviceaccount.name}' \
-selector 'serviceaccount.namespace==default and serviceaccount.name!=vault'
ID: 0ec1bd2f-1d3b-bafb-d9bf-90ef04ab1890
AuthMethod: minikube
Description: wildcard service
BindType: service
BindName: k8s-${serviceaccount.name}
Selector: serviceaccount.namespace==default and serviceaccount.name!=vault
```
Create a new binding rule that binds to a role:
```sh
$ consul acl binding-rule create -method 'minikube' \
-description 'just vault role' \
-bind-type 'role' \
-bind-name 'vault' \
-selector 'serviceaccount.namespace==default and serviceaccount.name==vault'
ID: e21ae868-7b13-a230-0235-f8e83510642c
AuthMethod: minikube
Description: just vault role
BindType: role
BindName: vault
Selector: serviceaccount.namespace==default and serviceaccount.name==vault
```

34
website/source/docs/commands/acl/binding-rule/delete.html.md.erb Normal file
View File

@ -0,0 +1,34 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule Delete"
sidebar_current: "docs-commands-acl-binding-rule-delete"
---
# Consul ACL Binding Rule Delete
Command: `consul acl binding-rule delete`
The `acl binding-rule delete` command deletes a binding rule.
## Usage
Usage: `consul acl binding-rule delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<string>` - The ID of the binding rule to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple binding rule IDs.
## Examples
Delete a binding rule:
```sh
$ consul acl binding-rule delete -id 0ec1bd
Binding rule "0ec1bd2f-1d3b-bafb-d9bf-90ef04ab1890" deleted successfully
```

67
website/source/docs/commands/acl/binding-rule/list.html.md.erb Normal file
View File

@ -0,0 +1,67 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule List"
sidebar_current: "docs-commands-acl-binding-rule-list"
---
# Consul ACL Binding Rule List
Command: `consul acl binding-rule list`
The `acl binding-rule list` command lists all binding rules. By default it will not show metadata.
## Usage
Usage: `consul acl binding-rule list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-meta` - Indicates that binding rule metadata such as the raft indices
should be shown for each entry.
## Examples
Default listing.
```sh
$ consul acl binding-rule list
0ec1bd2f-1d3b-bafb-d9bf-90ef04ab1890:
AuthMethod: minikube
Description: wildcard service
BindType: service
BindName: k8s-${serviceaccount.name}
Selector: serviceaccount.namespace==default
e21ae868-7b13-a230-0235-f8e83510642c:
AuthMethod: minikube
Description: just vault role
BindType: role
BindName: vault
Selector: serviceaccount.namespace==default and serviceaccount.name==vault
```
Show Metadata.
```sh
$ consul acl binding-rule list -meta
0ec1bd2f-1d3b-bafb-d9bf-90ef04ab1890:
AuthMethod: minikube
Description: wildcard service
BindType: service
BindName: k8s-${serviceaccount.name}
Selector: serviceaccount.namespace==default
Create Index: 558
Modify Index: 583
e21ae868-7b13-a230-0235-f8e83510642c:
AuthMethod: minikube
Description: just vault role
BindType: role
BindName: vault
Selector: serviceaccount.namespace==default and serviceaccount.name==vault
Create Index: 593
Modify Index: 593
```

42
website/source/docs/commands/acl/binding-rule/read.html.md.erb Normal file
View File

@ -0,0 +1,42 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule Read"
sidebar_current: "docs-commands-acl-binding-rule-read"
---
# Consul ACL Binding Rule Read
Command: `consul acl binding-rule read`
The `acl binding-rule read` command reads and displays a binding rules details.
## Usage
Usage: `consul acl binding-rule read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<string>` - The ID of the binding rule to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple binding rule IDs.
* `-meta` - Indicates that binding rule metadata such as the raft
indices should be shown for each entry.
## Examples
Get binding rule details:
```sh
$ consul acl binding-rule read -id '0ec1bd2f-1d3b-bafb-d9bf-90ef04ab1890'
ID: 0ec1bd2f-1d3b-bafb-d9bf-90ef04ab1890
AuthMethod: minikube
Description: wildcard service
BindType: service
BindName: k8s-${serviceaccount.name}
Selector: serviceaccount.namespace==default and serviceaccount.name!=vault
```

61
website/source/docs/commands/acl/binding-rule/update.html.md.erb Normal file
View File

@ -0,0 +1,61 @@
---
layout: "docs"
page_title: "Commands: ACL Binding Rule Update"
sidebar_current: "docs-commands-acl-binding-rule-update"
---
# Consul ACL Binding Rule Update
Command: `consul acl binding-rule update`
The `acl binding-rule update` command is used to update a binding rule. The
default operations is to merge the current binding rule with those values
provided to the command invocation. Therefore to update just one field, only
the `-id` option and the option to modify must be provided.
## Usage
Usage: `consul acl binding-rule update [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-bind-name=<string>` - Name to bind on match. Can use `${var}`
interpolation. This flag is required.
* `-bind-type=<string>` - Type of binding to perform (`"service"` or `"role"`).
* `-description=<string>` - A description of the binding rule.
* `-id=<string>` - The ID of the binding rule to update. It may be specified as a
unique ID prefix but will error if the prefix matches multiple binding rule IDs
* `-meta` - Indicates that binding rule metadata such as the raft
indices should be shown for each entry.
* `-no-merge` - Do not merge the current binding rule information with what is
provided to the command. Instead overwrite all fields with the exception of the
binding rule ID which is immutable.
* `-selector=<string>` - Selector is an expression that matches against
verified identity attributes returned from the auth method during login.
## Examples
Update a binding rule:
```sh
$ consul acl binding-rule update -id '0ec1bd2f-1d3b-bafb-d9bf-90ef04ab1890' \
-selector 'serviceaccount.namespace==default'
Binding rule updated successfully
ID: 0ec1bd2f-1d3b-bafb-d9bf-90ef04ab1890
AuthMethod: minikube
Description: wildcard service
BindType: service
BindName: k8s-${serviceaccount.name}
Selector: serviceaccount.namespace==default
```

0
website/source/docs/commands/acl/acl-bootstrap.html.md.erb → website/source/docs/commands/acl/bootstrap.html.md.erb
View File

97
website/source/docs/commands/acl/policy.html.md.erb Normal file
View File

@ -0,0 +1,97 @@
---
layout: "docs"
page_title: "Commands: ACL Policy"
sidebar_current: "docs-commands-acl-policy"
---
# Consul ACL Policies
Command: `consul acl policy`
The `acl policy` command is used to manage Consul's ACL policies.
It exposes commands for creating, updating, reading, deleting, and listing policies.
This command is available in Consul 1.4.0 and newer.
ACL policies may also be managed via the [HTTP API](/api/acl/policies.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
## Usage
Usage: `consul acl policy <subcommand>`
For the exact documentation for your Consul version, run `consul acl
policy -h` to view the complete list of subcommands.
```text
Usage: consul acl policy <subcommand> [options] [args]
...
Subcommands:
create Create an ACL policy
delete Delete an ACL policy
list Lists ACL policies
read Read an ACL policy
update Update an ACL policy
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.
## Identifying Policies
Several of the subcommands need to operate on a specific policy. Those
subcommands support specifying the policy by its ID using the `-id` parameter
or by name using the `-name` parameter.
When specifying the policy by its ID a unique policy ID prefix may be specified
instead of the entire UUID. As long as it is unique it will be resolved to the
full UUID and used. Additionally builtin policy names will be accepted as the
value to the `-id` parameter. Even if the builtin policies are renamed their
original name can be used to operate on them.
Builtin policies:
| Policy UUID | Policy Name |
| ------------------------------------ | ----------------- |
| 00000000-0000-0000-0000-000000000001 | global-management |
## Basic Examples
Create a new ACL policy:
```sh
$ consul acl policy create -name "new-policy" \
-description "This is an example policy" \
-datacenter "dc1" \
-datacenter "dc2" \
-rules @rules.hcl
```
List all policies:
```sh
$ consul acl policy list
```
Update a policy:
```sh
$ consul acl policy update -name "other-policy" -datacenter "dc1"
```
Read a policy:
```sh
$ consul acl policy read -id 0479e93e-091c-4475-9b06-79a004765c24
```
Delete a policy
```sh
$ consul acl policy delete -name "my-policy"
```

104
website/source/docs/commands/acl/policy/create.html.md.erb Normal file
View File

@ -0,0 +1,104 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Create"
sidebar_current: "docs-commands-acl-policy-create"
---
# Consul ACL Policy Create
Command: `consul acl policy create`
The `acl policy create` command creates new policies. The policies rules can either be set explicitly or the
`-from-token` parameter may be used to load the rules from a legacy ACL token. When loading
the rules from an existing legacy ACL token, the rules get translated from the legacy syntax
to the new syntax.
Both the `-rules` and `-from-token` parameter values allow loading the value
from stdin, a file or the raw value. To use stdin pass `-` as the value.
To load the value from a file prefix the value with an `@`. Any other
values will be used directly.
-> **Deprecated:** The `-from-token` and `-token-secret` arguments exist only as a convenience
to make legacy ACL migration easier. These will be removed in a future major release when
support for the legacy ACL system is removed.
## Usage
Usage: `consul acl policy create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-description=<string>` - A description of the policy.
* `-from-token=<string>` - The legacy token to retrieve the rules for when creating this
policy. When this is specified no other rules should be given.
Similar to the -rules option the token to use can be loaded from
stdin or from a file.
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The new policy's name. This flag is required.
* `-rules=<string>` - The policy rules. May be prefixed with '@' to indicate that the
value is a file path to load the rules from. '-' may also be given
to indicate that the rules are available on stdin.
* `-token-secret` - Indicates the token provided with -from-token is a SecretID and not
an AccessorID.
* `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
This flag may be specified multiple times.
## Examples
Create a new policy that is valid in all datacenters:
```sh
$ consul acl policy create -name "acl-replication" -description "Policy capable of replicating ACL policies" -rules 'acl = "read"'
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Name: acl-replication
Description: Policy capable of replicating ACL policies
Datacenters:
Rules:
acl = "read"
```
Create a new policy valid only in specific datacenters with rules read from a file:
```sh
$ consul acl policy create -name "replication" -description "Replication" -rules @rules.hcl -valid-datacenter dc1 -valid-datacenter dc2
ID: ca44555b-a2d8-94de-d763-88caffdaf11f
Name: replication
Description: Replication
Datacenters: dc1, dc2
Rules:
acl = "read"
service_prefix "" {
policy = "read"
intentions = "read"
}
```
Create a new policy with rules equivalent to that of a legacy ACL token:
```sh
$ consul acl policy create -name "node-services-read" -from-token 5793a5ce -description "Can read any node and service"
ID: 06acc965-df4b-5a99-58cb-3250930c6324
Name: node-services-read
Description: Can read any node and service
Datacenters:
Rules:
service_prefix "" {
policy = "read"
}
node_prefix "" {
policy = "read"
}
```

43
website/source/docs/commands/acl/policy/delete.html.md.erb Normal file
View File

@ -0,0 +1,43 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Delete"
sidebar_current: "docs-commands-acl-policy-delete"
---
# Consul ACL Policy Delete
Command: `consul acl policy delete`
The `acl policy delete` command deletes a policy. Policies may be deleted by their ID or by name.
## Usage
Usage: `consul acl policy delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<string>` - The ID of the policy to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple policy IDs.
* `-name=<string>` - The Name of the policy to delete.
## Examples
Delete a policy:
```sh
$ consul acl policy delete -id 35b8
Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully
```
Delete a policy by name:
```sh
$ consul acl policy delete -name acl-replication
Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully
```

68
website/source/docs/commands/acl/policy/list.html.md.erb Normal file
View File

@ -0,0 +1,68 @@
---
layout: "docs"
page_title: "Commands: ACL Policy List"
sidebar_current: "docs-commands-acl-policy-list"
---
# Consul ACL Policy List
Command: `consul acl policy list`
The `acl policy list` command lists all policies. By default it will not show metadata.
## Usage
Usage: `consul acl policy list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-meta` - Indicates that policy metadata such as the content hash and
Raft indices should be shown for each entry.
## Examples
Default listing.
```sh
$ consul acl policy list
global-management:
ID: 00000000-0000-0000-0000-000000000001
Description: Builtin Policy that grants unlimited access
Datacenters:
acl-replication:
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Description: Policy capable of replicating ACL policies
Datacenters:
```
Show Metadata.
```sh
$ consul acl policy list -meta
global-management:
ID: 00000000-0000-0000-0000-000000000001
Description: Builtin Policy that grants unlimited access
Datacenters:
Hash: b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69
Create Index: 4
Modify Index: 4
node-services-read:
ID: 06acc965-df4b-5a99-58cb-3250930c6324
Description: Can read any node and service
Datacenters:
Hash: 19d2a73dcd315506af73bfff1492779a0dc0235066fcac07f432fb2cc3402133
Create Index: 244
Modify Index: 244
acl-replication:
ID: ca44555b-a2d8-94de-d763-88caffdaf11f
Description: Token capable of replicating ACL policies
Datacenters: dc1, dc2
Hash: b94669679cc24e0d064412e4aa90b470b7f900a8e0801f65feaf1f7d716a5390
Create Index: 198
Modify Index: 198
```

123
website/source/docs/commands/acl/policy/read.html.md.erb Normal file
View File

@ -0,0 +1,123 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Read"
sidebar_current: "docs-commands-acl-policy-read"
---
# Consul ACL Policy Read
Command: `consul acl policy read`
The `acl policy read` command reads and displays a policies details.
## Usage
Usage: `consul acl policy read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple policy IDs.
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The name of the policy to read.
## Examples
Get policy details:
```sh
$ consul acl policy read -id 00000000-0000-0000-0000-000000000001
ID: 00000000-0000-0000-0000-000000000001
Name: global-management
Description: Builtin Policy that grants unlimited access
Datacenters:
Rules:
acl = "write"
agent_prefix "" {
policy = "write"
}
event_prefix "" {
policy = "write"
}
key_prefix "" {
policy = "write"
}
keyring = "write"
node_prefix "" {
policy = "write"
}
operator = "write"
query_prefix "" {
policy = "write"
}
service_prefix "" {
policy = "write"
intentions = "write"
}
session_prefix "" {
policy = "write"
}
```
Get policy details by name:
```sh
$ consul acl policy read -name "acl-replication"
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Name: acl-replication
Description: Token capable of replicating ACL policies
Datacenters:
Rules:
acl = "read"
```
Get policy details (Builtin Policies):
Builtin policies can be accessed by specifying their original name as the value to the `-id` parameter.
```sh
$ consul acl policy read -id global-management
ID: 00000000-0000-0000-0000-000000000001
Name: global-management
Description: Builtin Policy that grants unlimited access
Datacenters:
Hash: b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69
Create Index: 4
Modify Index: 4
Rules:
acl = "write"
agent_prefix "" {
policy = "write"
}
event_prefix "" {
policy = "write"
}
key_prefix "" {
policy = "write"
}
keyring = "write"
node_prefix "" {
policy = "write"
}
operator = "write"
query_prefix "" {
policy = "write"
}
service_prefix "" {
policy = "write"
intentions = "write"
}
session_prefix "" {
policy = "write"
}
```

85
website/source/docs/commands/acl/policy/update.html.md.erb Normal file
View File

@ -0,0 +1,85 @@
---
layout: "docs"
page_title: "Commands: ACL Policy Update"
sidebar_current: "docs-commands-acl-policy-update"
---
# Consul ACL Policy Update
Command: `consul acl policy update`
The `acl policy update` command is used to update a policy. The default operations is to merge the current policy
with those values provided to the command invocation. Therefore to update just one field, only
the `-id` or `-name` options and the option to modify must be provided. Note that renaming
policies requires both the `-id` and `-name` as the new name cannot yet be used to lookup the
policy.
## Usage
Usage: `consul acl policy update [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-description=<string>` - A description of the policy.
* `-id=<string>` - The ID of the policy to update. It may be specified as a
unique ID prefix but will error if the prefix matches multiple policy IDs
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry
* `-name=<string>` - The policy's name.
* `-no-merge` - Do not merge the current policy information with what is provided
to the command. Instead overwrite all fields with the exception of
the policy ID which is immutable.
* `-rules=<string>` - The policy rules. May be prefixed with `@` to indicate that
the value is a file path to load the rules from. `-` may also be given to
indicate that the rules are available on stdin.
* `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
This flag may be specified multiple times.
## Examples
Update a policy:
```sh
$ consul acl policy update -id 35b8 -name "replication" -description "Policy capable of replication ACL policies and Intentions" -rules @rules.hcl
Policy updated successfully
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Name: replication
Description: Policy capable of replication ACL policies and Intentions
Datacenters:
Rules:
acl = "read"
service_prefix "" {
policy = "read"
intentions = "read"
}
```
Rename a policy:
```sh
$ consul acl policy update -id 35b8 -name "dc1-replication"
Policy updated successfully
ID: 35b8ecb0-707c-ee18-2002-81b238b54b38
Name: dc1-replication
Description: Policy capable of replication ACL policies and Intentions
Datacenters: dc1
Rules:
acl = "read"
service_prefix "" {
policy = "read"
intentions = "read"
}
```

87
website/source/docs/commands/acl/role.html.md.erb Normal file
View File

@ -0,0 +1,87 @@
---
layout: "docs"
page_title: "Commands: ACL Role"
sidebar_current: "docs-commands-acl-role"
---
# Consul ACL Roles
Command: `consul acl role`
The `acl role` command is used to manage Consul's ACL roles.
It exposes commands for creating, updating, reading, deleting, and listing roles.
This command is available in Consul 1.5.0 and newer.
ACL roles may also be managed via the [HTTP API](/api/acl/roles.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
## Usage
Usage: `consul acl role <subcommand>`
For the exact documentation for your Consul version, run `consul acl
role -h` to view the complete list of subcommands.
```text
Usage: consul acl role <subcommand> [options] [args]
...
Subcommands:
create Create an ACL role
delete Delete an ACL role
list Lists ACL roles
read Read an ACL role
update Update an ACL role
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.
## Identifying Roles
Several of the subcommands need to operate on a specific role. Those
subcommands support specifying the role by its ID using the `-id` parameter
or by name using the `-name` parameter.
When specifying the role by its ID a unique role ID prefix may be specified
instead of the entire UUID. As long as it is unique it will be resolved to the
full UUID and used.
## Basic Examples
Create a new ACL role:
```sh
$ consul acl role create -name "new-role" \
-description "This is an example role" \
-policy-id 06acc965
```
List all roles:
```sh
$ consul acl role list
```
Update a role:
```sh
$ consul acl role update -name "other-role" -datacenter "dc1"
```
Read a role:
```sh
$ consul acl role read -id 0479e93e-091c-4475-9b06-79a004765c24
```
Delete a role
```sh
$ consul acl role delete -name "my-role"
```

63
website/source/docs/commands/acl/role/create.html.md.erb Normal file
View File

@ -0,0 +1,63 @@
---
layout: "docs"
page_title: "Commands: ACL Role Create"
sidebar_current: "docs-commands-acl-role-create"
---
# Consul ACL Role Create
Command: `consul acl role create`
The `acl role create` command creates new roles.
## Usage
Usage: `consul acl role create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-description=<string>` - A description of the role.
* `-meta` - Indicates that role metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The new role's name. This flag is required.
* `-policy-id=<value>` - ID of a policy to use for this role. May be specified
multiple times
* `-policy-name=<value>` - Name of a policy to use for this role. May be
specified multiple times
* `-service-identity=<value>` - Name of a service identity to use for this
role. May be specified multiple times. Format is the `SERVICENAME` or
`SERVICENAME:DATACENTER1,DATACENTER2,...`
## Examples
Create a new role with one policy:
```sh
$ consul acl role create -name "crawler" -description "web crawler role" -policy-name "crawler-kv"
ID: 57147d87-6bf7-f794-1a6e-7d038c4e4ae9
Name: crawler
Description: web crawler role
Policies:
2f8f99c7-edd9-2f09-7e4b-a1f519eb4fc2 - crawler-kv
```
Create a new role with one service identity:
```sh
$ consul acl role create -name archiver -description 'archiver role' -service-identity "archiver:dc2"
ID: a365fdc9-ac71-e754-0645-7ab6bd747301
Name: archiver
Description: archiver role
Service Identities:
archiver (Datacenters: dc2)
```

43
website/source/docs/commands/acl/role/delete.html.md.erb Normal file
View File

@ -0,0 +1,43 @@
---
layout: "docs"
page_title: "Commands: ACL Role Delete"
sidebar_current: "docs-commands-acl-role-delete"
---
# Consul ACL Role Delete
Command: `consul acl role delete`
The `acl role delete` command deletes a role. Roles may be deleted by their ID or by name.
## Usage
Usage: `consul acl role delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<string>` - The ID of the role to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple role IDs.
* `-name=<string>` - The Name of the role to delete.
## Examples
Delete a role by prefix:
```sh
$ consul acl role delete -id 57147
Role "57147d87-6bf7-f794-1a6e-7d038c4e4ae9" deleted successfully
```
Delete a role by name:
```sh
$ consul acl role delete -name crawler
Role "a365fdc9-ac71-e754-0645-7ab6bd747301" deleted successfully
```

69
website/source/docs/commands/acl/role/list.html.md.erb Normal file
View File

@ -0,0 +1,69 @@
---
layout: "docs"
page_title: "Commands: ACL Role List"
sidebar_current: "docs-commands-acl-role-list"
---
# Consul ACL Role List
Command: `consul acl role list`
The `acl role list` command lists all roles. By default it will not show metadata.
## Usage
Usage: `consul acl role list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-meta` - Indicates that role metadata such as the content hash and
Raft indices should be shown for each entry.
## Examples
Default listing.
```sh
$ consul acl role list
web-crawler:
ID: 57147d87-6bf7-f794-1a6e-7d038c4e4ae9
Description: web crawler updated role
Policies:
2f8f99c7-edd9-2f09-7e4b-a1f519eb4fc2 - crawler-kv
Service Identities:
crawler (Datacenters: all)
archiver:
ID: a365fdc9-ac71-e754-0645-7ab6bd747301
Description: archiver role
Service Identities:
archiver (Datacenters: dc2)
```
Show Metadata.
```sh
$ consul acl role list -meta
web-crawler:
ID: 57147d87-6bf7-f794-1a6e-7d038c4e4ae9
Description: web crawler updated role
Hash: 3bd7c15a77c8d1d45c515378f1176df2e6f76d9c96d541f96de8272ff4dba7b5
Create Index: 18
Modify Index: 39
Policies:
2f8f99c7-edd9-2f09-7e4b-a1f519eb4fc2 - crawler-kv
Service Identities:
crawler (Datacenters: all)
archiver:
ID: a365fdc9-ac71-e754-0645-7ab6bd747301
Description: archiver role
Hash: 9af397ea92ee901366d6333c658195be16f4aee8aa64d2b529b921c879b70a58
Create Index: 22
Modify Index: 22
Service Identities:
archiver (Datacenters: dc2)
```

54
website/source/docs/commands/acl/role/read.html.md.erb Normal file
View File

@ -0,0 +1,54 @@
---
layout: "docs"
page_title: "Commands: ACL Role Read"
sidebar_current: "docs-commands-acl-role-read"
---
# Consul ACL Role Read
Command: `consul acl role read`
The `acl role read` command reads and displays a roles details.
## Usage
Usage: `consul acl role read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<string>` - The ID of the role to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple role IDs.
* `-meta` - Indicates that role metadata such as the content hash and raft
indices should be shown for each entry.
* `-name=<string>` - The name of the role to read.
## Examples
Get role details:
```sh
$ consul acl role read -id 57147d87-6bf7-f794-1a6e-7d038c4e4ae9
ID: 57147d87-6bf7-f794-1a6e-7d038c4e4ae9
Name: crawler
Description: web crawler role
Policies:
2f8f99c7-edd9-2f09-7e4b-a1f519eb4fc2 - crawler-kv
```
Get role details by name:
```sh
$ consul acl role read -name archiver
ID: a365fdc9-ac71-e754-0645-7ab6bd747301
Name: archiver
Description: archiver role
Service Identities:
archiver (Datacenters: dc2)
```

81
website/source/docs/commands/acl/role/update.html.md.erb Normal file
View File

@ -0,0 +1,81 @@
---
layout: "docs"
page_title: "Commands: ACL Role Update"
sidebar_current: "docs-commands-acl-role-update"
---
# Consul ACL Role Update
Command: `consul acl role update`
The `acl role update` command is used to update a role. The default operations is to merge the
current role with those values provided to the command invocation. Therefore to
update just one field, only the `-id` or `-name` options and the option to
modify must be provided. Note that renaming roles requires both the `-id` and
`-name` as the new name cannot yet be used to lookup the role.
## Usage
Usage: `consul acl role update [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-description=<string>` - A description of the role.
* `-id=<string>` - The ID of the role to update. It may be specified as a
unique ID prefix but will error if the prefix matches multiple role IDs
* `-meta` - Indicates that role metadata such as the content hash and raft
indices should be shown for each entry
* `-name=<string>` - The role name.
* `-no-merge` - Do not merge the current role information with what is provided
to the command. Instead overwrite all fields with the exception of the role
ID which is immutable.
* `-policy-id=<value>` - ID of a policy to use for this role. May be specified
multiple times
* `-policy-name=<value>` - Name of a policy to use for this role. May be
specified multiple times
* `-service-identity=<value>` - Name of a service identity to use for this
role. May be specified multiple times. Format is the `SERVICENAME` or
`SERVICENAME:DATACENTER1,DATACENTER2,...`
## Examples
Update a role:
```sh
$ consul acl role update -id 57147d87-6bf7-f794-1a6e-7d038c4e4ae9 \
-description 'web crawler updated role' -service-identity 'crawler'
Role updated successfully
ID: 57147d87-6bf7-f794-1a6e-7d038c4e4ae9
Name: crawler
Description: web crawler updated role
Policies:
2f8f99c7-edd9-2f09-7e4b-a1f519eb4fc2 - crawler-kv
Service Identities:
crawler (Datacenters: all)
```
Rename a role by prefix:
```sh
$ consul acl role update -id 57147 -name web-crawler
Role updated successfully
ID: 57147d87-6bf7-f794-1a6e-7d038c4e4ae9
Name: web-crawler
Description: web crawler updated role
Policies:
2f8f99c7-edd9-2f09-7e4b-a1f519eb4fc2 - crawler-kv
Service Identities:
crawler (Datacenters: all)
```

0
website/source/docs/commands/acl/acl-set-agent-token.html.md.erb → website/source/docs/commands/acl/set-agent-token.html.md.erb
View File

93
website/source/docs/commands/acl/token.html.md.erb Normal file
View File

@ -0,0 +1,93 @@
---
layout: "docs"
page_title: "Commands: ACL Token"
sidebar_current: "docs-commands-acl-token"
---
# Consul ACL Tokens
Command: `consul acl token`
The `acl token` command is used to manage Consul's ACL tokens.
It exposes commands for creating, updating, reading, deleting, and listing tokens.
This command is available in Consul 1.4.0 and newer.
ACL tokens may also be managed via the [HTTP API](/api/acl/tokens.html).
-> **Note:** All of the example subcommands in this document will require a valid
Consul token with the appropriate permissions. Either set the
`CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
secret ID as the value of the `-token` parameter.
## Usage
Usage: `consul acl token <subcommand>`
For the exact documentation for your Consul version, run `consul acl
token -h` to view the complete list of subcommands.
```text
Usage: consul acl token <subcommand> [options] [args]
...
Subcommands:
clone Clone an ACL token
create Create an ACL token
delete Delete an ACL token
list List ACL tokens
read Read an ACL token
update Update an ACL token
```
For more information, examples, and usage about a subcommand, click on the name
of the subcommand in the sidebar.
## Identifying Tokens
Several of the subcommands need to operate on a specific token. Those
subcommands support specifying the token by its ID using the `-id` parameter.
The ID may be specified as a unique UUID prefix instead of the entire UUID. As
long as it is unique it will be resolve to the full UUID and used. Additionally
builtin token names will be accepted as the value of the `-id`.
Builtin Tokens:
| Token UUID | Token Name |
| ------------------------------------ | ----------------- |
| 00000000-0000-0000-0000-000000000002 | anonymous |
## Basic Examples
Create a new ACL token:
```sh
$ consul acl token create \
-description "This is an example token" \
-policy-id 06acc965
```
List all tokens:
```sh
$ consul acl token list
```
Update a token:
```sh
$ consul acl token update -id 986193 -description "WonderToken"
```
Read a token with an accessor ID:
```sh
$ consul acl token read -id 986193
```
Delete a token
```sh
$ consul acl token delete -id 986193
```

45
website/source/docs/commands/acl/token/clone.html.md.erb Normal file
View File

@ -0,0 +1,45 @@
---
layout: "docs"
page_title: "Commands: ACL Token Clone"
sidebar_current: "docs-commands-acl-token-clone"
---
# Consul ACL Token Clone
Command: `consul acl token clone`
The `acl token clone` command clones an existing token.
## Usage
Usage: `consul acl token clone [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-description=<string>` - A description of the new cloned token.
* `-id=<string>` - The Accessor ID of the token to clone. It may be specified
as a unique ID prefix but will error if the prefix matches multiple token
Accessor IDs. The special value of 'anonymous' may be provided instead of
the anonymous tokens accessor ID
## Examples
Clone a token:
```sh
$ consul acl token clone -id 59f8 -description "Clone of Super User"
Token cloned successfully.
AccessorID: dcfa52ed-9288-b3ff-056d-255ef69d2d88
SecretID: 0005d17e-5bb2-7e8b-7bfa-15f2eee9ad14
Description: Clone of Super User
Local: false
Create Time: 2018-10-22 16:26:02.909096 -0400 EDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```

108
website/source/docs/commands/acl/token/create.html.md.erb Normal file
View File

@ -0,0 +1,108 @@
---
layout: "docs"
page_title: "Commands: ACL Token Create"
sidebar_current: "docs-commands-acl-token-create"
---
# Consul ACL Token Create
Command: `consul acl token create`
This command creates new tokens. When creating a new token, policies may be linked using
either the `-policy-id` or the `-policy-name` options. When specifying policies by IDs you
may use a unique prefix of the UUID as a shortcut for specifying the entire UUID.
## Usage
Usage: `consul acl token create [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-accessor=<string>` - Create the token with this Accessor ID. It must be a UUID. If not
specified one will be auto-generated
* `-description=<string>` - A description of the token.
* `-expires-ttl=<duration>` - Duration of time this token should be valid for.
* `-local` - Create this as a datacenter local token.
* `-meta` - Indicates that token metadata such as the content hash and raft indices should be shown
for each entry.
* `-policy-id=<value>` - ID of a policy to use for this token. May be specified multiple times.
* `-policy-name=<value>` - Name of a policy to use for this token. May be specified multiple times.
* `-role-id=<value>` - ID of a role to use for this token. May be specified multiple times.
* `-role-name=<value>` - Name of a role to use for this token. May be specified multiple times.
* `-service-identity=<value>` - Name of a service identity to use for this
token. May be specified multiple times. Format is the `SERVICENAME` or
`SERVICENAME:DATACENTER1,DATACENTER2,...`
* `-secret=<string>` - Create the token with this Secret ID. It must be a UUID. If not
specified one will be auto-generated.
**Note**: The SecretID is used to authorize operations against Consul and should
be generated from an appropriate cryptographic source.
## Examples
Create a new token:
```sh
$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
Description: Read Nodes and Services
Local: false
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
Create a new local token:
```sh
$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 -local
AccessorID: 4fdf0ec8-d251-3865-079c-7247c974fc50
SecretID: 02143514-abf2-6c23-0aa1-ec2107e68f6b
Description: Read Nodes and Services
Local: true
Create Time: 2018-10-22 15:34:19.330265 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
Create a new token and link with policies by name:
```sh
$ consul acl token create -description "Super User" -policy-name global-management
AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa
SecretID: ada7f751-f654-8872-7f93-498e799158b6
Description: Super User
Local: false
Create Time: 2018-10-22 15:35:28.787003 -0400 EDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```
Create a new token with one service identity that expires in 15 minutes:
```sh
$ consul acl token create -description 'crawler token' -service-identity 'crawler' -expires-ttl '15m'
AccessorID: 0c083aca-6c15-f0cc-c4d9-30578db54cd9
SecretID: 930dafb6-5c08-040b-23fb-a368a95256f9
Description: crawler token
Local: false
Create Time: 2019-04-25 16:45:49.337687334 -0500 CDT
Expiration Time: 2019-04-25 17:00:49.337687334 -0500 CDT
Service Identities:
crawler (Datacenters: all)
```

34
website/source/docs/commands/acl/token/delete.html.md.erb Normal file
View File

@ -0,0 +1,34 @@
---
layout: "docs"
page_title: "Commands: ACL Token Delete"
sidebar_current: "docs-commands-acl-token-delete"
---
# Consul ACL Token Delete
Command: `consul acl token delete`
The `acl token delete` command deletes a token.
## Usage
Usage: `consul acl token delete [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<string>` - The ID of the token to delete. It may be specified as a
unique ID prefix but will error if the prefix matches multiple token IDs.
## Examples
Delete a token:
```sh
$ consul acl token delete -id 35b8
Token "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully
```

64
website/source/docs/commands/acl/token/list.html.md.erb Normal file
View File

@ -0,0 +1,64 @@
---
layout: "docs"
page_title: "Commands: ACL Token List"
sidebar_current: "docs-commands-acl-token-list"
---
# Consul ACL Token List
Command: `consul acl token list`
The `acl token list` command lists all tokens. By default it will not show metadata.
## Usage
Usage: `consul acl token list`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-meta` - Indicates that token metadata such as the content hash and
Raft indices should be shown for each entry.
## Examples
Default listing.
```sh
$ consul acl token list
AccessorID: 4d123dff-f460-73c3-02c4-8dd64d136e01
Description: Bootstrap Token (Global Management)
Local: false
Create Time: 2018-10-22 11:27:04.479026 -0400 EDT
Legacy: false
Policies:
00000000-0000-0000-0000-000000000001 - global-management
AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa
Description: Super User
Local: false
Create Time: 2018-10-22 15:35:28.787003 -0400 EDT
Legacy: false
Policies:
00000000-0000-0000-0000-000000000001 - global-management
AccessorID: 00000000-0000-0000-0000-000000000002
Description: Anonymous Token
Local: false
Create Time: 0001-01-01 00:00:00 +0000 UTC
Legacy: false
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
Description: WonderToken
Local: false
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Legacy: false
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```

71
website/source/docs/commands/acl/token/read.html.md.erb Normal file
View File

@ -0,0 +1,71 @@
---
layout: "docs"
page_title: "Commands: ACL Token Read"
sidebar_current: "docs-commands-acl-token-read"
---
# Consul ACL Token Read
Command: `consul acl token read`
The `acl token read` command reads and displays a token details.
## Usage
Usage: `consul acl token read [options] [args]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID
prefix but will error if the prefix matches multiple policy IDs.
* `-meta` - Indicates that policy metadata such as the content hash and raft
indices should be shown for each entry.
* `-self` - Indicates that the current HTTP token should be read by secret ID
instead of expecting a -id option.
## Examples
Get token details:
```sh
$ consul acl token read -id 986
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
Description: Read Nodes and Services
Local: false
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
Get token details using the token secret ID:
```sh
$consul acl token read -self
AccessorID: 4d123dff-f460-73c3-02c4-8dd64d136e01
SecretID: 86cddfb9-2760-d947-358d-a2811156bf31
Description: Bootstrap Token (Global Management)
Local: false
Create Time: 2018-10-22 11:27:04.479026 -0400 EDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```
Get token details (Builtin Tokens)
```sh
$ consul acl token read -id anonymous
AccessorID: 00000000-0000-0000-0000-000000000002
SecretID: anonymous
Description: Anonymous Token
Local: false
Create Time: 0001-01-01 00:00:00 +0000 UTC
Policies:
```

79
website/source/docs/commands/acl/token/update.html.md.erb Normal file
View File

@ -0,0 +1,79 @@
---
layout: "docs"
page_title: "Commands: ACL Token Update"
sidebar_current: "docs-commands-acl-token-update"
---
# Consul ACL Token Update
Command: `consul acl token update`
The `acl token update` command will update a token. Some parts of the token like whether the
token is local to the datacenter cannot be changed.
## Usage
Usage: `consul acl token update [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Command Options
* `-description=<string>` - A description of the token
* `-id=<string>` - The Accessor ID of the token to read. It may be specified as a
unique ID prefix but will error if the prefix matches multiple token Accessor IDs
* `-merge-policies` - Merge the new policies with the existing policies.
* `-merge-roles` - Merge the new roles with the existing roles.
* `-merge-service-identities` - Merge the new service identities with the existing service identities.
* `-meta` - Indicates that token metadata such as the content hash and Raft indices should be
shown for each entry.
* `-policy-id=<value>` - ID of a policy to use for this token. May be specified multiple times.
* `-policy-name=<value>` - Name of a policy to use for this token. May be specified multiple times.
* `-role-id=<value>` - ID of a role to use for this token. May be specified multiple times.
* `-role-name=<value>` - Name of a role to use for this token. May be specified multiple times.
* `-service-identity=<value>` - Name of a service identity to use for this
token. May be specified multiple times. Format is the `SERVICENAME` or
`SERVICENAME:DATACENTER1,DATACENTER2,...`
## Examples
Update the anonymous token:
```sh
$ consul acl token update -id anonymous -policy-id 06acc
Token updated successfully.
AccessorID: 00000000-0000-0000-0000-000000000002
SecretID: anonymous
Description: Anonymous Token
Local: false
Create Time: 0001-01-01 00:00:00 +0000 UTC
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
Update a token description and take the policies from the existing token:
```sh
$ consul acl token update -id 986193 -description "WonderToken" -merge-policies
Token updated successfully.
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
Description: WonderToken
Local: false
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```

0
website/source/docs/commands/acl/acl-translate-rules.html.md.erb → website/source/docs/commands/acl/translate-rules.html.md.erb
View File

16
website/source/docs/commands/index.html.md
View File

@ -26,9 +26,11 @@ $ consul
Usage: consul [--version] [--help] <command> [<args>]
Available commands are:
acl Interact with Consul's ACLs
agent Runs a Consul agent
catalog Interact with the catalog
connect Interact with Consul Connect
debug Records a debugging archive for operators
event Fire a new event
exec Executes a command on Consul nodes
force-leave Forces a member of the cluster to enter the "left" state
@ -40,6 +42,8 @@ Available commands are:
kv Interact with the key-value store
leave Gracefully leaves the Consul cluster and shuts down
lock Execute a command holding a lock
login Login to Consul using an auth method
logout Destroy a Consul token created with login
maint Controls node or service maintenance mode
members Lists the members of a Consul cluster
monitor Stream logs from a Consul agent
@ -48,6 +52,7 @@ Available commands are:
rtt Estimates network round trip time between nodes
services Interact with services
snapshot Saves, restores and inspects snapshots of Consul server state
tls Builtin helpers for creating CAs and certificates
validate Validate config files/directories
version Prints the Consul version
watch Watch for changes in Consul
@ -138,6 +143,15 @@ are enabled, for example:
CONSUL_HTTP_TOKEN=aba7cbe5-879b-999a-07cc-2efd9ac0ffe
```
### `CONSUL_HTTP_TOKEN_FILE`
This is a path to a file containing the API access token required when access
control lists (ACLs) are enabled, for example:
```
CONSUL_HTTP_TOKEN_FILE=/path/to/consul.token
```
### `CONSUL_HTTP_AUTH`
This specifies HTTP Basic access credentials as a username:password pair:
@ -226,4 +240,4 @@ If the agent is [configured with TLS
certificates](/docs/agent/encryption.html#rpc-encryption-with-tls), then the
gRPC listener will require TLS and present the same certificate as the https
listener. As with `CONSUL_HTTP_ADDR`, if TLS is enabled either the `https://`
scheme should be used, or `CONSUL_HTTP_SSL` set.
scheme should be used, or `CONSUL_HTTP_SSL` set.

50
website/source/docs/commands/login.html.md.erb Normal file
View File

@ -0,0 +1,50 @@
---
layout: "docs"
page_title: "Commands: Login"
sidebar_current: "docs-commands-login"
description: >
The `login` command will exchange the provided third party credentials with the requested auth method for a newly minted Consul ACL token.
---
# Consul Login
Command: `consul login`
The `login` command will exchange the provided third party credentials with the
requested auth method for a newly minted Consul ACL token. The companion
command `consul logout` should be used to destroy any tokens created this way
to avoid a resource leak.
## Usage
Usage: `consul login [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
#### Command Options
* `-bearer-token-file=<string>` - Path to a file containing a secret bearer
token to use with this auth method.
* `-meta=<value>` - Metadata to set on the token, formatted as `key=value`. This
flag may be specified multiple times to set multiple meta fields.
* `-method=<string>` - Name of the auth method to login to.
* `-token-sink-file=<string>` - The most recent token's SecretID is kept up to
date in this file.
### Examples
Login to an auth method.
```sh
$ consul login -method 'minikube' \
-bearer-token-file '/run/secrets/kubernetes.io/serviceaccount/token' \
-token-sink-file 'consul.token'
$ cat consul.token
36103ae4-6731-e719-f53a-d35188cfa41d
```

34
website/source/docs/commands/logout.html.md.erb Normal file
View File

@ -0,0 +1,34 @@
---
layout: "docs"
page_title: "Commands: Logout"
sidebar_current: "docs-commands-logout"
description: >
The `logout` command will destroy the provided token if it was created from `consul login`.
---
# Consul Logout
Command: `consul logout`
The `logout` command will destroy the provided token if it was created from
`consul login`.
## Usage
Usage: `consul logout [options]`
-> The token to delete should be specified with the `-token` argument, the
`CONSUL_HTTP_TOKEN` environment variable, the `-token-file` argument, or the
`CONSUL_HTTP_TOKEN_FILE` environment variable.
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
### Examples
Logout and delete a login token.
```sh
$ consul logout -token-file 'consul.token'
```

9
website/source/layouts/api.erb
View File

@ -36,6 +36,15 @@
<li<%= sidebar_current("api-acl-policies") %>>
<a href="/api/acl/policies.html">Policies</a>
</li>
<li<%= sidebar_current("api-acl-roles") %>>
<a href="/api/acl/roles.html">Roles</a>
</li>
<li<%= sidebar_current("api-acl-auth-methods") %>>
<a href="/api/acl/auth-methods.html">Auth Methods</a>
</li>
<li<%= sidebar_current("api-acl-binding-rules") %>>
<a href="/api/acl/binding-rules.html">Binding Rules</a>
</li>
</ul>
</li>
<li<%= sidebar_current("api-agent") %>>

121
website/source/layouts/docs.erb
View File

@ -67,20 +67,117 @@
<li<%= sidebar_current("docs-commands-acl") %>>
<a href="/docs/commands/acl.html">acl</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-acl-auth-method") %>>
<a href="/docs/commands/acl/auth-method.html">auth-method</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-acl-auth-method-create") %>>
<a href="/docs/commands/acl/auth-method/create.html">create</a>
</li>
<li<%= sidebar_current("docs-commands-acl-auth-method-delete") %>>
<a href="/docs/commands/acl/auth-method/delete.html">delete</a>
</li>
<li<%= sidebar_current("docs-commands-acl-auth-method-list") %>>
<a href="/docs/commands/acl/auth-method/list.html">list</a>
</li>
<li<%= sidebar_current("docs-commands-acl-auth-method-read") %>>
<a href="/docs/commands/acl/auth-method/read.html">read</a>
</li>
<li<%= sidebar_current("docs-commands-acl-auth-method-update") %>>
<a href="/docs/commands/acl/auth-method/update.html">update</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-commands-acl-binding-rule") %>>
<a href="/docs/commands/acl/binding-rule.html">binding-rule</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-acl-binding-rule-create") %>>
<a href="/docs/commands/acl/binding-rule/create.html">create</a>
</li>
<li<%= sidebar_current("docs-commands-acl-binding-rule-delete") %>>
<a href="/docs/commands/acl/binding-rule/delete.html">delete</a>
</li>
<li<%= sidebar_current("docs-commands-acl-binding-rule-list") %>>
<a href="/docs/commands/acl/binding-rule/list.html">list</a>
</li>
<li<%= sidebar_current("docs-commands-acl-binding-rule-read") %>>
<a href="/docs/commands/acl/binding-rule/read.html">read</a>
</li>
<li<%= sidebar_current("docs-commands-acl-binding-rule-update") %>>
<a href="/docs/commands/acl/binding-rule/update.html">update</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-commands-acl-bootstrap") %>>
<a href="/docs/commands/acl/acl-bootstrap.html">bootstrap</a>
<a href="/docs/commands/acl/bootstrap.html">bootstrap</a>
</li>
<li<%= sidebar_current("docs-commands-acl-policy") %>>
<a href="/docs/commands/acl/acl-policy.html">policy</a>
<a href="/docs/commands/acl/policy.html">policy</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-acl-policy-create") %>>
<a href="/docs/commands/acl/policy/create.html">create</a>
</li>
<li<%= sidebar_current("docs-commands-acl-policy-delete") %>>
<a href="/docs/commands/acl/policy/delete.html">delete</a>
</li>
<li<%= sidebar_current("docs-commands-acl-policy-list") %>>
<a href="/docs/commands/acl/policy/list.html">list</a>
</li>
<li<%= sidebar_current("docs-commands-acl-policy-read") %>>
<a href="/docs/commands/acl/policy/read.html">read</a>
</li>
<li<%= sidebar_current("docs-commands-acl-policy-update") %>>
<a href="/docs/commands/acl/policy/update.html">update</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-commands-acl-role") %>>
<a href="/docs/commands/acl/role.html">role</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-acl-role-create") %>>
<a href="/docs/commands/acl/role/create.html">create</a>
</li>
<li<%= sidebar_current("docs-commands-acl-role-delete") %>>
<a href="/docs/commands/acl/role/delete.html">delete</a>
</li>
<li<%= sidebar_current("docs-commands-acl-role-list") %>>
<a href="/docs/commands/acl/role/list.html">list</a>
</li>
<li<%= sidebar_current("docs-commands-acl-role-read") %>>
<a href="/docs/commands/acl/role/read.html">read</a>
</li>
<li<%= sidebar_current("docs-commands-acl-role-update") %>>
<a href="/docs/commands/acl/role/update.html">update</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-commands-acl-set-agent-token") %>>
<a href="/docs/commands/acl/acl-set-agent-token.html">set-agent-token</a>
<a href="/docs/commands/acl/set-agent-token.html">set-agent-token</a>
</li>
<li<%= sidebar_current("docs-commands-acl-token") %>>
<a href="/docs/commands/acl/acl-token.html">token</a>
<a href="/docs/commands/acl/token.html">token</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-acl-token-clone") %>>
<a href="/docs/commands/acl/token/clone.html">clone</a>
</li>
<li<%= sidebar_current("docs-commands-acl-token-create") %>>
<a href="/docs/commands/acl/token/create.html">create</a>
</li>
<li<%= sidebar_current("docs-commands-acl-token-delete") %>>
<a href="/docs/commands/acl/token/delete.html">delete</a>
</li>
<li<%= sidebar_current("docs-commands-acl-token-list") %>>
<a href="/docs/commands/acl/token/list.html">list</a>
</li>
<li<%= sidebar_current("docs-commands-acl-token-read") %>>
<a href="/docs/commands/acl/token/read.html">read</a>
</li>
<li<%= sidebar_current("docs-commands-acl-token-update") %>>
<a href="/docs/commands/acl/token/update.html">update</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-commands-acl-translate-rules") %>>
<a href="/docs/commands/acl/acl-translate-rules.html">translate-rules</a>
<a href="/docs/commands/acl/translate-rules.html">translate-rules</a>
</li>
</ul>
</li>
@ -207,6 +304,12 @@
<li<%= sidebar_current("docs-commands-lock") %>>
<a href="/docs/commands/lock.html">lock</a>
</li>
<li<%= sidebar_current("docs-commands-login") %>>
<a href="/docs/commands/login.html">login</a>
</li>
<li<%= sidebar_current("docs-commands-logout") %>>
<a href="/docs/commands/logout.html">logout</a>
</li>
<li<%= sidebar_current("docs-commands-maint") %>>
<a href="/docs/commands/maint.html">maint</a>
</li>
@ -347,6 +450,14 @@
<li<%= sidebar_current("docs-acl-migration") %>>
<a href="/docs/acl/acl-migrate-tokens.html">Token Migration</a>
</li>
<li<%= sidebar_current("docs-acl-auth-methods") %>>
<a href="/docs/acl/acl-auth-methods.html">Auth Methods</a>
<ul class="nav">
<li<%= sidebar_current("docs-acl-auth-methods-kubernetes") %>>
<a href="/docs/acl/auth-methods/kubernetes.html">Kubernetes</a>
</li>
</ul>
</li>
</ul>
</li>

7
website/source/redirects.txt
View File

@ -49,6 +49,13 @@
/docs/guides/bootstrapping.html https://www.consul.io/docs/install/bootstrapping.html
/docs/guides/sentinel.html https://www.consul.io/docs/agent/sentinel.html
# CLI renames
/docs/commands/acl/acl-bootstrap.html https://www.consul.io/docs/commands/acl/bootstrap.html
/docs/commands/acl/acl-policy.html https://www.consul.io/docs/commands/acl/policy.html
/docs/commands/acl/acl-set-agent-token.html https://www.consul.io/docs/commands/acl/set-agent-token.html
/docs/commands/acl/acl-token.html https://www.consul.io/docs/commands/acl/token.html
/docs/commands/acl/acl-translate-rules.html https://www.consul.io/docs/commands/acl/translate-rules.html
# Consul Learn Redirects
/docs/guides/acl.html https://learn.hashicorp.com/consul/advanced/day-1-operations/acl-guide
/docs/guides/agent-encryption.html https://learn.hashicorp.com/consul/advanced/day-1-operations/agent-encryption