Skip to content

Commit 4929dd2

Browse files
FxKuFxKu
authored
Update major version upgrade docs (zalando#2807)
* Update major version upgrade logs
1 parent fc9a260 commit 4929dd2

File tree

1 file changed

+33
-15
lines changed

1 file changed

+33
-15
lines changed

‎docs/administrator.md

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -63,14 +63,17 @@ the `PGVERSION` environment variable is set for the database pods. Since
6363
`v1.6.0` the related option `enable_pgversion_env_var` is enabled by default.
6464

6565
In-place major version upgrades can be configured to be executed by the
66-
operator with the `major_version_upgrade_mode` option. By default it is set
67-
to `off` which means the cluster version will not change when increased in
68-
the manifest. Still, a rolling update would be triggered updating the
69-
`PGVERSION` variable. But Spilo's [`configure_spilo`](https://github.com/zalando/spilo/blob/master/postgres-appliance/scripts/configure_spilo.py)
70-
script will notice the version mismatch and start the old version again.
71-
72-
In this scenario the major version could then be run by a user from within the
73-
primary pod. Exec into the container and run:
66+
operator with the `major_version_upgrade_mode` option. By default, it is
67+
enabled (mode: `manual`). In any case, altering the version in the manifest
68+
will trigger a rolling update of pods to update the `PGVERSION` env variable.
69+
Spilo's [`configure_spilo`](https://github.com/zalando/spilo/blob/master/postgres-appliance/scripts/configure_spilo.py)
70+
script will notice the version mismatch but start the current version again.
71+
72+
Next, the operator would call an updage script inside Spilo. When automatic
73+
upgrades are disabled (mode: `off`) the upgrade could still be run by a user
74+
from within the primary pod. This gives you full control about the point in
75+
time when the upgrade can be started (check also maintenance windows below).
76+
Exec into the container and run:
7477
```bash
7578
python3 /scripts/inplace_upgrade.py N
7679
```
@@ -79,17 +82,32 @@ The upgrade is usually fast, well under one minute for most DBs. Note, that
7982
changes become irrevertible once `pg_upgrade` is called. To understand the
8083
upgrade procedure, refer to the [corresponding PR in Spilo](https://github.com/zalando/spilo/pull/488).
8184

82-
When `major_version_upgrade_mode` is set to `manual` the operator will run
83-
the upgrade script for you after the manifest is updated and pods are rotated.
84-
It is also possible to define `maintenanceWindows` in the Postgres manifest to
85-
better control when such automated upgrades should take place after increasing
86-
the version.
85+
When `major_version_upgrade_mode` is set to `full` the operator will compare
86+
the version in the manifest with the configured `minimal_major_version`. If it
87+
is lower the operator would start an automatic upgrade as described above. The
88+
configured `major_target_version` will be used as the new version. This option
89+
can be useful if you have to get rid of outdated major versions in your fleet.
90+
Please note, that the operator does not patch the version in the manifest.
91+
Thus, the `full` mode can create drift between desired and actual state.
92+
93+
### Upgrade during maintenance windows
94+
95+
When `maintenanceWindows` are defined in the Postgres manifest the operator
96+
will trigger a major version upgrade only during these periods. Make sure they
97+
are at least twice as long as your configured `resync_period` to guarantee
98+
that operator actions can be triggered.
8799

88100
### Upgrade annotations
89101

90-
When an upgrade is executed, the operator sets an annotation in the PostgreSQL resource, either `last-major-upgrade-success` if the upgrade succeeds, or `last-major-upgrade-failure` if it fails. The value of the annotation is a timestamp indicating when the upgrade occurred.
102+
When an upgrade is executed, the operator sets an annotation in the PostgreSQL
103+
resource, either `last-major-upgrade-success` if the upgrade succeeds, or
104+
`last-major-upgrade-failure` if it fails. The value of the annotation is a
105+
timestamp indicating when the upgrade occurred.
91106

92-
If a PostgreSQL resource contains a failure annotation, the operator will not attempt to retry the upgrade during a sync event. To remove the failure annotation, you can revert the PostgreSQL version back to the current version. This action will trigger the removal of the failure annotation.
107+
If a PostgreSQL resource contains a failure annotation, the operator will not
108+
attempt to retry the upgrade during a sync event. To remove the failure
109+
annotation, you can revert the PostgreSQL version back to the current version.
110+
This action will trigger the removal of the failure annotation.
93111

94112
## Non-default cluster domain
95113

0 commit comments

Comments
 (0)