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 |
|---|---|---|
|
|
@@ -59,70 +59,84 @@ $ docker-compose up -d --remove-orphans | |
|
|
||
| ### Multi-version upgrades | ||
|
|
||
| > **⚠️ Attention:** 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. | ||
|
|
||
| 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 to your `release` branch. | ||
DaedalusG marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| 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' | ||
|
There was a problem hiding this comment. we may want to use There was a problem hiding this comment. 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 |
||
| ``` | ||
| 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
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.
Uh oh!
There was an error while loading. Please reload this page.