Goal:

Customers need to be able to upgrade their existing deployments. Today there are 2 guides: connected (6.18) and disconnected (6.18). At the end we expect to cover both scenarios in the new 6.19 upgrade guides. The upgrade helper derives its information from the guides through a manual process.

Acceptance Criteria:

• A Satellite or Capsule server can be upgraded in place
• A Satellite or Capsule server can be upgraded using backup on the old server & restore on a fresh server
• The upgrade guides (connected & disconnected) are updated with the new instructions
• The upgrade helper (https://access.redhat.com/labs/satelliteupgradehelper/) is updated to the new instructions (depends on the guides being upgraded).
• Make sure https://access.stage.redhat.com/labs/satelliteupgradehelper/ is upgraded so the steps can be tested before going live
• Upgrades are tested using automation
• Supported parameters are migrated to foremanctl

Open questions:

• Should we update the backup & restore documentation? Perhaps part of the support backup & restore porting
• Should we use satellite-clone?
• How do we get the new disconnected ISOs?
• How do we handle unsupported parameters?
• How do we handle custom-hiera.yaml when the customer specified some items?
• How do we handle the Upgrade Capsule jobs in Remote Execution? (https://github.com/theforeman/foreman_ansible/blob/master/app/views/foreman_ansible/job_templates/capsule_upgrade_-_ansible_default.erb)

Implementation suggestions:

Any parameter that is documented is considered supported today. We need to have a migration strategy for that (https://github.com/theforeman/foremanctl/blob/master/docs/parameters.md can help). Parameters listed in KCS articles are likely unsupported because KCS articles should say applicable versions. Especially if we do a major version bump then it should set the customer expectations right.

Implementation brainstorming

We have considered two upgrade scenarios:

• upgrade live 6.18 to live 6.19
• backup a 6.18 system and create a 6.19 instance based on the backup.

Assumption: we do not support upgrades others than from the latest 6.18

Current upgrade scenario looks like this:
1. stop services
2. verify upgradeability
3. update rpms
4. run rails migrations and pulp migrations
5. start the services
6. run foreman-maintain upgrade (which is a data migrations step implemented as rake tasks) See https://github.com/Katello/katello/tree/master/lib/katello/tasks/upgrades for examples.

The new upgrade process should look like this:
1. install foremanctl RPM (should not too much dependencies)
2. foremanctl extract [backup|live] - this step is responsible for gathering all the source configuration and data in a single known location to be consumed later. Let's call the data structure ctl_data. The data will come either from the live instance or from the backup.
3. foremanctl prepare - this step is responsible to take the configuration from the known location (ctl_data) parse it, analyze it for errors/conflicts e.t.c., ask the user for additional input (if needed) and generate a set of configuration files that can be consumed by foremanctl later on.
4. foreman-maintain stop (the 6.18 instance)
5. Remove rpms and do a proper cleanup of the config files
From this point the process is the same as for clean installations and 6.19+ upgrades.
6. pull containers
7. foremanctl stop
8. foremanctl deploy
8.1 create an empty DB (already existing step, that is not executed if the DB already exists)
8.2 Import DB data, if provided - This will take the data from the ctl_data, if we are in the backup/restore scenario. For other scenarios, this step will be a noop
8.3 run rails migrations
8.4 run pulp migrations
8.5 run data migrations (a.k.a. foreman-maintain upgrade). We assume designing a process similar to rails migrations that will have its own story under this epic.