18702: add documentation for maintaining and upgrading Arvados. Make it

       clear that the Salt-based installer is only intended for
       installation.

Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <ward@curii.com>

diff --git a/doc/_config.yml b/doc/_config.yml
index eb0f173dfbcefae5c4c609026363ec1c93127b38..844866c409be679f90558c3a586681915e739963 100644 (file)
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -218,12 +218,14 @@ navbar:
     - Manual installation:
       - install/install-manual-prerequisites.html.textile.liquid
       - install/packages.html.textile.liquid
-      - admin/upgrading.html.textile.liquid
     - Configuration:
       - install/config.html.textile.liquid
       - admin/config-migration.html.textile.liquid
       - admin/config.html.textile.liquid
       - admin/config-urls.html.textile.liquid
+    - Maintenance and upgrading:
+      - admin/upgrading.html.textile.liquid
+      - install/maintenance-and-upgrading.html.textile.liquid
     - Core:
       - install/install-api-server.html.textile.liquid
     - Keep:

diff --git a/doc/admin/upgrading.html.textile.liquid b/doc/admin/upgrading.html.textile.liquid
index 2bd41829bea9ebb20fbd359a6cce5836a93177f8..7d77223263b0cc2c340c8acaa002beb5ef1f9c89 100644 (file)
--- a/doc/admin/upgrading.html.textile.liquid
+++ b/doc/admin/upgrading.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: installguide
-title: "Upgrading Arvados and Release notes"
+title: "Arvados upgrade notes"
 ...
 
 {% comment %}

diff --git a/doc/install/maintenance-and-upgrading.html.textile.liquid b/doc/install/maintenance-and-upgrading.html.textile.liquid
new file mode 100644 (file)
index 0000000..8cfbbe8
--- /dev/null
+++ b/doc/install/maintenance-and-upgrading.html.textile.liquid
@@ -0,0 +1,60 @@
+---
+layout: default
+navsection: installguide
+title: Maintenance and upgrading
+...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+# "Commercial support":#commercial_support
+# "Maintaining Arvados":#maintaining
+## "Modification of the config.yml file":#configuration
+## "Distributing the configuration file":#distribution
+## "Restart the services affected by the change":#restart
+# "Upgrading Arvados":#upgrading
+
+h2(#commercial_support). Commercial support
+
+Arvados is "100% open source software":{{site.baseurl}}/user/copying/copying.html. Anyone can download, install, maintain and upgrade it. However, if this is not something you want to spend your time and energy doing, "Curii Corporation":https://curii.com provides managed Arvados installations as well as commercial support for Arvados. Please contact "info@curii.com":mailto:info@curii.com for more information.
+
+If you'd prefer to do things yourself, a few starting points for a maintaining and upgrading Arvados can be found below.
+
+h2(#maintaining). Maintaining Arvados
+
+After Arvados is installed, periodic configuration changes may be required to adapt the software to your needs. Arvados uses a unified configuration file, which is normally found at @/etc/arvados/config.yml@.
+
+Making a configuration change to Arvados typically involves three steps:
+
+* modification of the @config.yml@ file
+* distribution of the modified file to the machines in the cluster
+* restarting of the services affected by the change
+
+h3(#configchange). Modification of the @config.yml@ file
+
+Consult the "configuration reference":{{site.baseurl}}/admin/config.html or another part of the documentation to identify the change to be made.
+
+Preserve a copy of your existing configuration file as a backup, and make the desired modification.
+
+Run @arvados-server config-check@ to make sure the configuration file has no errors and no warnings.
+
+h3(#distribution). Distribute the configuration file
+
+We recommend to keep the @config.yml@ file in sync between all the Arvados system nodes, to avoid issues with services running on different versions of the configuration.
+
+Distribution of the configuration file can be done in many ways, e.g. scp, configuration management software, etc.
+
+h3(#restart). Restart the services affected by the change
+
+If you know which Arvados service uses the specific configuration that was modified, restart those services. When in doubt, restart all Arvados system services.
+
+h2(#upgrading). Upgrading Arvados
+
+Upgrading Arvados typically involves the following steps:
+
+* consult the "upgrade notes":{{site.baseurl}}/admin/upgrading.html and the "release notes":https://arvados.org/releases/ for the release you want to upgrade to
+* rebuild and deploy the "compute node image":crunch2-cloud/install-compute-node.html (cloud only)
+* update the configuration file for the new release (see "Maintaining Arvados":#maintaining above)
+* upgrade the Arvados components on the system nodes

diff --git a/doc/install/salt-multi-host.html.textile.liquid b/doc/install/salt-multi-host.html.textile.liquid
index c3d6a92b5d9f019e28c26b622acd52c7ac2a9b89..d06a190ad05560e5b1c5b538f7431dd550eb8162 100644 (file)
--- a/doc/install/salt-multi-host.html.textile.liquid
+++ b/doc/install/salt-multi-host.html.textile.liquid
@@ -20,8 +20,7 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 # "Run the provision.sh script":#run_provision_script
 # "Initial user and login":#initial_user
 # "Test the installed cluster running a simple workflow":#test_install
-
-
+# "After the installation":#post_install
 
 h2(#introduction). Introduction
 
@@ -290,3 +289,9 @@ INFO Final output collection d6c69a88147dde9d52a418d50ef788df+123
 INFO Final process status is success
 </code></pre>
 </notextile>
+
+h2(#post_install). After the installation
+
+Once the installation is complete, it is recommended to keep a copy of your local configuration files. Committing them to version control is a good idea.
+
+Re-running the Salt-based installer is not recommended for maintaining and upgrading Arvados, please see "Maintenance and upgrading":maintenance-and-upgrading.html for more information.

diff --git a/doc/install/salt-single-host.html.textile.liquid b/doc/install/salt-single-host.html.textile.liquid
index ce70a30d467bc7f38bb75e1f4803e04df699cb86..a3fa63c25a20b1f096a41067a459eed7a4794728 100644 (file)
--- a/doc/install/salt-single-host.html.textile.liquid
+++ b/doc/install/salt-single-host.html.textile.liquid
@@ -20,6 +20,7 @@ SPDX-License-Identifier: CC-BY-SA-3.0
 ## "DNS configuration (single host / multiple hostnames)":#single_host_multiple_hostnames_dns_configuration
 # "Initial user and login":#initial_user
 # "Test the installed cluster running a simple workflow":#test_install
+# "After the installation":#post_install
 
 h2(#single_host). Single host install using the provision.sh script
 
@@ -266,3 +267,9 @@ INFO Final output collection d6c69a88147dde9d52a418d50ef788df+123
 INFO Final process status is success
 </code></pre>
 </notextile>
+
+h2(#post_install). After the installation
+
+Once the installation is complete, it is recommended to keep a copy of your local configuration files. Committing them to version control is a good idea.
+
+Re-running the Salt-based installer is not recommended for maintaining and upgrading Arvados, please see "Maintenance and upgrading":maintenance-and-upgrading.html for more information.