From 1fc3e6081d1d016184f328af84c1aaf330920be0 Mon Sep 17 00:00:00 2001 From: Ward Vandewege Date: Wed, 16 Feb 2022 10:39:41 -0500 Subject: [PATCH] 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 --- doc/_config.yml | 4 +- doc/admin/upgrading.html.textile.liquid | 2 +- ...ntenance-and-upgrading.html.textile.liquid | 60 +++++++++++++++++++ .../salt-multi-host.html.textile.liquid | 9 ++- .../salt-single-host.html.textile.liquid | 7 +++ 5 files changed, 78 insertions(+), 4 deletions(-) create mode 100644 doc/install/maintenance-and-upgrading.html.textile.liquid diff --git a/doc/_config.yml b/doc/_config.yml index eb0f173dfb..844866c409 100644 --- 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 2bd41829be..7d77223263 100644 --- 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 index 0000000000..8cfbbe8dcb --- /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 c3d6a92b5d..d06a190ad0 100644 --- 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 + +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 ce70a30d46..a3fa63c25a 100644 --- 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 + +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. -- 2.30.2