docs: how to launch envoy when ACLs enabled #15497
Conversation
jkirschner-hashicorp
added
type/docs
| 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.
@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.
| 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.
| 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.
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.
| 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.
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.
| 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 |
| ``` | ||
|
|
||
| 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.
| ### 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.
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.
| 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.
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.
No description provided.