upgrading.md

Upgrading OpenAppStack

General considerations before upgrading

Include all potential new values of ansible/group_vars/all/settings.yml.example in your clusters/YOUR_CLUSTERNAME/group_vars/all/settings.yml. To find the differences (requires python yq package):

yq -y -rS . clusters/YOURCLUSTER/group_vars/all/settings.yml > /tmp/mine.yml
yq -y -rS . ansible/group_vars/all/settings.yml.example > /tmp/upstream.yml
diff /tmp/mine.yml /tmp/upstream.yml

Before you upgrade please look at the CHANGELOG.md file to review what changed between the versions.

Upgrading from 0.4.0 to 0.5.0

Unfortunatly we can't ensure a smooth upgrade for this version neither. Please read the section below on how to do an upgrade by installing a the new OAS version from scratch after backing up your data.

Upgrading from 0.3.0 to 0.4.0

There is no easy upgrade path from version 0.3.0 to version 0.4.0. As far as we know, nobody was running OpenAppStack apart from the developers, so we assume this is not a problem.

If you do need to upgrade, this is how you can migrate your data. Backup all the data available under /var/lib/OpenAppStack/local-storage, create a new cluster using the installation instructions, and putting back the data. This migration procedure might not work perfectly.

Use kubectl get pvc -A on your old cluster to get a mapping of all the PVC uuids (and thus their folder names in /var/lib/OpenAppStack/local-storage) to the pods they are bound to.

Then, delete your old OpenAppStack, and install a new one with version number 0.4.0 or higher. You can upload your backed up data into /var/lib/OpenAppStack/local-storage. All PVCs will have new unique IDs (and thus different folder names). You have to manually match the folders from your backup with the new folders.

Additionally, if you want to re-use your old settings.yaml file, this data needs to be added to it:

backup:
  s3:
    # Disabled by default. To enable, change to `true` and configure the
    # settings below. You'll also want to add "velero" to the enabled
    # applications a bit further in this file.
    # Finally, you'll also need to provide access credentials as
    # secrets; see the documentation:
    # https://docs.openappstack.net/en/latest/installation_instructions.html#step-2-optional-cluster-backups-using-velero
    enabled: false
    # URL of S3 service. Please use the principal domain name here, without the
    # bucket name.
    url: "https://store.greenhost.net"
    # Region of S3 service that's used for backups.
    # For some on-premise providers this may be irrelevant, but the S3
    # apparently requires it at some point.
    region: "ceph"
    # Name of the S3 bucket that backups will be stored in.
    # This has to exist already: Velero will not create it for you.
    bucket: "openappstack-backup"
    # Prefix that's added to backup filenames.
    prefix: "test-instance"

# A whitelist of applications that will be enabled.
enabled_applications:
  # System components, necessary for the system to function.
  - 'cert-manager'
  - 'letsencrypt-production'
  - 'letsencrypt-staging'
  - 'ingress'
  - 'local-path-provisioner'
  - 'single-sign-on'
  # The backup system Velero is disabled by default, see settings under `backup` above.
  # - 'velero'
  # Applications.
  - 'grafana'
  - 'loki'
  - 'promtail'
  - 'nextcloud'
  - 'prometheus'
  - 'rocketchat'
  - 'wordpress'

Upgrading to 0.3.0

Upgrading from versions earlier than 0.3.0 requires manual intervention.

• Move your local settings.yml file to a different location:

  cd CLUSTER_DIR
  mkdir -p ./group_vars/all/
  mv settings.yml ./group_vars/all/

• Flux is now used to install and update applications. For that reason, we need you to remove all helm charts (WARNING: You will lose your data!):

  helm delete --purge oas-test-cert-manager oas-test-local-storage \
      oas-test-prometheus oas-test-proxy oas-test-files`

  • After removing all helm charts, you probably also want to remove all the pvcs that are left behind. Flux will not re-use the database PVCs created for these applications. Find all the pvcs by running kubectl get pvc --namespace oas-apps and kubectl get pvc --namespace oas

Troubleshooting

If you encounter problems when you upgrade your cluster, please try again running the installation procedure before reporting an issue.