You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This PR updates the upgrade docs embellishing instructions for the
different deployment methods to include better coverage and handling of
the Postgres 16 database upgrade when crossing over Sourcegraph 5.10.0
using migrator 6.0.0 or greater.
The notable change here is the inclusion of deployment specific builtin
Postgres upgrade instructions, as well as changes to the MVU upgrade
docs suggesting that users bring down all services and merge upstream
changes from their target version into their release branch **before**
performing their migrator upgrade. Due to migrators `depends_on` clause
this will ensure that Postgres upgrades occur **before** migrator
attempts connection to a PG12 database. This gets around the connect
bouncer added in 6.0.0 which blocks services connection to our dbs
## Testing
- [x] docker-compose
- [x] autoupgrade
- [x] MVU (tested 5.9 -> 5.11 with migrator 6.0)
- [x] kustomize
- [x] autoupgrade
- [x] MVU (tested 5.9 -> 5.11 with migrator 6.0)
- [ ] Helm
- [ ] autoupgrade
- [ ] MVU
---------
Co-authored-by: Anish Lakhwara <[email protected]>
Co-authored-by: Maedah Batool <[email protected]>
Co-authored-by: Jacob Pleiness <[email protected]>
Copy file name to clipboardExpand all lines: docs/admin/deploy/docker-compose/upgrade.mdx
+61-47Lines changed: 61 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ import { CURRENT_VERSION_STRING } from 'src/components/PreCodeBlock'
4
4
5
5
This document describes the process to update a Docker Compose Sourcegraph instance. If you are unfamiliar with sourcegraph versioning or releases see our [general concepts documentation](/admin/updates/).
6
6
7
-
> ***⚠️ Attention: Always consult the [release notes](/admin/updates/docker_compose) for the versions your upgrade will pass over and end on.***
7
+
> <Callouttype="note">Always consult the [release notes](/admin/updates/docker_compose) for the versions your upgrade will pass over and end on.</Callout>
8
8
9
9
### Standard upgrades
10
10
@@ -59,70 +59,84 @@ $ docker-compose up -d --remove-orphans
59
59
60
60
### Multi-version upgrades
61
61
62
-
If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perform an [**automatic multi-version upgrade**](/admin/updates/automatic). The following procedure has been automated, but is still applicable should errors occur in an automated upgrade.
62
+
> <Callouttype="warning">Multiversion upgrades **require downtime**, please see our [cautionary note](/admin/updates/#best-practices) on upgrades, if you have any concerns about running a multiversion upgrade, please reach out to us at [[email protected]](mailto:[email protected]) for advisement. </Callout>
63
63
64
-
---
65
-
66
-
> **⚠️ Attention:** please see our [cautionary note](/admin/updates/#best-practices) on upgrades, if you have any concerns about running a multiversion upgrade, please reach out to us at [[email protected]](mailto:[email protected]) for advisement.
67
-
68
-
To perform a **manual** multi-version upgrade on a Sourcegraph instance running on Docker compose follow the procedure below:
64
+
To perform a multi-version upgrade via migrators [upgrade](/admin/updates/migrator/migrator-operations#upgrade) command on a Sourcegraph instance running on Docker compose follow the procedure below:
69
65
70
66
1.**Check Upgrade Readiness**:
71
67
- Check the [upgrade notes](/admin/updates/docker_compose#docker-compose-upgrade-notes) for the version range you're passing through.
72
68
- Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
73
69
74
-
2.**Disable Connections to the Database**:
75
-
- Run the following command in the directory containing your `docker-compose.yaml` file.
76
-
```sh
77
-
$ docker-compose stop && docker-compose up -d pgsql codeintel-db codeinsights-db
78
-
```
79
-
3.**Run Migrator with the `upgrade` command**:
80
-
- The following procedure describes running migrator in brief, for more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#docker-compose).
81
-
1. Set the migrator `image:` in your `docker-compose.yaml` to the **latest** release of `migrator`. **Example:**
70
+
2.**Pull and merge upstream changes**:
71
+
- Follow the [standard upgrade procedure](#standard-upgrades) to pull and merge upstream changes from the version you are upgrading to your `release` branch.
72
+
73
+
3.**Disable Connections to the Database**:
74
+
- Stop running containers connected to the databases and the databases:
75
+
```
76
+
$ docker-compose down --remove-orphans
77
+
```
78
+
79
+
4.**Run Migrator with the `upgrade` command**:
80
+
-*For more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#upgrade).*
81
+
1. If the migrator `image:` in your `docker-compose.yaml` wasn't updated to in the **latest** release of `migrator` in step 2 set migrator's image to the latest release.
> *Note: you may add the `--dry-run` flag to the `command:` to test things out before altering the dbs*
93
-
3. Run migrator with `docker-compose up migrator` **Example:**
94
+
3. Run migrator with `docker-compose up migrator`
95
+
96
+
- Migrator `depends_on:` will ensure the databases are ready before attempting to run the migrator. Ensuring that database entry point scripts are run before the migrator attempts to connect to the databases. For users upgrading from a version earlier than `5.10.0`, a PostgreSQL version is required and will be performed automatically here. For more details, see [Upgradeing PostgreSQL](/admin/postgresql#upgrading-postgresql).
97
+
98
+
**Example:**
94
99
```sh
95
100
$ ~/deploy-sourcegraph-docker/docker-compose/ docker-compose up migrator
! codeinsights-db The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s
106
+
! pgsql The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s
107
+
! codeintel-db The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s
108
+
✔ Container migrator Created 0.0s
109
+
! migrator The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s
100
110
Attaching to migrator
101
-
migrator | ❗️ An error was returned when detecting the terminal size and capabilities:
102
-
migrator |
103
-
migrator | GetWinsize: inappropriate ioctl for device
104
-
migrator |
105
-
migrator | Execution will continue, but please report this, along with your operating
106
-
migrator | system, terminal, and any other details, to:
- Follow the [standard upgrade procedure](#standard-upgrades) to pull and merge upstream changes from the version you are upgrading to to your `release` branch.
123
-
- **⚠️ Attention:** *merging upstream changes should set the migrator `image:` version back to the release you are upgrading to, and the `command:` should be set back to `up`, this is necessary to start your instance again.*
124
-
125
-
5. **Start your containers again**:
139
+
6. **Start your containers again**:
126
140
- run `docker-compose up -d` in the folder containing your `docker-compose.yaml` file.
Copy file name to clipboardExpand all lines: docs/admin/deploy/kubernetes/index.mdx
+2-4Lines changed: 2 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -928,10 +928,6 @@ When all pods have restarted and show as Running, you can browse to your Sourceg
928
928
929
929
### Multi-version upgrades
930
930
931
-
If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perform an [**automatic multi-version upgrade**](/admin/updates/automatic). The following instructions are still applicable, just the manual version of what automatic multi-version upgrade do for you now (and therefore is valuable information during a bumpy upgrade).
932
-
933
-
---
934
-
935
931
<Callout type="warning">Please see our [cautionary note](/admin/updates/#best-practices) on upgrades, if you have any concerns about running a multi-version upgrade, please reach out to us at [[email protected]](mailto:[email protected]) for advisement.</Callout>
936
932
937
933
### Multi-version upgrade procedure
@@ -942,6 +938,8 @@ If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perfor
942
938
- Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
943
939
944
940
**Step 2:**
941
+
> <Callout type="warning">The Kubernetes Helm deployment type does not support MVU from Sourcegraph `v5.9.45` versions and earlier to Sourcegraph `v6.0.0`. Admins seeking to upgrade to Sourcegraph `v6.0.0` should upgrade to `v5.10.3940` or `v5.11.6271` and then use the standard upgrade procedure to get to `v6.0.0`. This is because migrator v6.0.0 will no longer connect to Postgres 12 databases. For more info see our [PostgreSQL upgrade docs](/admin/postgres#requirements).</Callout>
942
+
945
943
Scale down `deployments` and `statefulSets` that access the database, _this step prevents services from accessing the database while schema migrations are in process._
946
944
The following services must have their replicas scaled to 0:
Copy file name to clipboardExpand all lines: docs/admin/deploy/kubernetes/upgrade.mdx
+41-41Lines changed: 41 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -120,46 +120,41 @@ For example, if you use [overlays to make changes to the manifests](https://gith
120
120
121
121
## Multi-version upgrades
122
122
123
-
If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perform an [**automatic multi-version upgrade**](/admin/updates/automatic). The following procedure has been automated, but is still applicable should errors occur in an automated upgrade.
124
-
125
-
---
126
-
127
123
> **⚠️ Attention:** please see our [cautionary note](/admin/updates/#best-practices) on upgrades, if you have any concerns about running a multiversion upgrade, please reach out to us at [[email protected]](mailto:[email protected]) for advisement.
128
124
129
-
To perform a **manual**multi-version upgrade on a Sourcegraph instance running on our **kubernetes** repo follow the procedure below:
125
+
To perform a multi-version upgrade via migrators [upgrade](/admin/updates/migrator/migrator-operations#upgrade) command on a Sourcegraph instance deployed with our [kustomize repo](https://github.com/sourcegraph/deploy-sourcegraph-k8s) follow the procedure below:
130
126
131
127
1.**Check Upgrade Readiness**:
132
128
- Check the [upgrade notes](/admin/updates/kubernetes#kubernetes-upgrade-notes) for the version range you're passing through.
133
129
- Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness).
134
130
135
-
2.**Disable Connections to the Database**:
136
-
- The following services must have their replicas scaled to 0:
- The following procedure describes running migrator in brief, for more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#kubernetes-kustomize).
156
-
1. In the `configure/migrator/migrator.Job.yaml` manifest ([kustomize](https://github.com/sourcegraph/deploy-sourcegraph/blob/master/configure/migrator/migrator.Job.yaml) or [legacy](https://github.com/sourcegraph/deploy-sourcegraph/blob/master/configure/migrator/migrator.Job.yaml)):
131
+
2.**Pull and merge upstream changes**:
132
+
- Follow the [standard legacy upgrade procedure](#upgrade-with-legacy-kubernetes) to pull and merge upstream changes from the version you are upgrading to to your `release` branch.
133
+
134
+
3.**Update cluster.yaml and scale down non-database deployments and replicas**:
135
+
- In your cluster kustomization file (`instances/my-sourcegraph/kustomize.yaml`), uncomment the [multi-version-upgrade util](https://github.com/sourcegraph/deploy-sourcegraph-k8s/blob/main/instances/template/kustomization.template.yaml#L155). This will scale down all non-database deployments and statefulSets replicas to 0.
136
+
```yaml
137
+
# - ../../components/utils/uid # -- Run all Postgres database with valid users on host
138
+
- ../../components/utils/multi-version-upgrade # -- Scale down non-database pods to 0 for multi-version upgrade
139
+
# - ../../components/utils/migrate-to-nonprivileged # -- Component for migrating from privileged to non-privileged
> Note: This step will ensure that any PostgreSQL upgrade performed as an entrypoint script will have a chance to execute before the migrator is run. For more information see [Upgradeing PostgreSQL](/admin/postgres#upgrading-postgresql).
148
+
149
+
4.**Run Migrator with the `upgrade` command**:
150
+
-*For more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#upgrade).*
151
+
1. In the `configure/migrator/migrator.Job.yaml`[manifest](https://github.com/sourcegraph/deploy-sourcegraph-k8s/blob/main/components/utils/migrator/resources/migrator.Job.yaml):
157
152
- set the `image:` to the **latest** release of `migrator`
158
153
- set the `args:` value to `upgrade`. **Example:**
@@ -209,14 +204,19 @@ To perform a **manual** multi-version upgrade on a Sourcegraph instance running
209
204
migrator 1/1 9s 35s
210
205
```
211
206
212
-
4. **Pull and merge upstream changes**:
213
-
- Follow the [standard legacy upgrade procedure](#upgrade-with-legacy-kubernetes) to pull and merge upstream changes from the version you are upgrading to to your `release` branch.
214
-
215
-
5. **Scale your replicas back up and apply new manifests**:
216
-
- The [legacy kubernetes upgrade procedure](#upgrade-with-legacy-kubernetes) describes this step in more detail.
217
-
- Ensure that the replica counts adjusted in the previous steps are turned back up.
218
-
- Run `./kubectl-apply-all.sh` to deploy the new pods to the Kubernetes cluster.
219
-
- Monitor the status of the deployment via `kubectl get pods -o wide --watch`.
207
+
5. **Generate and apply a new cluster.yaml file**:
208
+
1. Comment out the [multi-version-upgrade util](https://github.com/sourcegraph/deploy-sourcegraph-k8s/blob/main/instances/template/kustomization.template.yaml#L155) in your cluster kustomization file (`instances/my-sourcegraph/kustomize.yaml`).
209
+
```yaml
210
+
# - ../../components/utils/uid # -- Run all Postgres database with valid users on host
211
+
# - ../../components/utils/multi-version-upgrade # -- Scale down non-database pods to 0 for multi-version upgrade
212
+
# - ../../components/utils/migrate-to-nonprivileged # -- Component for migrating from privileged to non-privileged
213
+
```
214
+
2. Generate and apply a new cluster.yaml with the new images from Step 2.
0 commit comments