Skip to content
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.

Sign up for GitHub

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] Connect with Envoy Guide #5505

Merged
merged 3 commits into from
Mar 26, 2019
Merged

[docs] Connect with Envoy Guide #5505

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
49511f9
Updating the intro.
kaitlincart Mar 18, 2019
8fadc2d
Update website/source/docs/guides/connect-envoy.md
judithpatudith Mar 25, 2019
3454491
Update website/source/docs/guides/connect-envoy.md
judithpatudith Mar 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 18 additions & 25 deletions website/source/docs/guides/connect-envoy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,35 +9,28 @@ description: |-
# Using Connect with Envoy Proxy

Consul Connect has first class support for using
[Envoy](https://www.envoyproxy.io) as a proxy. This guide will walk through a
working example on a local development machine that shows the moving parts.
[Envoy](https://www.envoyproxy.io) as a proxy. This guide will describe how to setup a development-mode Consul server and two services that use
kaitlincart marked this conversation as resolved.
Show resolved Hide resolved
Envoy proxies on a single machine with [Docker](https://www.docker.com/).
The aim of this guide is to demonstrate a minimal working setup and the moving parts involved, it is not intended for production deployments.

For reference documentation on how the integration works and is configured,
please see [Envoy](/docs/connect/proxies/envoy.html).
kaitlincart marked this conversation as resolved.
Show resolved Hide resolved

## Setup Overview

This guide will describe how to setup a development-mode Consul server and two
Envoy proxies on a single machine using [Docker](https://www.docker.com/). The
aim is to demonstrate a minimal working setup and the moving parts involved.
We'll start all containers using Docker's `host` network mode and will have a total of five containers running by the end of this guide.

We choose to run in Docker since Envoy is only distributed as a Docker image so
it's the quickest way to get a demo running. The same commands used here will
work in just the same way outside of Docker if you build an Envoy binary
yourself.

We'll start all containers using Docker's `host` network mode which is not a
realistic simulation of a production setup, but makes the following steps much
simpler.

We should end up with five containers running:

1. The Consul agent
1. A single Consul server
2. An example TCP `echo` service as a destination
3. An Envoy sidecar proxy for the `echo` service
4. An Envoy sidecar proxy for the `client` service
5. An example `client` service (netcat)

We choose to run in Docker since Envoy is only distributed as a Docker image so
it's the quickest way to get a demo running. The same commands used here will
work in just the same way outside of Docker if you build an Envoy binary
yourself.

## Building an Envoy Image

Starting Envoy requires a bootstrap configuration file that points Envoy to the
Expand Down Expand Up @@ -75,21 +68,21 @@ docker build -t consul-envoy .
We will use the `consul-envoy` image we just made to configure and run Envoy
processes later.

## Consul Agent Setup
## Deploying a Consul Server

Next we need a Consul agent. We'll work with a single Consul agent in `-dev`
Next we need a Consul server. We'll work with a single Consul server in `-dev`
mode for simplicity.

-> **Note:** `-dev` mode enables the gRPC server on port 8502 by default. For a
production agent you'll need to [explicitly configure the gRPC
port](/docs/agent/options.html#grpc_port).

In order to start a proxy instance, a [proxy service
definition](/docs/connect/proxies.html) must exist on the local agent. We'll
definition](/docs/connect/proxies.html) must exist on the local Consul agent. We'll
create one using the [sidecar service
registration](/docs/connect/proxies/sidecar-service.html) syntax.

Create a config file called `envoy_demo.hcl` containing the following service
Create a configuration file called `envoy_demo.hcl` containing the following service
definitions.

```hcl
Expand All @@ -116,7 +109,7 @@ services {
}
```

The Consul agent container can now be started with that configuration.
The Consul container can now be started with that configuration.

```sh
$ docker run --rm -d -v$(pwd)/envoy_demo.hcl:/etc/consul/envoy_demo.hcl \
Expand All @@ -132,13 +125,13 @@ continue in the same terminal. Log output can be seen using the name we gave.
docker logs -f consul-agent
```

Note that the Consul agent has registered two services `client` and `echo`, but
Note that the Consul server has registered two services `client` and `echo`, but
also registered two proxies `client-sidecar-proxy` and `echo-sidecar-proxy`.
Next we'll need to run those services and proxies.

## Running the Echo Service

Next we'll run the `echo` service. We can use an existing tcp echo utility image
Next we'll run the `echo` service. We can use an existing TCP echo utility image
for this.

Start the echo service on port 9090 as registered before.
Expand Down Expand Up @@ -182,7 +175,7 @@ listeners, TLS certificates, upstream service instances and so on. The xDS API
allows the Envoy instance to watch for any changes so certificate rotations or
changes to the upstream service instances are immediately sent to the proxy.

## Running the Client
## Running the Client Service

Finally, we can see the connectivity by running a dummy "client" service. Rather
than run a full service that itself can listen, we'll simulate the service with
Expand Down