github.com/sl1pm4t/consul@v1.4.5-0.20190325224627-74c31c540f9c/website/source/docs/commands/connect/envoy.html.md.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: Connect Proxy"
     4  sidebar_current: "docs-commands-connect-envoy"
     5  description: >
     6    The connect proxy subcommand is used to run the built-in mTLS proxy for Connect.
     7  ---
     8  
     9  # Consul Connect Envoy
    10  
    11  Command: `consul connect envoy`
    12  
    13  The connect Envoy command is used to generate a bootstrap configuration for
    14  [Envoy proxy](https://envoyproxy.io) for use with [Consul
    15  Connect](/docs/connect/).
    16  
    17  The default behaviour is to generate the necessary bootstrap configuration for
    18  Envoy based on the environment variables and options provided and by taking to
    19  the local Consul agent. It `exec`s an external Envoy binary with that
    20  configuration leaving the Envoy process running in the foreground. An error is
    21  returned on operating systems other than linux or macOS since Envoy does not
    22  build for other platforms currently.
    23  
    24  If the `-bootstrap` option is specified, the bootstrap config is generated in
    25  the same way and then printed to stdout. This allows it to be redirected to a
    26  file and used with `envoy -c bootstrap.json`. This works on all operating
    27  systems allowing configuration to be generated on a host that Envoy doesn't
    28  build on but then used in a virtualized environment that can run Envoy.
    29  
    30  ## Usage
    31  
    32  Usage: `consul connect envoy [options] [-- pass-through options]`
    33  
    34  #### API Options
    35  
    36  The standard API options are used to connect to the local agent to discover the
    37  proxy configuration needed.
    38  
    39   - `-grpc-addr=<addr>` - Address of the Consul agent with `grpc` port. This can
    40     be an IP address or DNS address, but it must include the port. This can also
    41     be specified via the CONSUL_GRPC_ADDR environment variable. In Consul 1.3 and
    42     later, the default value is http://127.0.0.1:8502, and https can optionally
    43     be used instead. The scheme can also be set to HTTPS by setting the
    44     environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket
    45     using `unix:///path/to/socket` if the [agent is configured to
    46     listen](/docs/agent/options.html#addresses) that way.
    47  
    48  -> **Note:** gRPC uses the same TLS
    49     settings as the HTTPS API. If HTTPS is enabled then gRPC will require HTTPS
    50     as well.
    51  
    52     <%= partial "docs/commands/http_api_options_client" %>
    53  
    54  #### Envoy Options
    55  
    56  * `-sidecar-for` - The _ID_ (not name if they differ) of the service instance
    57    this proxy will represent. The target service doesn't need to exist on the
    58    local agent yet but a [sidecar proxy
    59    registration](/docs/connect/proxies.html#sidecar-proxy-fields) with
    60    `proxy.destination_service_id` equal to the passed value must be present. If
    61    multiple proxy registrations targeting the same local service instance are
    62    present the command will error and `-proxy-id` should be used instead.
    63  
    64  * `-proxy-id` - The [proxy
    65    service](/docs/connect/proxies.html#proxy-service-definitions) ID on the
    66    local agent. This must already be present on the local agent.
    67  
    68  -> **Note:** If ACLs are enabled, a token granting `service:write` for the
    69    _target_ service (configured in `proxy.destination_service_name`) must be
    70    passed using the `-token` option or `CONSUL_HTTP_TOKEN` environment variable.
    71    This token authorizes the proxy to obtain TLS certificates representing the
    72    target service.
    73  
    74   * `-envoy-binary` - The full path to a specific Envoy binary to exec. By
    75     default the current `$PATH` is searched for `envoy`.
    76  
    77   * `-admin-bind` - The `host:port` to bind Envoy's admin HTTP API. Default is
    78     `localhost:19000`. Envoy requires that this be enabled. The host part must be
    79     resolvable DNS name or IP address.
    80  
    81   * `-bootstrap` - If present, the command will simply output the generated
    82     bootstrap config to stdout in JSON protobuf form. This can be directed to a
    83     file and used to start Envoy with `envoy -c bootstrap.json`.
    84  
    85  ~> **Security Note:** If ACLs are enabled the bootstrap JSON will contain the
    86  ACL token from `-token` or the environment and so should be handled as a secret.
    87  This token grants the identity of any service it has `service:write` permission
    88  for and so can be used to access any upstream service that that service is
    89  allowed to access by [Connect intentions](/docs/connect/intentions.html).
    90  
    91   * `-- [pass-through options]` - Any options given after a double dash are passed
    92     directly through to the `envoy` invocation. See [Envoy's
    93     documentation](https://www.envoyproxy.io/docs) for more details. The command
    94     always specifies `--config-file` and `--v2-config-only` and by default passes
    95     `--disable-hot-restart` see [hot restart](#hot-restart).
    96  
    97  ## Examples
    98  
    99  Assume a local service instance is registratered on the local agent with a
   100  sidecar proxy (using the [sidecar service
   101  registration](/docs/connect/proxies/sidecar-service.html) helper) as below.
   102  
   103  ```hcl
   104  service {
   105    name = "web"
   106    port = 8080
   107    connect { sidecar_service {} }
   108  }
   109  ```
   110  
   111  The sidecar Envoy process can be started with.
   112  
   113  ```text
   114  $ consul connect envoy -sidecar-for web
   115  ```
   116  
   117  This example assumes that the correct [environment variables](#api-options) are
   118  used to set the local agent connection information and ACL token, or that the
   119  agent is using all-default configuration.
   120  
   121  To pass additional arguments directly to Envoy, for example output logging
   122  level, you can use:
   123  
   124  ```text
   125  $ consul connect envoy -sidecar-for web -- -l debug
   126  ```
   127  
   128  To run multiple different proxy instances on the same host, you will
   129  need to use `-admin-bind` on all but one to ensure they don't attempt to bind to
   130  the same port as in the following example.
   131  
   132  ```text
   133  $ consul connect envoy -sidecar-for db -admin-bind localhost:19001
   134  ```
   135  
   136  ## Exec Security Details
   137  
   138  The command needs to pass the bootstrap config through to Envoy. Envoy currently
   139  only supports passing this as a file path or passing a whole string on the
   140  command line with `--config-yaml`. Since the bootstrap needs to contain the ACL
   141  token to authorize the proxy, this secret needs careful handling.
   142  
   143  Passing a secret via command option is unacceptable as on many unix systems
   144  these are readable to any user on the host for example via `/proc` or via a
   145  setuid process like `ps`.
   146  
   147  Creating a temporary file is more secure in that it can only be read by the
   148  current user but risks leaving secret material on disk for an unbounded length
   149  of time and in a location that is opaque to the operator.
   150  
   151  To work around these issues, the command currently creates a temporary file and
   152  immediately unlinks it so it can't be read by any other process that doesn't
   153  already have the file descriptor. It then writes the bootstrap JSON, and unsets
   154  the CLOEXEC bit on the file handle so that it remains available to the Envoy
   155  process after exec. Finally it `exec`s Envoy with `--config-file /dev/fd/X`
   156  where `X` is the the file descriptor number of the temp file.
   157  
   158  This ensures that Envoy can read the file without any other normal user process
   159  being able to (assuming they don't have privileged access to /proc). Once the
   160  Envoy process stops, there is no longer any reference to the file to clean up.
   161  
   162  ## Envoy Hot Restart
   163  
   164  Envoy supports hot restart which requires simple external coordination. By
   165  default, this command will add `--disable-hot-restart` when it runs Envoy.
   166  
   167  The reason for this default behavior is to make it easy to test and run local
   168  demonstrations with multiple Envoy instances outside of cgroups or network
   169  namespaces.
   170  
   171  To use hot restart, Envoy needs to be started with either the `--restart-epoch`
   172  option. If this command detects that option in the pass-through flags it will
   173  _not_ add `--disable-hot-restart` allowing hot restart to work normally.
   174  
   175  The only difference to note over running Envoy directly is that
   176  `--restart-epoch` must be explicitly set to `0` for the initial launch of the
   177  Envoy instance to avoid disabling hot restart entirely. The official
   178  `hot-restarter.py` always sets this option so should work as recommended.