diff --git a/website/source/docs/compatibility.html.markdown b/website/source/docs/compatibility.html.markdown index aad6e0fb47..0ff0811221 100644 --- a/website/source/docs/compatibility.html.markdown +++ b/website/source/docs/compatibility.html.markdown @@ -1,27 +1,27 @@ --- layout: "docs" -page_title: "Serf Protocol Compatibility Promise" +page_title: "Consul Protocol Compatibility Promise" sidebar_current: "docs-upgrading-compatibility" --- # Protocol Compatibility Promise -We expect Serf to run in large clusters as long-running agents. Because +We expect Consul to run in large clusters as long-running agents. Because upgrading agents in this sort of environment relies heavily on protocol compatibility, this page makes it clear on our promise to keeping different -Serf versions compatible with each other. +Consul versions compatible with each other. -We promise that every subsequent release of Serf will remain backwards +We promise that every subsequent release of Consul will remain backwards compatible with _at least_ one prior version. Concretely: version 0.5 can speak to 0.4 (and vice versa), but may not be able to speak to 0.1. -The backwards compatibility must be explicitly enabled: Serf agents by +The backwards compatibility must be explicitly enabled: Consul agents by default will speak the latest protocol, but can be configured to speak earlier ones. If speaking an earlier protocol, _new features may not be available_. The ability for an agent to speak an earlier protocol is only so that they can be upgraded without cluster disruption. -This compatibility guarantee makes it possible to upgrade Serf agents one +This compatibility guarantee makes it possible to upgrade Consul agents one at a time, one version at a time. For more details on the specifics of upgrading, see the [upgrading page](/docs/upgrading.html). @@ -36,36 +36,5 @@ upgrading, see the [upgrading page](/docs/upgrading.html). 0.1 0 - -0.2 -0, 1 - - -0.3 -0, 1, 2   see warning below - - -0.4 -1, 2, 3   see warning below - -
-

-Warning: Version 0.3 introduces support for dynamic ports, allowing each -agent to bind to a different port. However, this feature is only supported -if all agents are running protocol version 2. Due to the nature of this -feature, it is hard to detect using the versioning scheme. If ports are kept -consistent across the cluster, then protocol version 2 is fully backwards -compatible. -

-
- -
-

-Warning: Version 0.4 introduces support for dynamic tags, allowing each -agent to provide key/value tags and update them without restarting. This feature is only supported -if all agents are running protocol version 3. If an agent is running an older protocol, -then only the "role" tag is supported for backwards compatibility. -

-
diff --git a/website/source/docs/upgrading.html.markdown b/website/source/docs/upgrading.html.markdown index 194ab96b32..dc5aa44743 100644 --- a/website/source/docs/upgrading.html.markdown +++ b/website/source/docs/upgrading.html.markdown @@ -1,67 +1,67 @@ --- layout: "docs" -page_title: "Upgrading Serf" +page_title: "Upgrading Consul" sidebar_current: "docs-upgrading-upgrading" --- -# Upgrading Serf +# Upgrading Consul -Serf is meant to be a long-running agent on any nodes participating in a -Serf cluster. These nodes consistently communicate with each other. As such, +Consul is meant to be a long-running agent on any nodes participating in a +Consul cluster. These nodes consistently communicate with each other. As such, protocol level compatibility and ease of upgrades is an important thing to -keep in mind when using Serf. +keep in mind when using Consul. -This page documents how to upgrade Serf when a new version is released. +This page documents how to upgrade Consul when a new version is released. -## Upgrading Serf +## Upgrading Consul -In short, upgrading Serf is a short series of easy steps. For the steps -below, assume you're running version A of Serf, and then version B comes out. +In short, upgrading Consul is a short series of easy steps. For the steps +below, assume you're running version A of Consul, and then version B comes out. -1. On each node, install version B of Serf. +1. On each node, install version B of Consul. 2. Shut down version A, and start version B with the `-protocol=PREVIOUS` flag, where "PREVIOUS" is the protocol version of version A (which can - be discovered by running `serf -v` or `serf members -detailed). + be discovered by running `consul -v` or `consul members -detailed`). 3. Once all nodes are running version B, go through every node and restart the version B agent _without_ the `-protocol` flag. -4. Done! You're now running the latest Serf agent speaking the latest protocol. - You can verify this is the case by running `serf members -detailed` to +4. Done! You're now running the latest Consul agent speaking the latest protocol. + You can verify this is the case by running `consul members -detailed` to make sure all members are speaking the same, latest protocol version. The key to making this work is the [protocol compatibility](/docs/compatibility.html) -of Serf. The protocol version system is discussed below. +of Consul. The protocol version system is discussed below. ## Protocol Versions -By default, Serf agents speak the latest protocol they can. However, each -new version of Serf is also able to speak the previous protocol, if there +By default, Consul agents speak the latest protocol they can. However, each +new version of Consul is also able to speak the previous protocol, if there were any protocol changes. -You can see what protocol versions your version of Serf understands by -running `serf -v`. You'll see output similar to that below: +You can see what protocol versions your version of Consul understands by +running `consul -v`. You'll see output similar to that below: ``` -$ serf -v -Serf v0.2.0 +$ consul -v +Consul v0.1.0 Agent Protocol: 1 (Understands back to: 0) ``` -This says the version of Serf as well as the latest protocol version (1, -in this case). It also says the earliest protocol version that this Serf +This says the version of Consul as well as the latest protocol version (1, +in this case). It also says the earliest protocol version that this Consul agent can understand (0, in this case). -By specifying the `-protocol` flag on `serf agent`, you can tell the -Serf agent to speak any protocol version that it can understand. This -only specifies the protocol version to _speak_. Every Serf agent can +By specifying the `-protocol` flag on `consul agent`, you can tell the +Consul agent to speak any protocol version that it can understand. This +only specifies the protocol version to _speak_. Every Consul agent can always understand the entire range of protocol versions it claims to -on `serf -v`. +on `consul -v`.
By running a previous protocol version, some features -of Serf, especially newer features, may not be available. If this is the -case, Serf will typically warn you. In general, you should always upgrade +of Consul, especially newer features, may not be available. If this is the +case, Consul will typically warn you. In general, you should always upgrade your cluster so that you can run the latest protocol version.