Merge pull request #3904 from vespa-engine/vekterli/add-maintenance-mode-to-ops-procedure

Add use of maintenance mode to admin procedure documentation

Author: vekterli

en/operations-selfhosted/admin-procedures.html

@@ -49,8 +49,32 @@ <h2 id="vespa-start-stop-restart">Vespa start / stop / restart</h2>
   See <a href="multinode-systems.html#aws-ec2">multinode</a> for <em>systemd</em> /<em>systemctl</em> examples.
   <a href="/en/operations-selfhosted/docker-containers.html">Docker containers</a> has relevant start/stop information, too.
 </p>
-
-
+<h3 id="content-node-maintenance-mode">Content node maintenance mode</h3>
+<p>
+  When stopping a content node <em>temporarily</em> (e.g. for a software upgrade), consider manually setting the node into
+  <a href="../reference/cluster-v2.html#maintenance">maintenance mode</a> <em>before</em> stopping the node to prevent
+  automatic redistribution of data while the node is down. Maintenance mode must be manually removed once the node has
+  come back online. See also: <a href="#cluster-state">cluster state</a>.
+</p>
+<p>
+  Example of setting a node with <a href="../reference/services-content.html#node">distribution key</a> 42 into
+  <code>maintenance</code> mode using <a href="vespa-cmdline-tools.html#vespa-set-node-state">vespa-set-node-state</a>,
+  additionally supplying a reason that will be recorded by the cluster controller:
+</p>
+<pre>
+  $ vespa-set-node-state --type storage --index 42 maintenance "rebooting for software upgrade"
+</pre>
+<p>
+  After the node has come back online, clear maintenance mode by marking the node as <code>up</code>:
+</p>
+<pre>
+  $ vespa-set-node-state --type storage --index 42 up
+</pre>
+<p>
+  Note that if the above commands are executed <em>locally</em> on the host running the services for node 42,
+  <code>--index 42</code> can be omitted; <code>vespa-set-node-state</code> will use the distribution key of
+  the local node if no <code>--index</code> has been explicitly specified.
+</p>
 
 <h2 id="system-status">System status</h2>
 <ul>