Katello/katello — pull request #1055 by lzap (2012-11-13 16:27:54+00:00)
Title: katello-upgrade redesign

Major katello-upgrade redesign. Scripts are now in one directory and the header specifies
if the script is "once" type or "always" type:

$ ls upgrade-scripts/ -1
README
0050_start_qpid.sh
0099_preallocate_mongo.sh
0100_start_mongodb.sh
0110_migrate_pulp.sh
0200_start_httpd.sh
0385_remove_hornet_files.sh
0390_migrate_candlepin.sh
0400_start_tomcat.sh
0410_start_elasticsearch.sh
0700_start_foreman.sh
0710_migrate_katello.sh
0711_reindex_elastic.sh
0720_create_foreman_users.rb
0800_start_katello.sh
0805_start_katello_jobs.sh
0900_katello_configure.sh

$ cat upgrade-scripts/README

This directory contains upgrade scripts. Before writing your first script,
please read katello-upgrade man page and read this file.

Header
------

Each script must have executable flag, shebang and header in the following
format:

#name: Short name starting with capital
#apply: katello headpin
#run: always
#description:
#Multiline description of the step. Please write several sentences
#here as users will be presented this before confirming this step.

Apply field must have space separated list of modes in which this script
applies. Possible values are: "katello" and "headpin".

Run field can be only set to "always" or "once".

ALL FIELDS ARE REQUIRED!

Script content
--------------

Scripts can be written in Bash, Python or Ruby. Make sure Python scripts
are not creating pyc/pyo files, use the following shebang:

#!/usr/bin/python -B

Script MUST return zero value when everything is fine, non-zero value
otherwise.

Both stdout and stderr are redirected to the log file (and stdout in
verbose mode). It is recommended to print several messages, but keep the
output not too much verbose

Multiple use
------------

ALL scripts MUST be invariant. That means user MUST be able to execute it
multiple times without breaking things.

Type of scripts
---------------

Always - script is executed every katello-upgrade run, it can be skipped
in the interactive mode, but it is executed by default.

Once - script is executed only once, then is "marked" as done and never
executed again.

Testing
-------

Always test your upgrade scripts on all supported platforms.

$ katello-upgrade --help
Katello upgrade script

Usage: /usr/sbin/katello-upgrade [options]

-a, --autostop Automatically stop services using "katello-service stop"
-y, --assumeyes Work non-intearactively and proceed without asking
-n, --dryrun Prints the upgrade steps without modifying anything
-q, --quiet Do not print anything on the stdout/stderr (only log)
--describe Only describe all the upgrade steps without modifying anything
--trace Print exception stacktrace on error
--noservicecheck Do not check if all services are stopped (use with care)
--norootcheck Disable check for root (use with care)
--deployment=DEPLOYMENT Force deployment mode (use with care)
-h, --help Show this short summary

$ katello-upgrade --describe
Upgrade plan:
Step: Start qpidd service (1/14)
Runs: always
Description: Start the service

Step: Start mongod service (2/14)
Runs: always
Description: Start the service

Step: Migrate MongoDB database (3/14)
Runs: always
Description: This steps calls pulp-migrate tool to migrate Pulp database schema
to the most recent version.

Step: Start Apache httpd service (4/14)
Runs: always
Description: Start the service

Step: Remove hornetq files (5/14)
Runs: always
Description: Certain Candlepin versions can contaion several directories with journal
data of hornetq daemon which needs to be removed.

Step: Migrate candlepin database (6/14)
Runs: always
Description: This step calls Candlepin cpdb utility to upgrade database schema
in postgresql database to the latest version.

Step: Start Apache tomcat6 service (7/14)
Runs: always
Description: Start the service

Step: Start elasticsearch service (8/14)
Runs: always
Description: Start the service

Step: Start foreman service (9/14)
Runs: always
Description: Start the service

Step: Migrate Katello database (10/14)
Runs: always
Description: This step calls rake db:migrate target to update Katello database schema in the
postgresql to the latest version.

Step: Reindex search index (11/14)
Runs: always
Description: This steps completely rebuild elasticsearch index from scratch. Due to upgrade of
the elasticsearch component it is necessary to flush the index before stopping
it and then reindexing it.

Step: Start katello service (12/14)
Runs: always
Description: Start the service

Step: Start katello-jobs service (13/14)
Runs: always
Description: Start the service

Step: Reconfigure with katello-configure (14/14)
Runs: always
Description: This steps calls katello-configure twice to re-deploy configuration
and restart services. Configuration files are replaced from erb templates
which are distributed as part of katello-configure package. Make sure you
have backup of all configuration files if you made any changes in it.

$ man katello-upgrade

NAME
katello-upgrade - Katello upgrade tool

SYNOPSIS
katello-upgrade
[ -a | --autostop ]
[ -y | --assumeyes ]
[ -n | --dryrun ]
[ -q | --quiet ]
[ --describe ]
[ --trace ]
[ --noservicecheck ]
[ --norootcheck ]
[ --deployment=DEPLOYMENT ]
[ -h | --help ]

DESCRIPTION
The katello-upgrade program will upgrade a previously installed version of katello to the latest version.
It guides user through the upgrade proces allowing to interrupt the process after each upgrade step.

Upgrade steps are divided into a separate scripts which can be found in
/usr/share/katello/install/upgrade-script directlry. There are two types of scripts, one groups is
executed every katello-upgrade run (always scripts) and the other group is executed only once (once
group).

Scripts that have been executed are "marked" in the /var/lib/katello/upgrade-history text file. If you
need, for some reason, to re-execute already marked script, delete the line in this file.

It is highly recommended to read Upgrade Guide and Release Notes documents before proceeding with the
upgrade. Manual steps are rarely necessary before running katello-upgrade.

Before procceeding, it is recommended to use --describe option to see all the steps and descriptions ahead
of time.

The katello-upgrade command works in interactive and non-interactive mode. In the interactive mode, one
can manually execute each step, skip steps and also terminate the upgrade process. Non-interactive mode is
set via -y option.

All the output is captured in the /var/log/katello/katello_upgrade.log file.

COMMAND LINE PARAMETERS
--autostop, -a
Stop all the services using katello-service stop command. If any service fails during stop action,
katello-upgrade terminates and you need to fix this manually. All the services are checked using
katello-service allstopped command before starting the upgrade process

--assumeyes, -y
Work non-interactively.

--dryrun, -n
Print the upgrade steps without doing anything.

--quiet, -q
Do not output anything on the stdout/stderr. Log file is still used.

--describe
Show all steps and descriptions which are planned for execution.

--trace
Print stacktrace on error (useful for debugging or reporting errors in katello-upgrade itself).

--noservicecheck
Do not check if all services are stopped prior upgrade (use with care).

--norootcheck
Do not check if executed under root account (do not use, only for debugging purposes).

--deployment=DEPLOYMENT
Force deployment (katello or headpin) instead of detecting this from the answer file (do not use, only
for debugging purposes).

--help, -h
Display short summary of all options.