-
Notifications
You must be signed in to change notification settings - Fork 4.4k
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.
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
docs: how to launch envoy when ACLs enabled #15497
Conversation
necessary privileges. A sidecar proxy must have a Consul ACL token to act as itself and | ||
the service it fronts, and to access all that service's potential upstreams. | ||
The best way to generate such a token is to | ||
[use a service identity](/consul/commands/acl/token/create#create-a-token-for-a-service). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@rboyer : In the future, we'll want to similarly clarify how to launch the various gateways with a token with the necessary ACL permissions. This pairs with the "write a doc on how to create the ACL token needed for various things" task.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mostly suggestions for consistency with our styles
This creates a token with the privileges necessary to register the service `my-api`. | ||
If `my-api` is in the service mesh, this token also has the privileges necessary | ||
to register its associated sidecar proxy and should be passed to the proxy when | ||
launched with [`consul connect envoy`](/consul/commands/connect/envoy). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This creates a token with the privileges necessary to register the service `my-api`. | |
If `my-api` is in the service mesh, this token also has the privileges necessary | |
to register its associated sidecar proxy and should be passed to the proxy when | |
launched with [`consul connect envoy`](/consul/commands/connect/envoy). | |
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. The proxy also inherits the privileges when it is launched using the [`consul connect envoy`](/consul/commands/connect/envoy) command. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll take the suggestions for the first two sentences, but leave the original text about the consul connect envoy
interaction. The proxy doesn't "inherit" anything. The token has to be specified by the user when launching the proxy with consul connect envoy
.
Nothing can access Consul API resources unless it presents a Consul ACL token with the | ||
necessary privileges. A sidecar proxy must have a Consul ACL token to act as itself and | ||
the service it fronts, and to access all that service's potential upstreams. | ||
The best way to generate such a token is to | ||
[use a service identity](/consul/commands/acl/token/create#create-a-token-for-a-service). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nothing can access Consul API resources unless it presents a Consul ACL token with the | |
necessary privileges. A sidecar proxy must have a Consul ACL token to act as itself and | |
the service it fronts, and to access all that service's potential upstreams. | |
The best way to generate such a token is to | |
[use a service identity](/consul/commands/acl/token/create#create-a-token-for-a-service). | |
To access Consul API resources, services and users must present a Consul ACL token with the | |
necessary privileges. A sidecar proxy configuration must also contain a Consul ACL token. This is so that the proxy and services that send traffic through the proxy can also access Consul API resources and access all of the services' potential upstreams. | |
We recommend creating a [service identity](/consul/commands/acl/token/create#create-a-token-for-a-service) when generating a token. Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service. |
Trying to be more specific than saying "nothing" can access resources. I also wan to be more concrete about what we mean in terms of a sidecar proxy "act[ing] as itself". Let me know if I am misinterpreting this information.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I applied the spirit of this suggestion to some new wording (that I'll push to the repo in a few minutes) to preserve accuracy. Let me know if the new wording is clear and complies with our style.
Then, provide that token when launching the Envoy sidecar proxy instance with | ||
the `consul connect envoy` command through either: | ||
- 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 | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Then, provide that token when launching the Envoy sidecar proxy instance with | |
the `consul connect envoy` command through either: | |
- 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 | |
``` | |
After establishing a service identity that provides access to resources, you can provide the token when launching the Envoy sidecar proxy instance with | |
the `consul connect envoy` command. You can pass the token in an environment variable or with the `-token` or `-token-file` flag. | |
Environment variables: | |
- [`CONSUL_HTTP_TOKEN`](/consul/commands#consul_http_token) | |
- [`CONSUL_HTTP_TOKEN_FILE`](/consul/commands#consul_http_token_file) | |
CLI flags: | |
- [`-token`](/consul/commands/connect/envoy#token) | |
- [`-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 |
This suggestion is about presenting information in complete sentences, rather than completing the sentences with bullets.
@trujillo-adam : ready for re-review |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is super close to being ready.
``` | ||
|
||
Create a new token and link with policies by name: | ||
### Create a short-lived and highly privileged token |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
### Create a short-lived and highly privileged token | |
### Create a temporary and highly-privileged token |
Same comment here about setting up the example
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Out of curiosity, why change short-lived to temporary?
Either can be fine. Short-lived just feels more precise (to me) for this specific example (15 minute lifetime).
with the necessary privileges. A sidecar proxy must be provided with an ACL token | ||
with privileges to register itself and the service it fronts, | ||
and to access all potential upstreams of that service. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
with the necessary privileges. A sidecar proxy must be provided with an ACL token | |
with privileges to register itself and the service it fronts, | |
and to access all potential upstreams of that service. | |
with the necessary privileges. You must add an ACL token to the sidecar proxy’s configuration when ACLs are enabled. The token must grant the proxy privileges to register itself and the service it fronts and to access all potential upstreams of that service. |
I think this was my most recent suggestion. After rereading it I can see that it is ambiguous. I think this is clearer.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I went with something substantially similar:
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks great!
No description provided.