Consul Connect Proxy
Command: consul connect proxy
The connect proxy command is used to run Consul's built-in mTLS proxy for use with Consul service mesh. This can be used in production to enable a mesh-unaware application to accept and establish mesh-based connections. This proxy can also be used in development to connect to mesh-enabled services.
Usage
Usage: consul connect proxy [options]
Command Options
-sidecar-for
- The ID (not name if they differ) of the service instance this proxy will represent. The target service doesn't need to exist on the local agent yet but a sidecar proxy registration withproxy.destination_service_id
equal to the passed value must be present. If multiple proxy registrations targeting the same local service instance are present the command will error and-proxy-id
should be used instead. This can also be specified via theCONNECT_SIDECAR_FOR
environment variable.-proxy-id
- The proxy service ID on the local agent. This must already be present on the local agent. This option can also be specified via theCONNECT_PROXY_ID
environment variable.-log-level
- Specifies the log level.-pprof-addr
- Enable debugging via pprof. Providing a host:port (or just ':port') enables profiling HTTP endpoints on that address.-service
- Name of the service this proxy is representing. This service doesn't need to actually exist in the Consul catalog, but proper ACL permissions (service:write
) are required. This and the remaining options can be used to setup a proxy that is not registered already with local config useful for development.-upstream
- Upstream service to support connecting to. The format should be 'name:addr', such as 'db:8181'. This will make 'db' available on port 8181. When a regular TCP connection is made to port 8181, the proxy will service discover "db" and establish a Consul service mesh mTLS connection identifying as the-service
value. This flag can be repeated multiple times.-listen
- Address to listen for inbound connections to the proxied service. Must be specified with -service and -service-addr. If this isn't specified, an inbound listener is not started.-service-addr
- Address of the local service to proxy. Required for-listen
.-register
- Self-register with the local Consul agent, making this proxy available as mesh-capable service in the catalog. This is only useful with-listen
.-register-id
- Optional ID suffix for the service when-register
is set to disambiguate the service ID. By default the service ID is<service>-proxy
where<service>
is the-service
value. In most cases it is now preferable to useconsul services register
to register a fully configured proxy instance rather than specify config and registration via this command.
API Options
-ca-file=<value>
- Path to a CA file to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CACERT
environment variable.-ca-path=<value>
- Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via theCONSUL_CAPATH
environment variable.-client-cert=<value>
- Path to a client cert file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_CERT
environment variable.-client-key=<value>
- Path to a client key file to use for TLS whenverify_incoming
is enabled. This can also be specified via theCONSUL_CLIENT_KEY
environment variable.-http-addr=<addr>
- Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via theCONSUL_HTTP_ADDR
environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variableCONSUL_HTTP_SSL=true
. This may be a unix domain socket usingunix:///path/to/socket
if the agent is configured to listen that way.-tls-server-name=<value>
- The server name to use as the SNI host when connecting via TLS. This can also be specified via theCONSUL_TLS_SERVER_NAME
environment variable.-token=<value>
- ACL token to use in the request. This can also be specified via theCONSUL_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 orCONSUL_HTTP_TOKEN
environment variable. This can also be specified via theCONSUL_HTTP_TOKEN_FILE
environment variable.
-datacenter=<name>
- Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.-stale
- Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.
Examples
The example below shows how to start a local proxy for establishing outbound connections to "db" representing the frontend service. Once running, any process that creates a TCP connection to the specified port (8181) will establish a mutual TLS connection to "db" identified as "frontend".
The next example starts a local proxy that also accepts inbound connections on port 8443, authorizes the connection, then proxies it to port 8080: