Docs: When setting up Geo, disable automatic Postgres upgrades
Problem
In this section https://docs.gitlab.com/omnibus/development/managing-postgresql-versions/#known-issues:
Known issues
Geo uses streaming replication, which requires that the entire secondary database be resynced after a major PostgreSQL upgrade. This can cause hours or days of downtime, and as such, we do not recommend auto upgrades for Geo customers. Starting in 12.10, automatic PostgreSQL upgrades are disabled if Geo is detected.
This line is not true in all cases:
Starting in 12.10, automatic PostgreSQL upgrades are disabled if Geo is detected.
More details
Automatic upgrade of PG is only skipped if:
-
roles ['geo_primary_role']orgeo_primary_role['enable'] = trueexists ingitlab.rb. This role is only relevant if you are running all GitLab services of the primary Geo site in a single node. -
roles ['geo_secondary_role']orgeo_secondary_role['enable'] = trueexists ingitlab.rb. This role is only relevant if you are running all GitLab services of a secondary Geo site in a single node. -
geo_postgresql['enable'] = trueingitlab.rb. This wouldn't be the case for primary Geo sites. And it wouldn't be the case if you are running the Geo tracking DB on a different node than the read-replica DB in a secondary Geo site.
Proposal
Opt out of automatic PG upgrades when setting up Geo.
Implementation Guide
In all Geo docs where a GitLab-managed PostgreSQL server is configured:
- Add a step to opt out of automatic PG upgrades.
- Be sure to link to https://docs.gitlab.com/omnibus/settings/database/#opt-out-of-automatic-postgresql-upgrades.
- Be sure to link to https://docs.gitlab.com/omnibus/settings/database/#caveats-when-upgrading-postgresql-with-geo because it says why you should do this.
- Be sure to mention that you will then need to upgrade Postgres yourself when the time comes. In any complex environment, for example 3k and up, it is safer to do this as a completely separate operation than upgrading GitLab anyway. One small configuration mistake or surprise is harder to find and fix when it's in the middle of many steps rather than a few steps.
Some relevant docs: