open-consul/website/source/docs/commands/connect/proxy.html.md.erb
Paul Banks 94332edf2e
[WIP] Initial draft of Sidecar Service and Managed Proxy deprecation docs (#4752)
* Initial draft of Sidecar Service and Managed Proxy deprecation docs

* Service definition deprecation notices and sidecar service

* gRPC and sidecar service config options; Deprecate managed proxy options

* Envoy Docs: Basic envoy command; envoy getting started/intro

* Remove change that snuck in

* Envoy custom config example

* Add agent/service API docs; deprecate proxy config endpoint

* Misc grep cleanup for managed proxies; capitalize Envoy

* Updates to getting started guide

* Add missing link

* Refactor Envoy guide into a separate guide and add bootstrap reference notes.

* Add limitations to Envoy docs; Highlight no fixes for known managed proxy issues on deprecation page; clarify snake cae stuff; Sidecar Service lifecycle
2018-10-11 10:44:42 +01:00

97 lines
3.8 KiB
Plaintext

---
layout: "docs"
page_title: "Commands: Connect Proxy"
sidebar_current: "docs-commands-connect-proxy"
description: >
The connect proxy subcommand is used to run the built-in mTLS proxy for Connect.
---
# Consul Connect Proxy
Command: `consul connect proxy`
The connect proxy command is used to run Consul's built-in mTLS proxy for
use with Connect. This can be used in production to enable a Connect-unaware
application to accept and establish Connect-based connections. This proxy
can also be used in development to connect to Connect-enabled services.
## Usage
Usage: `consul connect proxy [options]`
#### API Options
<%= partial "docs/commands/http_api_options_client" %>
<%= partial "docs/commands/http_api_options_server" %>
#### Proxy 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](/docs/connect/proxies.html#sidecar-proxy-fields) with
`proxy.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.
* `-proxy-id` - The [proxy
service](/docs/connect/proxies.html#proxy-service-definitions) ID on the
local agent. This must already be present on the local agent.
* `-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](/docs/connect/dev.html).
* `-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 Connect 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 Connect-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 use [`consul services register`](/docs/commands/services/register.html) to
register a fully configured proxy instance rather than specify config and
registration via this command.
## 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".
```text
$ consul connect proxy -service frontend -upstream db:8181
```
The next example starts a local proxy that also accepts inbound connections
on port 8443, authorizes the connection, then proxies it to port 8080:
```text
$ consul connect proxy \
-service frontend \
-service-addr 127.0.0.1:8080 \
-listen ':8443'
```