|
| 1 | +# Upgrade to v0.50.x |
| 2 | + |
| 3 | +> [!WARNING] |
| 4 | +> Upgrade only supported from v0.49.x. |
| 5 | +
|
| 6 | +<!-- |
| 7 | +Notice to developers on writing migration steps: |
| 8 | +
|
| 9 | +- Migration steps: |
| 10 | + - are written per minor version and placed in a subdirectory of the migration directory with the name `vX.Y/`, |
| 11 | + - are written to be idempotent and usable no matter which patch version you are upgrading from and to, |
| 12 | + - are documented in this document to be able to run them manually, |
| 13 | + - are divided into prepare and apply steps: |
| 14 | + - Prepare steps: |
| 15 | + - are placed in the `prepare/` directory, |
| 16 | + - may **only** modify the configuration of the environment, |
| 17 | + - may **not** modify the state of the environment, |
| 18 | + - steps are run in order of their names use two digit prefixes. |
| 19 | + - Apply steps: |
| 20 | + - are placed in the `apply/` directory, |
| 21 | + - may **only** modify the state of the environment, |
| 22 | + - may **not** modify the configuration of the environment, |
| 23 | + - are run in order of their names use two digit prefixes, |
| 24 | + - are run with the argument `execute` on upgrade and should return 1 on failure and 2 on successful internal rollback, |
| 25 | + - are rerun with the argument `rollback` on execute failure and should return 1 on failure. |
| 26 | +
|
| 27 | +For prepare the init step is given. |
| 28 | +For apply the bootstrap and the apply steps are given, it is expected that releases upgraded in custom steps are excluded from the apply step. |
| 29 | +
|
| 30 | +Upgrades of components that are dependent on each other should be done within the same snippet to easily manage the upgrade to a working state and to be able to rollback to a working state. |
| 31 | +
|
| 32 | +Steps should use the `scripts/migration/lib.sh` which will provide helper functions, see the file for available helper functions. |
| 33 | +This script expects the `ROOT` environment variable to be set pointing to the root of the repository. |
| 34 | +As with all scripts in this repository `CK8S_CONFIG_PATH` is expected to be set. |
| 35 | +--> |
| 36 | + |
| 37 | +## Prerequisites |
| 38 | + |
| 39 | +- [ ] Read through the changelog to check if there are any changes you need to be aware of. Read through the release notes, Platform Administrator notices, Application Developer notices, and Security notice. |
| 40 | +- [ ] Notify the users (if any) before the upgrade starts; |
| 41 | +- [ ] Check if there are any pending changes to the environment; |
| 42 | +- [ ] Check the state of the environment, pods, nodes and backup jobs: |
| 43 | + |
| 44 | + ```bash |
| 45 | + ./bin/ck8s test sc|wc |
| 46 | + ./bin/ck8s ops kubectl sc|wc get pods -A -o custom-columns=NAMESPACE:metadata.namespace,POD:metadata.name,READY-false:status.containerStatuses[*].ready,REASON:status.containerStatuses[*].state.terminated.reason | grep false | grep -v Completed |
| 47 | + ./bin/ck8s ops kubectl sc|wc get nodes |
| 48 | + ./bin/ck8s ops kubectl sc|wc get jobs -A |
| 49 | + ./bin/ck8s ops helm sc|wc list -A --all |
| 50 | + ./bin/ck8s ops velero sc|wc get backup |
| 51 | + ``` |
| 52 | + |
| 53 | +- [ ] Silence the notifications for the alerts. e.g you can use [alertmanager silences](https://prometheus.io/docs/alerting/latest/alertmanager/#silences); |
| 54 | + |
| 55 | +## Automatic method |
| 56 | + |
| 57 | +1. Pull the latest changes and switch to the correct branch: |
| 58 | + |
| 59 | + ```bash |
| 60 | + git pull |
| 61 | + git switch -d v0.50.x |
| 62 | + ``` |
| 63 | + |
| 64 | +1. Prepare upgrade - _non-disruptive_ |
| 65 | + |
| 66 | + > _Done before maintenance window._ |
| 67 | + |
| 68 | + ```bash |
| 69 | + ./bin/ck8s upgrade both v0.50 prepare |
| 70 | +
|
| 71 | + # check if the netpol IPs need to be updated |
| 72 | + ./bin/ck8s update-ips both dry-run |
| 73 | + # if you agree with the changes apply |
| 74 | + ./bin/ck8s update-ips both apply |
| 75 | + ``` |
| 76 | + |
| 77 | + > **Note:** |
| 78 | + > It is possible to upgrade `wc` and `sc` clusters separately by replacing `both` when running the `upgrade` command, e.g. the following will only upgrade the workload cluster: |
| 79 | + |
| 80 | + ```bash |
| 81 | + ./bin/ck8s upgrade wc v0.50 prepare |
| 82 | + ./bin/ck8s upgrade wc v0.50 apply |
| 83 | + ``` |
| 84 | + |
| 85 | +1. Apply upgrade - _disruptive_ |
| 86 | + |
| 87 | + > _Done during maintenance window._ |
| 88 | + |
| 89 | + ```bash |
| 90 | + ./bin/ck8s upgrade both v0.50 apply |
| 91 | + ``` |
| 92 | + |
| 93 | +## Manual method |
| 94 | + |
| 95 | +### Prepare upgrade - _non-disruptive_ |
| 96 | + |
| 97 | +> _Done before maintenance window._ |
| 98 | + |
| 99 | +1. Pull the latest changes and switch to the correct branch: |
| 100 | + |
| 101 | + ```bash |
| 102 | + git pull |
| 103 | + git switch -d v0.50.x |
| 104 | + ``` |
| 105 | + |
| 106 | +1. Set whether or not upgrade should be prepared for `both` clusters or for one of `sc` or `wc`: |
| 107 | + |
| 108 | + ```bash |
| 109 | + export CK8S_CLUSTER=<wc|sc|both> |
| 110 | + ``` |
| 111 | + |
| 112 | +1. Update apps configuration: |
| 113 | + |
| 114 | + This will take a backup into `backups/` before modifying any files. |
| 115 | + |
| 116 | + ```bash |
| 117 | + ./bin/ck8s init ${CK8S_CLUSTER} |
| 118 | + # or |
| 119 | + ./migration/v0.50/prepare/50-init.sh |
| 120 | +
|
| 121 | + # check if the netpol IPs need to be updated |
| 122 | + ./bin/ck8s update-ips ${CK8S_CLUSTER} dry-run |
| 123 | + # if you agree with the changes apply |
| 124 | + ./bin/ck8s update-ips ${CK8S_CLUSTER} apply |
| 125 | + ``` |
| 126 | + |
| 127 | +### Apply upgrade - _disruptive_ |
| 128 | + |
| 129 | +> _Done during maintenance window._ |
| 130 | + |
| 131 | +1. Set whether or not upgrade should be applied for `both` clusters or for one of `sc` or `wc`: |
| 132 | + |
| 133 | + ```bash |
| 134 | + export CK8S_CLUSTER=<wc|sc|both> |
| 135 | + ``` |
| 136 | + |
| 137 | +1. Upgrade applications: |
| 138 | + |
| 139 | + ```bash |
| 140 | + ./bin/ck8s apply {sc|wc} |
| 141 | + # or |
| 142 | + ./migration/v0.50/apply/80-apply.sh execute |
| 143 | + ``` |
| 144 | + |
| 145 | +## Postrequisite |
| 146 | + |
| 147 | +- [ ] Check the state of the environment, pods and nodes: |
| 148 | + |
| 149 | + ```bash |
| 150 | + ./bin/ck8s test sc|wc |
| 151 | + ./bin/ck8s ops kubectl sc|wc get pods -A -o custom-columns=NAMESPACE:metadata.namespace,POD:metadata.name,READY-false:status.containerStatuses[*].ready,REASON:status.containerStatuses[*].state.terminated.reason | grep false | grep -v Completed |
| 152 | + ./bin/ck8s ops kubectl sc|wc get nodes |
| 153 | + ./bin/ck8s ops helm sc|wc list -A --all |
| 154 | + ``` |
| 155 | + |
| 156 | +- [ ] Enable the notifications for the alerts; |
| 157 | +- [ ] Notify the users (if any) when the upgrade is complete; |
| 158 | + |
| 159 | +> [!NOTE] |
| 160 | +> Additionally it is good to check: |
| 161 | +> |
| 162 | +> - if any alerts generated by the upgrade didn't close; |
| 163 | +> - if you can login to Grafana, Opensearch or Harbor; |
| 164 | +> - you can see fresh metrics and logs. |
0 commit comments