Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

Backport of docs: how to launch envoy when ACLs enabled into stable-website #15750

Merged
merged 1 commit into from
Dec 9, 2022
Merged

Backport of docs: how to launch envoy when ACLs enabled into stable-website #15750

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

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 41 additions & 25 deletions website/content/commands/acl/token/create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,14 @@ Usage: `consul acl token create [options] [args]`

## Examples

Create a new token:
The following examples describe how to create ACL tokens for common scenarios.

### Create a token with policy by name

The following example creates a token that includes a policy by its name.

```shell-session
$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965
$ consul acl token create -description "Read Nodes and Services" -policy-name node-services-read
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
Description: Read Nodes and Services
Expand All @@ -89,42 +93,54 @@ Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```

Create a new local token:
### Create a token for a service

The following example creates a token with the privileges necessary
for registering a service named `my-api`.
If `my-api` is in the service mesh, the token also has the privileges necessary
to register its associated sidecar proxy and must be provided to the proxy when
launched with [`consul connect envoy`](/consul/commands/connect/envoy#sidecar-proxy-with-acls-enabled).

```shell-session
$ 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
$ consul acl token create -description 'my-api token' -service-identity 'my-api'
AccessorID: 0c083aca-6c15-f0cc-c4d9-30578db54cd9
SecretID: 930dafb6-5c08-040b-23fb-a368a95256f9
Description: api token
Local: false
Create Time: 2019-04-25 16:45:49.337687334 -0500 CDT
Service Identities:
my-api (Datacenters: all)
```

Create a new token and link with policies by name:
### Create a temporary and highly-privileged token

The following example creates a token with a lifetime of 15 minutes that
includes the built-in [`global-management` policy](/consul/docs/security/acl/acl-policies#global-management).

```shell-session
$ consul acl token create -description "Super User" -policy-name global-management
$ consul acl token create -description "Temp Super User" -policy-name global-management -expires-ttl '15m'
AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa
SecretID: ada7f751-f654-8872-7f93-498e799158b6
Description: Super User
Description: Temp Super User
Local: false
Create Time: 2018-10-22 15:35:28.787003 -0400 EDT
Create Time: 2019-04-25 16:45:49.337687334 -0500 CDT
Expiration Time: 2019-04-25 17:00:49.337687334 -0500 CDT
Policies:
00000000-0000-0000-0000-000000000001 - global-management
```

Create a new token with one service identity that expires in 15 minutes:
### Create a local token with policy by ID

The following example creates a token that is only valid in this datacenter
and includes a policy by its UUID.

```shell-session
$ 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)
$ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 -local
AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d
SecretID: ec15675e-2999-d789-832e-8c4794daa8d7
Description: Read Nodes and Services
Local: true
Create Time: 2018-10-22 15:33:39.01789 -0400 EDT
Policies:
06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read
```
32 changes: 31 additions & 1 deletion website/content/commands/connect/envoy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ The connect Envoy command is used to generate a bootstrap configuration for
[Envoy proxy](https://envoyproxy.io) for use with [Consul
Connect](/docs/connect/).

Refer to the [examples](#examples) for guidance on common use cases,
such as [launching a service instance's sidecar proxy
when ACLs are enabled](#sidecar-proxy-with-acls-enabled).

The default behavior is to generate the necessary bootstrap configuration for
Envoy based on the environment variables and options provided and by talking to
the local Consul agent. It `exec`s an external Envoy binary with that
Expand Down Expand Up @@ -215,7 +219,7 @@ service {
}
```

### Basic Sidecar Proxy
### Basic sidecar proxy

The sidecar Envoy process can be started with.

Expand All @@ -227,6 +231,32 @@ This example assumes that the correct [environment variables](#api-options) are
used to set the local agent connection information and ACL token, or that the
agent is using all-default configuration.

### Sidecar proxy with ACLs enabled

In secure deployments, Consul's ACL system is enabled with a default `deny` policy.
To access Consul API resources, an API request must present a Consul ACL token
with the necessary privileges. If ACLs are enabled, you must provide an ACL token to the sidecar proxy. The token must grant the proxy privileges to register itself and the service it fronts and to access all potential upstreams of that service.
We recommend [using a service identity](/consul/commands/acl/token/create#create-a-token-for-a-service)
to directly create a token with the privileges necessary for a service and its sidecar proxy,
rather than creating a unique ACL policy for every service.

After creating a token using a service identity, provide the token when
launching the Envoy sidecar proxy instance with the `consul connect envoy` command.
You can provide the token through an environment variable or CLI flag.

Environment variables:
- [`CONSUL_HTTP_TOKEN`](/consul/commands#consul_http_token) or
- [`CONSUL_HTTP_TOKEN_FILE`](/consul/commands#consul_http_token_file)

CLI flags:
- [`-token`](/consul/commands/connect/envoy#token) or
- [`-token-file`](/consul/commands/connect/envoy#token-file)

```shell-session
$ export CONSUL_HTTP_TOKEN="<secret-id-of-token-with-service-identity-for-web>"
$ consul connect envoy -sidecar-for web
```

### Additional Envoy Arguments

To pass additional arguments directly to Envoy, for example output logging
Expand Down