Skip to main content
Version: Develop

a9s PostgreSQL Ubuntu Jammy BOSH Stemcell Upgrade

Disclaimer

With the introduction of Ubuntu Jammy to a9s PostgreSQL the default BOSH stemcell for a9s PostgreSQL has been set to Ubuntu Jammy.

This change requires you to freeze existing a9s PostgreSQL 13 Service Plans to Ubuntu Bionic when you have existing a9s PostgreSQL 13 Service Instances. This is necessary, even if:

  • An upgrade of existing a9s PostgreSQL Service Instances to Ubuntu Jammy is planned in the near future.
  • No upgrade of existing a9s PostgreSQL Service Instances to Ubuntu Jammy is planned at all.

Nevertheless, please be aware that upgrading the BOSH stemcell of existing a9s PostgreSQL Service Instances from Ubuntu Bionic to Ubuntu Jammy needs to be performed very carefully!

Therefore, please make sure you read and understand all of the following document before starting the upgrade!

This document describes and collects all important information regarding the upgrade of existing a9s PostgreSQL Service Instances from a BOSH stemcell based on Ubuntu Bionic to a BOSH stemcell based on Ubuntu Jammy, which from this point on will be named Ubuntu Bionic and Ubuntu Jammy respectively.

Overview​

Ubuntu Jammy is supported for a9s PostgreSQL 13 and above. For a9s PostgreSQL 11 and below Ubuntu Jammy is NOT supported, wherefore, the used BOSH stemcell is hardcoded to the latest available Ubuntu Bionic BOSH stemcell.

While Ubuntu Jammy's compatibility with PostgreSQL 13 and above is not a problem per-se, existing instances of PostgreSQL 13 are affected by a breaking change in the GNU C library (glibc), that can potentially affect the user data. According to the offical PostgreSQL documentation, this issue can be resolved by rebuilding the indexes of these instances.

This means that, for all intents and purposes, in the case of PostgreSQL 13 we have two paths:

It should be noted that when you have Service Instances of a9s PostgreSQL 11 and below, it is necessary to migrate them to a9s PostgreSQL 13 or above via Dump and Restore From Origin Instance to New Instance if Ubuntu Jammy must be used. However, you must do this after following one of the paths presented above first and not before.

Upgrading to Ubuntu Jammy - With Pre-existing a9s PostgreSQL 13 Service Instances Exist​

Freeze Existing a9s PostgreSQL 13 Service Plans to Ubuntu Bionic​

The existing Service Plans for a9s PostgreSQL must be configured to use the a9s PostgreSQL 13 templates with the hardcoded Ubuntu Bionic BOSH stemcell. For each existing a9s PostgreSQL 13 template exists a comparable template, with the postfix -bionic, which has Ubuntu Bionic hardcoded.

The existing Ubuntu Bionic Service Plans have to be configured to reference the template names like this:

template_name_v2: <template-name>-bionic

Upgrade Existing a9s PostgreSQL 13 Service Instances​

In general, the steps to upgrade existing a9s PostgreSQL 13 Service Instances must be performed in the following order, after freezing existing a9s PostgreSQL 13 Service Plans to Ubuntu Bionic:

  1. The Platform Operator introduces new Service Plans for a9s PostgreSQL 13 Service Instances on Ubuntu Jammy
  2. The Platform Operator prevents the creation of new a9s PostgreSQL 13 Service Instances on Ubuntu Bionic
  3. The Application Developers migrate their Service Instances

Add New a9s PostgreSQL 13 Ubuntu Jammy Service Plans​

After freezing the existing plans it is necessary to create a new set of Service Plans equal to the currently used set of Service Plans for a9s PostgreSQL 13, so that all new Service Instances can be created with Ubuntu Jammy while the existing Service Instances remain untouched and can be later migrated.

The new Service Plans must be configured to use the templates which are using the configured BOSH stemcell from the IaaS-config. In the IaaS-config the Ubuntu Jammy stemcell must be configured for the a9s PostgreSQL Data Service.

The new Ubuntu Jammy Service Plans have to be configured to reference the template names like this:

template_name_v2: <template-name>
Enable Migration from Ubuntu Bionic to Ubuntu Jammy Service Plans​

The Platform Operator can enable the migration from an Ubuntu Bionic Service Plan to an Ubuntu Jammy Service Plan by adding the Ubuntu Jammy Service Plan to the migration_paths of the corresponding Ubuntu Bionic Service Plan.

This configuration enables the Application Developers to update their Service Instances to an Ubuntu Jammy Service Plan. On Cloud Foundry this can be done using the CF CLI for example.

caution

Migrations from Ubuntu Jammy Service Plans back to Ubuntu Bionic Service Plans should NOT be allowed.

Example​

These Service Plans need to be configured inside the service-config file of the a9s PostgreSQL Data Service. An example for such a configuration can be found in the anynines-deployment repository.

postgresql_service:
  services:
    a9s-postgresql13:
      name: a9s-postgresql13
      guid: 17a48e43-c36b-4873-b4c9-ea884d4d1894
      description: This is a service creating and managing dedicated PostgreSQL service instances and clusters, powered by the a9s Service Framework
      label: a9s-postgresql
      version: 13
      bindable: true
      requires: []
      tags: [sql, database, object-relational, consistent]
      documentation_url: https://docs.anynines.com/
      metadata:
        displayName: a9s PostgreSQL 13
        supportUrl: https://anynines.atlassian.net/servicedesk/customer/portals
        documentationUrl: https://docs.anynines.com/
        shareable: true
      dashboard_client:
        id: a9s-postgresql-dashboard-client-id
      plans:
        postgresql-replica-small: # Existing Service Plan with Ubuntu Bionic
          guid: 03a1358d-7494-4ee2-83de-7d602599b228
          description: A small replica set with Ubuntu Bionic
          free: true
          template_name_v2: postgresql13-replica-bionic
          default_placeholder_values:
            vm_type: postgresql-replica-small
            persistent_disk_type: postgresql-replica-small
          migration_paths:
            - postgresql-replica-small-jammy
        postgresql-replica-small-jammy: # New Service Plan for Ubuntu Jammy
          guid: 2e32975e-9704-4c36-b98d-498cd2db4bcf
          description: A small replica set with Ubuntu Jammy
          free: true
          template_name_v2: postgresql13-replica
          default_placeholder_values:
            vm_type: postgresql-replica-small
            persistent_disk_type: postgresql-replica-small
          migration_paths: []

Disable Old a9s PostgreSQL 13 Ubuntu Bionic Service Plans​

After the new Service Plans are added and the existing Service Plans are adapted accordingly, the creation of new a9s PostgreSQL 13 Service Instances with Ubuntu Bionic can be prevented and only the creation of Service Instances with Ubuntu Jammy can be allowed.

On Cloud Foundry this can be done via the access control settings for the corresponding Service Plans for example.

Migrate Existing Service Instances​

While existing a9s PostgreSQL 13 Service Instances will continue to run on Ubuntu Bionic they can later be migrated to a9s PostgreSQL 13 and above with Ubuntu Jammy. To do so, the Application Developers, as the owners of the data, can schedule a maintenance window to manually migrate their existing a9s PostgreSQL 13 Service Instances to an Ubuntu Jammy Service Plan. During this maintenance window they must apply one of the options below for their existing a9s PostgreSQL 13 Service Instances to ensure the compatibility of the data. This avoids potential side effects that come with upgrades to Ubuntu Jammy.

Perform Reindexing of the Service Instance​

For performing the reindexing, there are two options available:

  • Reindex: Use the PostgreSQL command REINDEX to rebuild all necessary indices. See PostgreSQL REINDEX for the documentation on how to use the command.
  • Drop and recreate index: If reindexing is not an option due to resource constraints, you can also drop all indices and recreate them using the DROP INDEX and CREATE INDEX commands. See PostgreSQL DROP INDEX and PostgreSQL CREATE INDEX for the documentation on how to use those commands.
caution

Reindexing can take a lot of time, even hours depending on the maintenance_work_mem size and the amount of data, so increasing the maintenance_work_mem can help speed up the process. Furthermore, reindex will consume twice the index size of disk space because the new index is built while the old one is kept. Thus, drop index and recreate may be a better choice under some circumstances. In any case, the Application Developer has to check the available disk space and index size and plan the update accordingly, possibly considering an upgrade to a larger Service Plan.

Upgrading to Ubuntu Jammy - Without Pre-existing a9s PostgreSQL 13 Service Instances Exist​

If you do not have pre-existing a9s PostgreSQL Service Instances, then no additional steps are necessary and the Service Plans can just be configured to use the corresponding templates with Ubuntu Jammy.

However, we recommend that you migrate to existing PostgreSQL 11 to PostgreSQL 13 as soon as the Ubuntu Jammy upgrade has taken place. For more information on why you should consider migrating please see our FAQ.

FAQ​

Q: Why is a9s PostgreSQL 11 not supported on Ubuntu Jammy?
A: In PostgreSQL 11, among others, gdal has to be updated to gdal3, which is no longer supported by PostGis 2 and would require a migration. Since PostgreSQL 11 will become EOL in September 2023, support for Jammy for this version will not be implemented by anynines and our recommendation is to migrate to PostgreSQL 13 or above.

Q: If we have an a9s PostgreSQL 13 Service Instance with PITR enabled and a restore to a point-in-time before the upgrade to Ubuntu Jammy and the reindex is executed, is it necessary to perform another reindex?
A: Yes, Reindexing must be executed after running PITR and restoring a backup and WAL files taken in Ubuntu Bionic.

Q: If we have an a9s PostgreSQL 13 Service Instance without PITR enabled and a backup created before the upgrade to Ubuntu Jammy and the reindex is restored, is it necessary to perform another reindex?
A: No, with logical backups no Reindexing is necessary after restoring a backup in Ubuntu Jammy that was taken in Ubuntu Bionic.

Q: We have an a9s PostgreSQL 13 Service Instance on Ubuntu Bionic which the Application Developer cloned into a new a9s PostgreSQL 13 and above Service Instance on Ubuntu Jammy via copy_from, is it necessary to perform a reindex?
A: There is no Reindexing necessary after using copy_from.