From 689c8bc934acefdb918025b063b28d3f31db32e0 Mon Sep 17 00:00:00 2001
From: Kyle Havlovitz <kylehav@gmail.com>
Date: Tue, 18 Jul 2017 14:01:21 -0700
Subject: [PATCH] Add UpgradeVersionTag information to docs

---
 website/source/api/operator/autopilot.html.md  |  8 +++++++-
 .../operator/autopilot.html.markdown.erb       |  4 ++++
 website/source/docs/guides/autopilot.html.md   | 18 +++++++++++++++++-
 3 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/website/source/api/operator/autopilot.html.md b/website/source/api/operator/autopilot.html.md
index 5edfffb11b..03fee5c6e9 100644
--- a/website/source/api/operator/autopilot.html.md
+++ b/website/source/api/operator/autopilot.html.md
@@ -60,6 +60,7 @@ $ curl \
   "ServerStabilizationTime": "10s",
   "RedundancyZoneTag": "",
   "DisableUpgradeMigration": false,
+  "UpgradeVersionTag": "",
   "CreateIndex": 4,
   "ModifyIndex": 4
 }
@@ -110,7 +111,7 @@ The table below shows this endpoint's support for
   cluster. Only takes effect if all servers are running Raft protocol version 3
   or higher. Must be a duration value such as `30s`.
 
-- `RedundancyZoneTag` `(string: "")` controls the node-meta key to use when
+- `RedundancyZoneTag` `(string: "")` - Controls the node-meta key to use when
   Autopilot is separating servers into zones for redundancy. Only one server in
   each zone can be a voting member at one time. If left blank, this feature will
   be disabled.
@@ -120,6 +121,10 @@ The table below shows this endpoint's support for
   newer-versioned servers have been added to the cluster before promoting any of
   them to voters.
 
+- `UpgradeVersionTag` `(string: "")` - Controls the node-meta key to use for
+  version info when performing upgrade migrations. If left blank, the Consul
+  version will be used.
+
 ### Sample Payload
 
 ```json
@@ -130,6 +135,7 @@ The table below shows this endpoint's support for
   "ServerStabilizationTime": "10s",
   "RedundancyZoneTag": "",
   "DisableUpgradeMigration": false,
+  "UpgradeVersionTag": "",
   "CreateIndex": 4,
   "ModifyIndex": 4
 }
diff --git a/website/source/docs/commands/operator/autopilot.html.markdown.erb b/website/source/docs/commands/operator/autopilot.html.markdown.erb
index 39e47cfe02..79e113ee6c 100644
--- a/website/source/docs/commands/operator/autopilot.html.markdown.erb
+++ b/website/source/docs/commands/operator/autopilot.html.markdown.erb
@@ -46,6 +46,7 @@ MaxTrailingLogs = 250
 ServerStabilizationTime = 10s
 RedundancyZoneTag = ""
 DisableUpgradeMigration = false
+UpgradeMigrationTag = ""
 ```
 
 ## set-config
@@ -80,6 +81,9 @@ new servers until it can perform a migration. Must be one of `[true|false]`.
 * `-redundancy-zone-tag`- (Enterprise-only) Controls the [`-node-meta`](/docs/agent/options.html#_node_meta)
 key name used for separating servers into different redundancy zones.
 
+* `-upgrade-version-tag` - (Enterprise-only) Controls the [`-node-meta`](/docs/agent/options.html#_node_meta)
+tag to use for version info when performing upgrade migrations. If left blank, the Consul version will be used.
+
 The output looks like this:
 
 ```
diff --git a/website/source/docs/guides/autopilot.html.md b/website/source/docs/guides/autopilot.html.md
index 0ffbcc0d13..791986a635 100644
--- a/website/source/docs/guides/autopilot.html.md
+++ b/website/source/docs/guides/autopilot.html.md
@@ -32,7 +32,8 @@ bootstrapping the cluster:
     "max_trailing_logs": 250,
     "server_stabilization_time": "10s",
     "redundancy_zone_tag": "az",
-    "disable_upgrade_migration": false
+    "disable_upgrade_migration": false,
+    "upgrade_version_tag": ""
 }
 ```
 
@@ -49,6 +50,7 @@ MaxTrailingLogs = 250
 ServerStabilizationTime = 10s
 RedundancyZoneTag = ""
 DisableUpgradeMigration = false
+UpgradeVersionTag = ""
 
 $ consul operator autopilot set-config -cleanup-dead-servers=false
 Configuration updated!
@@ -60,6 +62,7 @@ MaxTrailingLogs = 250
 ServerStabilizationTime = 10s
 RedundancyZoneTag = ""
 DisableUpgradeMigration = false
+UpgradeVersionTag = ""
 ```
 
 ## Dead Server Cleanup
@@ -200,3 +203,16 @@ node2  127.0.0.1:8703  alive   server  0.7.5  2         dc1
 node3  127.0.0.1:8803  alive   server  0.7.5  2         dc1
 node4  127.0.0.1:8203  alive   server  0.8.0  2         dc1
 ```
+
+### Using migrations without a Consul version change
+
+The `UpgradeVersionTag` can be used to override the version information used during
+a migration, so that the migration logic can be used for updating the cluster when
+changing configuration.
+
+If the `UpgradeVersionTag` setting is set, Consul will use its value to look for a
+version in each server's specified [`-node-meta`](/docs/agent/options.html#_node_meta)
+tag. For example, if `UpgradeVersionTag` is set to `build`, and `-node-meta build:0.0.2`
+is used when starting a server, that server's version will be `0.0.2` when considered in
+a migration. The upgrade logic will follow semantic versioning and the version string
+must be in the form of either `X`, `X.Y`, or `X.Y.Z`.
\ No newline at end of file