6.0.0 MVU upgrade docs update #946
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,7 +4,7 @@ import { CURRENT_VERSION_STRING } from 'src/components/PreCodeBlock' | |
|
|
||
| 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/). | ||
|
|
||
| > <Callout type="note">Always consult the [release notes](/admin/updates/docker_compose) for the versions your upgrade will pass over and end on.</Callout> | ||
|
|
||
| ### Standard upgrades | ||
|
|
||
|
|
@@ -59,70 +59,84 @@ $ docker-compose up -d --remove-orphans | |
|
|
||
| ### Multi-version upgrades | ||
|
|
||
| > <Callout type="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> | ||
|
|
||
| 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: | ||
|
|
||
| 1. **Check Upgrade Readiness**: | ||
| - Check the [upgrade notes](/admin/updates/docker_compose#docker-compose-upgrade-notes) for the version range you're passing through. | ||
| - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness). | ||
|
|
||
| 2. **Pull and merge upstream changes**: | ||
| - Follow the [standard upgrade procedure](#standard-upgrades) to pull and merge upstream changes from the version you are upgrading to your `release` branch. | ||
|
|
||
| 3. **Disable Connections to the Database**: | ||
| - Stop running containers connected to the databases and the databases: | ||
| ``` | ||
| $ docker-compose down --remove-orphans | ||
| ``` | ||
|
|
||
| 4. **Run Migrator with the `upgrade` command**: | ||
| - *For more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#upgrade).* | ||
| 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. | ||
| **Example:** | ||
| ```yaml | ||
| migrator: | ||
| container_name: migrator | ||
| image: 'index.docker.io/sourcegraph/migrator:6.0.0' | ||
| ``` | ||
| 2. Set the migrator `command:` to `upgrade` you'll need to supply a `--to=` argument to the version you're upgrading to. | ||
| **Example:** | ||
| ```yaml | ||
| command: ['upgrade', '--from=v5.9.0', '--to=v6.0.0'] | ||
| ``` | ||
| > *Note: you may add the `--dry-run` flag to the `command:` to test things out before altering the dbs* | ||
| 3. Run migrator with `docker-compose up migrator` | ||
|
|
||
| - Migrator `depends_on:` will ensure that the databases are ready before attempting to run migrator. Ensuring that database entrypoint scripts are run before migrator attempts to connect to the databases. For users upgrading from a version earliar than `5.10.0` a PostrgreSQL version is required and will be performed automatically here. For more details see [Upgradeing PostgreSQL](/admin/postgresql#upgrading-postgresql). | ||
|
||
|
|
||
| **Example:** | ||
| ```sh | ||
| $ ~/deploy-sourcegraph-docker/docker-compose/ docker-compose up migrator | ||
| ✔ Network docker-compose_sourcegraph Create... 0.1s | ||
| ✔ Container pgsql Created 0.1s | ||
| ✔ Container codeinsights-db Created 0.1s | ||
| ✔ Container codeintel-db Created 0.1s | ||
| ! 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 | ||
| ! 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 | ||
| ! 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 | ||
| ✔ Container migrator Created 0.0s | ||
| ! 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 | ||
| Attaching to migrator | ||
| migrator | ✱ Sourcegraph migrator 6.0.0 | ||
| migrator | ⚠️ Failed to check for migrator update: unexpected status code 404. Continuing... | ||
| migrator | Attempting connection to frontend... | ||
| migrator | ✅ Connection to frontend succeeded | ||
| migrator | Attempting connection to frontend... | ||
| migrator | ✅ Connection to frontend succeeded | ||
| migrator | Attempting connection to codeintel... | ||
| migrator | ✅ Connection to codeintel succeeded | ||
| migrator | Attempting connection to codeinsights... | ||
| migrator | ✅ Connection to codeinsights succeeded | ||
| migrator | 👉 Migrating to v6.0 (step 1 of 1) | ||
| migrator | 👉 Running schema migrations | ||
| migrator | ✅ Schema migrations complete | ||
| migrator exited with code 0 | ||
| ``` | ||
| 5. **Run Migrator with the `up` command** | ||
| - Set your migrator `command:` to `up` | ||
| > *Note: If you aren't upgrading to the latest release remember to set the migrator image back to the version you are upgrading to.* | ||
| **Example:** | ||
| ```yaml | ||
| migrator: | ||
| container_name: migrator | ||
| image: 'index.docker.io/sourcegraph/migrator:6.0.0@sha256:ec295eb0b743da6bf56777ca6524972267a5c442b0288095e2fe12fce38ebacc' | ||
| cpus: 0.5 | ||
| mem_limit: '500m' | ||
| command: ['up'] | ||
| ``` | ||
|
|
||
| 6. **Start your containers again**: | ||
| - run `docker-compose up -d` in the folder containing your `docker-compose.yaml` file. | ||
| ```sh | ||
| $ docker-compose up -d | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | |
|
|
||
| ### Multi-version upgrades | ||
|
|
||
| <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> | ||
|
|
||
| ### Multi-version upgrade procedure | ||
|
|
@@ -942,6 +938,8 @@ If you are upgrading to **Sourcegraph 5.1 or later**, we encourage you to perfor | |
| - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness). | ||
|
|
||
| **Step 2:** | ||
| > <Callout type="warning">The Kuberentes 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` 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> | ||
MaedahBatool marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| Scale down `deployments` and `statefulSets` that access the database, _this step prevents services from accessing the database while schema migrations are in process._ | ||
| The following services must have their replicas scaled to 0: | ||
| - Deployments (e.g., `kubectl scale deployment <name> --replicas=0`) | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | |
|
|
||
| ## Multi-version upgrades | ||
|
|
||
| > **⚠️ 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. | ||
|
|
||
| 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: | ||
|
|
||
| 1. **Check Upgrade Readiness**: | ||
| - Check the [upgrade notes](/admin/updates/kubernetes#kubernetes-upgrade-notes) for the version range you're passing through. | ||
| - Check the `Site Admin > Updates` page to determine [upgrade readiness](/admin/updates/#upgrade-readiness). | ||
|
|
||
| 2. **Pull and merge upstream changes**: | ||
| - 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. | ||
|
|
||
| 3. **Update cluster.yaml and scale down non-database deployments and replicas**: | ||
| - 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. | ||
| ```yaml | ||
| # - ../../components/utils/uid # -- Run all Postgres database with valid users on host | ||
| - ../../components/utils/multi-version-upgrade # -- Scale down non-database pods to 0 for multi-version upgrade | ||
| # - ../../components/utils/migrate-to-nonprivileged # -- Component for migrating from privileged to non-privileged | ||
| # | ||
| ``` | ||
| - Generate and apply a new cluster.yaml file. | ||
| ```sh | ||
| kubectl kustomize instances/my-sourcegraph -o cluster.yaml | ||
| kubectl apply --prune -l deploy=sourcegraph -f cluster.yaml | ||
| ``` | ||
| > 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). | ||
|
|
||
| 4. **Run Migrator with the `upgrade` command**: | ||
| - *For more detailed instructions and available command flags see our [migrator docs](/admin/updates/migrator/migrator-operations#upgrade).* | ||
| 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): | ||
| - set the `image:` to the **latest** release of `migrator` | ||
| - set the `args:` value to `upgrade`. **Example:** | ||
| ```yaml | ||
| - name: migrator | ||
| image: "index.docker.io/sourcegraph/migrator:6.0.0" // here we use a later version of migrator than the version we're upgrading too. | ||
| args: ["upgrade", "--from=v5.9.0", "--to=5.11.0"] | ||
| env: | ||
| ``` | ||
| > *Note:* | ||
|
|
@@ -168,11 +163,11 @@ To perform a **manual** multi-version upgrade on a Sourcegraph instance running | |
| 2. Run the following commands to schedule the migrator job with the upgrade command and monitor its progress: | ||
| ```sh | ||
| # To ensure no previous job invocations will conflict with our current invocation | ||
| kubectl delete job migrator | ||
| # Start the migrator job | ||
| kubectl apply -f components/utils/migrator/resources/migrator.Job.yaml | ||
| # Stream the migrator's stdout logs for progress | ||
| kubectl logs job/migrator -f | ||
| ``` | ||
| **Example:** | ||
| ```sh | ||
|
|
@@ -209,14 +204,19 @@ To perform a **manual** multi-version upgrade on a Sourcegraph instance running | |
| migrator 1/1 9s 35s | ||
| ``` | ||
|
|
||
| 5. **Generate and apply a new cluster.yaml file**: | ||
| 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`). | ||
| ```yaml | ||
| # - ../../components/utils/uid # -- Run all Postgres database with valid users on host | ||
| # - ../../components/utils/multi-version-upgrade # -- Scale down non-database pods to 0 for multi-version upgrade | ||
| # - ../../components/utils/migrate-to-nonprivileged # -- Component for migrating from privileged to non-privileged | ||
| ``` | ||
| 2. Generate and apply a new cluster.yaml with the new images from Step 2. | ||
| ```sh | ||
| kubectl kustomize instances/my-sourcegraph -o cluster.yaml | ||
| kubectl apply --prune -l deploy=sourcegraph -f cluster.yaml | ||
| ``` | ||
| Your instance should now be up and running in the new version! | ||
|
|
||
| --- | ||
|
|
||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we may want to use
CURRENT_VERSION_STRINGstuff here?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd be into doing this as a revision later yea, at the moment I think we just need to ship this, and a lot of SG uses this stuff