Containers guide #3347

preetapan · 2017-08-01T15:41:45Z

Addressed a bunch of review comments, pls take a final look.

sethvargo · 2017-08-01T18:11:06Z

website/source/docs/guides/consul-containers.html.md

+## 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](/docs/upgrade-specific.html) before upgrading your cluster.


s/our/the

s/your/a

As a general rule, try to avoid first/second person in technical documentation where possible.

sethvargo · 2017-08-01T18:11:40Z

website/source/docs/guides/consul-containers.html.md

+
+For major releases, make sure to read our [upgrade guides](/docs/upgrade-specific.html) before upgrading your cluster.
+
+To get a development mode consul instance running the latest version, run `docker run consul`.


Capital "C" consul here

sethvargo · 2017-08-01T18:11:55Z

website/source/docs/guides/consul-containers.html.md

+
+## Data Directory Persistence
+
+The container exposes its data directory, `/consul/data`, as a [volume](https://docs.docker.com/engine/tutorials/dockervolumes/). This is where Consul will place its persisted state.


s/place/store

sethvargo · 2017-08-01T18:52:58Z

website/source/docs/guides/consul-containers.html.md

+
+Configuration can also be added by passing the configuration JSON via environment variable CONSUL_LOCAL_CONFIG. Example:
+
+```


Can we:

Add sh after the ticks to add syntax highlighting

Start the command with a $ to indicate it's a command

Left-flush this (it's indented very far right now

sethvargo · 2017-08-01T18:53:45Z

website/source/docs/guides/consul-containers.html.md

+```
+
+## 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_.


Can we combine this into:

When running inside a container, Consul must be configured with an appropriate cluster address and client address. In some cases, it may also require configuring an advertise address.

sethvargo · 2017-08-01T18:55:16Z

website/source/docs/guides/consul-containers.html.md

+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 \


Left align to the "```" + sh

sethvargo · 2017-08-01T18:55:30Z

website/source/docs/guides/consul-containers.html.md

+In the following example, the client and bind addresses are declaratively specified for the container network interface 'eth0'
+
+    ```
+        docker run \


Left align to the "```" + sh

sethvargo · 2017-08-01T18:57:22Z

website/source/docs/guides/consul-containers.html.md

+    ```
+
+## Stopping and Restarting Containers
+Consul containers can be stopped using the `docker stop <container_id>` command and restarted using `docker start <container_id>`. 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 [settings](/docs/agent/options.html#autopilot) are appropriate.


It's usually helpful to callout commands outside of the text. Consider:

The official Consul container supports stopping, starting, and restarting. To stop a container, use docker stop:

$ docker stop <container-id>

To start a container, run docker start:

$ docker start <container-id>

Is it worth mentioning docker kill here?

$ docker kill --signal="HUP" <container name or id>

That would also do an in-memory reload.

sethvargo · 2017-08-01T19:05:03Z

website/source/docs/guides/consul-containers.html.md

+* `last_contact_threshold` should be reasonably small, so that dead servers are removed quickly. 
+* `server_stabilization_time`should be sufficiently large( on the order of several seconds) so that unstable servers are not added to the cluster until they stabilize.
+
+If a container that was running a leader is stopped, leader election will be triggered causing another server in the cluster to assume leadership. 


If the container running the currently-elected Consul server leader is stopped, a leader election will trigger. This event will cause a new Consul server in the cluster to assume leadership.

sethvargo · 2017-08-01T19:05:48Z

website/source/docs/guides/consul-containers.html.md

+## Known Issues
+**Consul does not currently gracefully handle the situation where all nodes in the cluster running inside a container are restarted at the same time, and they all obtain new IP addresses.** This is because the underlying Raft layer persists the IP address and needs it for leader election operations. Operators must carefully orchestrate restarts of Consul containers that have ephemeral IP addresses to do restarts in small numbers, so that they can gracefully leave the cluster and re-join with their new IP address.
+
+**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 <source>-><destination>: write: broken pipe` when saving snapshots. This doesn't affect saving and restoring snapshots when running in Docker.


s/doesn't/does not

slackpad · 2017-08-01T21:11:20Z

website/source/docs/guides/consul-containers.html.md

+
+The container exposes its data directory, `/consul/data`, as a [volume](https://docs.docker.com/engine/tutorials/dockervolumes/). This is where Consul will store its persisted state.
+
+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.


I'd say "services and health checks"

slackpad · 2017-08-01T21:12:19Z

website/source/docs/guides/consul-containers.html.md

+
+ * **Cluster Address** -  The address at which other Consul agents may contact a given agent. This is also referred to as the bind address. 
+
+ * **Client Address** -  The address where other processes on the host contact Consul in order to make HTTP or DNS requests. Consider setting this to localhost or `127.0.0.1` to only allow processes on the same container to make http/DNS requests.


s/http/HTTP/

slackpad · 2017-08-01T21:12:37Z

website/source/docs/guides/consul-containers.html.md

+
+ * **Client Address** -  The address where other processes on the host contact Consul in order to make HTTP or DNS requests. Consider setting this to localhost or `127.0.0.1` to only allow processes on the same container to make http/DNS requests.
+
+ * **Advertise Address** - The advertise address is used to change the address that we advertise to other nodes in the cluster. This defaults to the bind address. Consider using this if you use NAT tables in your environment, or in scenarios where you have a routable address that cannot be bound


delete "tables"

Need a period at the end of this sentence.

slackpad · 2017-08-01T21:13:45Z

website/source/docs/guides/consul-containers.html.md

+
+* `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. 
+* `server_stabilization_time`should be sufficiently large( on the order of several seconds) so that unstable servers are not added to the cluster until they stabilize.


need a space before "should"

Also space after large, and there's an extra space inside the parens.

slackpad

Couple tiny things, then LGTM.

preetapan added 4 commits July 31, 2017 17:19

First pass at a consul containers guide

d45ceff

Capitalize Consul and Docker throughout

857a8e2

Addressed review comments

5dc07f2

More review feedback

fb28d55

preetapan requested review from sethvargo and slackpad August 1, 2017 15:41

preetapan added 3 commits August 1, 2017 11:13

More tweaks and grammar corrections

aa64d4b

Added a section on configuration

9c7cde3

Added links to new containers guide to navbar and index pages

d4fb271

sethvargo suggested changes Aug 1, 2017

View reviewed changes

Address more review comments

7e58245

slackpad reviewed Aug 1, 2017

View reviewed changes

Minor tweaks, fixed spacing issue with docker run examples

82b88cb

sethvargo approved these changes Aug 1, 2017

View reviewed changes

preetapan merged commit 5ca685a into master Aug 1, 2017

slackpad deleted the containers_guide branch August 8, 2017 18:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Containers guide #3347

Containers guide #3347

preetapan commented Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

sethvargo Aug 1, 2017

slackpad Aug 1, 2017

slackpad Aug 1, 2017

slackpad Aug 1, 2017

slackpad Aug 1, 2017

slackpad Aug 1, 2017

slackpad Aug 1, 2017

slackpad left a comment


		For major releases, make sure to read our [upgrade guides](/docs/upgrade-specific.html) before upgrading your cluster.

		To get a development mode consul instance running the latest version, run `docker run consul`.


		## Data Directory Persistence

		The container exposes its data directory, `/consul/data`, as a [volume](https://docs.docker.com/engine/tutorials/dockervolumes/). This is where Consul will place its persisted state.


		Configuration can also be added by passing the configuration JSON via environment variable CONSUL_LOCAL_CONFIG. Example:

		```


		The container exposes its data directory, `/consul/data`, as a [volume](https://docs.docker.com/engine/tutorials/dockervolumes/). This is where Consul will store its persisted state.

		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.


		* Cluster Address - The address at which other Consul agents may contact a given agent. This is also referred to as the bind address.

		* Client Address - The address where other processes on the host contact Consul in order to make HTTP or DNS requests. Consider setting this to localhost or `127.0.0.1` to only allow processes on the same container to make http/DNS requests.


		* Client Address - The address where other processes on the host contact Consul in order to make HTTP or DNS requests. Consider setting this to localhost or `127.0.0.1` to only allow processes on the same container to make http/DNS requests.

		* Advertise Address - The advertise address is used to change the address that we advertise to other nodes in the cluster. This defaults to the bind address. Consider using this if you use NAT tables in your environment, or in scenarios where you have a routable address that cannot be bound

Containers guide #3347

Containers guide #3347

Conversation

preetapan commented Aug 1, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slackpad left a comment

Choose a reason for hiding this comment