diff --git a/website/source/docs/guides/consul-containers.html.md b/website/source/docs/guides/consul-containers.html.md index bcd63e2260..f24812571b 100644 --- a/website/source/docs/guides/consul-containers.html.md +++ b/website/source/docs/guides/consul-containers.html.md @@ -1,29 +1,29 @@ --- layout: "docs" -page_title: "Using Consul With Containers" +page_title: "Using Consul with Containers" sidebar_current: "docs-guides-consul-on-containers" description: |- This guide describes how to run Consul on containers, with Docker as the primary focus. It also describes best practices when running a Consul cluster in production on Docker. --- ## Consul with Containers -This guide describes critical aspects of operating a Consul cluster that's run inside containers. It primarily focuses on Docker. +This guide describes critical aspects of operating a Consul cluster that's run inside containers. It primarily focuses on the Docker container runtime, but the principles largely apply to rkt, oci, and other container runtimes as well. ## Consul Official Docker Image - -Consul's official Docker images are tagged with version numbers. For example `docker pull consul:0.9.0` will pull the 0.9.0 Consul release image. For major releases, make sure to read our [upgrade guides](https://www.consul.io/docs/upgrade-specific.html) before upgrading your cluster. - -More instructions on how to get started using this image are available at the [official Docker repository page](https://hub.docker.com/_/consul/) +Consul's official Docker images are tagged with version numbers. For example `docker pull consul:0.9.0` will pull the 0.9.0 Consul release image. +For major releases, make sure to read our [upgrade guides](https://www.consul.io/docs/upgrade-specific.html) before upgrading your cluster. +To get a development mode consul instance running the latest version, run `docker run consul`. +More instructions on how to get started using this image are available at the [official Docker repository page](https://store.docker.com/images/consul) ## Data Directory Persistence -The container exposes its data directory, `/consul/data` as a [volume](https://docs.docker.com/engine/tutorials/dockervolumes/) , which is a path where Consul will place its persisted state. +The container exposes its data directory, `/consul/data` as a [volume](https://docs.docker.com/engine/tutorials/dockervolumes/), which is a path where Consul will place its persisted state. -For client agents, this stores some information about the cluster and the client's health checks in case the container is restarted. If the volume on a client agent disappears, it doesn't affect cluster operations. +For clients, this stores some information about the cluster and the client's health checks in case the container is restarted. If the volume on a client disappears, it doesn't affect cluster operations. -For server agents, this stores the client information plus snapshots and data related to the consensus algorithm and other state like Consul's key/value store and catalog. **Servers need the volume's data around when restarting containers to recover from outage scenarios.** Therefore, care must be taken by operators to make sure that volumes containing consul cluster data are not destroyed during container restarts, +For servers, this stores the client information plus snapshots and data related to the consensus algorithm and other state like Consul's key/value store and catalog. **Servers need the volume's data to be available when restarting containers to recover from outage scenarios.** Therefore, care must be taken by operators to make sure that volumes containing consul cluster data are not destroyed during container restarts, -**We also recommend taking additional backups via [`consul snapshot`](https://www.consul.io/docs/commands/snapshot.html), and storing them externally.** +~> We also recommend taking additional backups via [`consul snapshot`](https://www.consul.io/docs/commands/snapshot.html), and storing them externally. ## Networking When run inside a container, Consul's IP addresses need to be setup properly. Consul has to be configured with an appropriate _cluster address_ as well as a _client address._ In some cases, it might also require configuring an _advertise_address_. @@ -38,16 +38,24 @@ You will need to tell Consul what its cluster address is when starting so that i 1. _Environment Variables_: Use the `CONSUL_CLIENT_INTERFACE` and `CONSUL_BIND_INTERFACE` environment variables. In the following example `eth0` is the network interface of the container: ``` -docker run -d -e CONSUL_CLIENT_INTERFACE=eth0 -e CONSUL_BIND_INTERFACE='eth0' consul agent -server -bootstrap-expect=3 +docker run \ +-d \ +-e CONSUL_CLIENT_INTERFACE=eth0 \ +-e CONSUL_BIND_INTERFACE='eth0' \ +consul agent -server -bootstrap-expect=3 ``` 2. _Address Templates_: You can declaratively specify the client and cluster addresses using the formats described in the [go-socketaddr](https://github.com/hashicorp/go-sockaddr) library. In the following example, the client and bind addresses are declaratively specified for the container network interface 'eth0' ``` -docker run consul agent -server -client='{{ GetInterfaceIP "eth0" }}' -bind='{{ GetInterfaceIP "eth0" }}' -bootstrap-expect=3 +docker run \ +consul agent -server \ +-client='{{ GetInterfaceIP "eth0" }}' \ +-bind='{{ GetInterfaceIP "eth0" }}' \ +-bootstrap-expect=3 ``` ## Stopping and Restarting Containers -Consul containers can be stopped using the `docker stop ` command and restarted using `docker start `. As long as there are enough servers in the cluster to maintain [quorum](https://www.consul.io/docs/internals/consensus.html#deployment-table), Consul's [Autopilot](https://www.consul.io/docs/guides/autopilot.html) feature will handle removing servers whose containers were stopped. Autopilot's default settings are already configured correctly. If you override them, make sure that the following [Autopilot settings](https://www.consul.io/docs/agent/options.html#autopilot) are appropriate. +Consul containers can be stopped using the `docker stop ` command and restarted using `docker start `. As long as there are enough servers in the cluster to maintain [quorum](/docs/internals/consensus.html#deployment-table), Consul's [Autopilot](/docs/guides/autopilot.html) feature will handle removing servers whose containers were stopped. Autopilot's default settings are already configured correctly. If you override them, make sure that the following [Autopilot settings](/docs/agent/options.html#autopilot) are appropriate. * `cleanup_dead_servers` must be set to true to make sure that a stopped container is removed from the cluster. * `last_contact_threshold` should be reasonably small, so that dead servers are removed quickly. @@ -59,7 +67,6 @@ When a previously stopped server container is restarted using `docker start ->: write: broken pipe` when saving snapshots. This doesn't affect saving and restoring snapshots. - +**Snapshot close error** Due to a [known issue](https://github.com/docker/libnetwork/issues/1204) with half close support in docker, you will see an error message `[ERR] consul: Failed to close snapshot: write tcp ->: write: broken pipe` when saving snapshots. This doesn't affect saving and restoring snapshots.