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.