website: Upgrading 0.5 docs

website/source/docs/upgrade-specific.html.markdown

@@ -0,0 +1,81 @@
+---
+layout: "docs"
+page_title: "Upgrading Specific Versions"
+sidebar_current: "docs-upgrading-specific"
+description: |-
+  Specific versions of Consul may have additional information about the upgrade process beyond the standard flow.
+---
+
+# Upgrading Specific Versions
+
+The [upgrading page](/docs/upgrading.html) covers the details of doing
+a standard upgrade. However, specific versions of Consul may have more
+details provided for their upgrades as a result of new features or changed
+behavior. This page is used to document those details seperately from the
+standard upgrade flow.
+
+## Consul 0.5
+
+Consul version 0.5 adds two features that complicate the upgrade process:
+
+* ACL system includes service discovery and registration
+* Internal use of tombstones to fix behavior of blocking queries
+  in certain edge cases.
+
+Users of the ACL system need to be aware that deploying Consul 0.5 will
+cause service registration to be enforced. This means if an agent
+attempts to register a service without proper privileges it will be denied.
+If the `acl_default_policy` is "allow" then clients will continue to
+work without an updated policy. If the policy is "deny", then all clients
+will begin to have their registration rejected causing issues.
+
+To avoid this situation, all the ACL policies should be updated to
+add something like this:
+
+    # Enable all services to be registered
+    service "" {
+        policy = "write"
+    }
+
+This will set the service policy to `write` level for all services.
+The blank service name is the catch-all value. A more specific service
+can also be specified:
+
+    # Enable only the API service to be registered
+    service "api" {
+        policy = "write"
+    }
+
+The ACL policy can be updated while running 0.4, and enforcement will
+being with the upgrade to 0.5. The policy updates will ensure the
+availability of the cluster.
+
+The second major change is the new internal command used for tombstones.
+The details of the change are not important, however to function the leader
+node will replicate a new command to its followers. Consul is designed
+defensively, and when a command that is not recognized is received, the
+server will panic. This is a purposeful design decision to avoid the possibility
+of data loss, inconsistensies, or security issues caused by future incompatibility.
+
+In practice, this means if a Consul 0.5 node is the leader, all of its
+followers must also be running 0.5. There are a number of ways to do this
+to ensure cluster availability:
+
+* Add new 0.5 nodes, then remove the old servers. This will add the new
+  nodes as followers, and once the old servers are removed, one of the
+  0.5 nodes will become leader.
+
+* Upgrade the followers first, then the leader last. Using `consul info`,
+  you can determine which nodes are followers. Do an in-place upgrade
+  on them first, and finally upgrade the leader last.
+
+* Upgrade them in any order, but ensure all are done within 15 minutes.
+  Even if the leader is upgraded to 0.5 first, as long as all of the followers
+  are running 0.5 within 15 minutes there will be no issues.
+
+Finally, even if any of the methods above are not possible or the process
+fails for some reason, it is not fatal. The older version of the server
+will simply panic and stop. At that point, you can upgrade to the new version
+and restart the agent. There will be no data loss and the cluster will
+resume operations.
+

website/source/layouts/docs.erb

@@ -15,6 +15,10 @@
 
 					<li<%= sidebar_current("docs-upgrading-compat") %>>
 					<a href="/docs/compatibility.html">Compatibility Promise</a>
+                    </li>
+
+					<li<%= sidebar_current("docs-upgrading-specific") %>>
+					<a href="/docs/upgrade-specific.html">Specific Version Details</a>
 					</li>
 				</ul>
 				</li>