wip: Versioned Upgrade guides & Practices. #576
Draft
Conversation
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
✅ Deploy Preview for seqera-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
gavinelder
commented
May 1, 2025
Comment on lines
+17
to
+19
| - [Upgrade to v24.3](./upgrade/24.3) | ||
| - [Upgrade to v24.2](./upgrade/24.2) | ||
| - [Upgrade to v24.1](./upgrade/24.1) |
There was a problem hiding this comment.
These do not exist yet - will complete once agreement on the format is done.
There was a problem hiding this comment.
This file is not specifically for review - once the main changes in 25.1.mdx have been agreed this can be updated.
Comment on lines
-66
to
-143
| ## Breaking changes and warnings | ||
|
|
||
| ### OIDC Secrets injection modifications | ||
|
|
||
| The `auth-oidc-secrets` Micronaut environment has been replaced with `oidc-token-import`. If you use this configuration, you must change the `MICRONAUT_ENV` environment variable in the manifest during the migration process. If you activate the feature with the `TOWER_OIDC_TOKEN_IMPORT` environment variable, no changes are needed. | ||
|
|
||
| ### Seqera AWS ECR repository customer access ends June 1, 2025 | ||
|
|
||
| Customers will no longer be able to pull Seqera Enterprise container images from the legacy Seqera AWS ECR repository after June 1, 2025. All Seqera Enterprise images must be retrieved via the `cr.seqera.io` container registry after this cutoff date. The installation and configuration templates provided for both [Docker Compose](https://docs.seqera.io/platform-enterprise/25.1/enterprise/docker-compose) and [Kubernetes](https://docs.seqera.io/platform-enterprise/25.1/enterprise/kubernetes) installations already reference the `cr.seqera.io` container image URLs. If you have not yet transitioned to this registry, [contact Support](https://support.seqera.io) to request credentials and for any further assistance. | ||
|
|
||
| See [Legacy Seqera container image registries](https://docs.seqera.io/platform/25.1/platform-enterprise/advanced-topics/seqera-container-images) for more information on the AWS ECR and other deprecated Seqera container registries. | ||
|
|
||
| ### Redis version change | ||
|
|
||
| From Seqera Enterprise version 24.2: | ||
|
|
||
| - Redis version 6.2 or greater is required. | ||
| - Redis version 7 is officially supported. | ||
|
|
||
| ### Redisson properties deprecated | ||
|
|
||
| From Seqera Enterprise version 24.2, `redisson.*` configuration properties are deprecated. If you have set `redisson.*` properties directly previously, do the following: | ||
|
|
||
| - Replace `/redisson/*` references in AWS Parameter Store entries with `TOWER_REDIS_*`. | ||
| - Replace `redisson.*` references in `tower.yml` with `TOWER_REDIS_*`. | ||
|
|
||
| :::note | ||
| Set `TOWER_REDIS_*` values directly in the `tower.yml` or AWS Parameter Store entry (for example, `TOWER_REDIS_URL: redis://...`). | ||
| ::: | ||
|
|
||
| ### MariaDB driver: New MySQL connection parameter required | ||
|
|
||
| MariaDB driver 3.x requires a special parameter in the connection URL to connect to a MySQL database: | ||
|
|
||
| `jdbc:mysql://<domain>:<port>/tower?permitMysqlScheme=true` | ||
|
|
||
| All deployments using a MySQL database (regardless of version: 5.6, 5.7, or 8) must be updated when upgrading to Seqera Enterprise version 24.1 or later. | ||
|
|
||
| ### MariaDB driver: No truncation support for MySQL 5.6 | ||
|
|
||
| The MariaDB driver has dropped support for the `jdbcCompliantTruncation` parameter, which was true by default and set the `STRICT_TRANS_TABLES` SQL mode. The `STRICT_TRANS_TABLES` mode produces an error when the value of a VARCHAR column exceeds its limit, instead of truncating it to fit. Most common installations of MySQL 5.7 and 8 already include this mode at the server level, but the Docker container version of MySQL 5.6 does not. | ||
|
|
||
| The SQL mode must be set explicitly through the connection URL for deployments still using MySQL 5.6: | ||
|
|
||
| `jdbc:mysql://<domain>:<port>/tower?permitMysqlScheme=true&sessionVariables=sql_mode='STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION'` | ||
|
|
||
| ### Micronaut property key changes | ||
|
|
||
| The property that determines the expiration time of the JWT access token (used for authenticating web sessions and Nextflow-Platform interactions) has changed as of Seqera Enterprise version 24.1: | ||
|
|
||
| | Previous | New | | ||
| | ---------------------------------------------------------------- | ------------------------------------------------------------ | | ||
| | `micronaut.security.token.jwt.generator.access-token.expiration` | `micronaut.security.token.generator.access-token.expiration` | | ||
|
|
||
| Enterprise deployments that have customized this value previously will need to adopt the new format. | ||
|
|
||
| ## Upgrade steps | ||
|
|
||
| :::warning | ||
| Upgrading to version 25.1 requires backend downtime in order for the database migration to complete successfully. | ||
| ::: | ||
|
|
||
| 1. This version includes an update to the Platform Enterprise H8 cache. **Do not start the upgrade while any pipelines are in a `running` state as active run data may be lost.** | ||
| 1. This version requires a database schema update. Make a backup of your Platform database prior to upgrade. | ||
| 1. If you are upgrading from a version older than 23.4.1, update your installation to version [23.4.4](https://docs.seqera.io/changelog/seqera-enterprise/v23.4) first, before updating to 25.1 with the steps below. | ||
| 1. For recommended Platform memory settings, add the following environment variable to your Platform configuration values (`tower.env`, `configmap.yml`, etc.): | ||
| ```bash | ||
| JAVA_OPTS: -Xms1000M -Xmx2000M -XX:MaxDirectMemorySize=800m -Dio.netty.maxDirectMemory=0 -Djdk.nio.maxCachedBufferSize=262144 | ||
| ``` | ||
| 1. See [Upgrade installation](https://docs.seqera.io/platform-enterprise/24.2/enterprise/upgrade) for installation upgrade guidance. | ||
|
|
||
| :::info | ||
| Docker Compose deployments require downtime while upgrading services. Restarting the application may take several minutes. See [Docker compose deployment](https://docs.seqera.io/platform-enterprise/latest/enterprise/docker-compose) for more information. | ||
| :::note[UPGRADING] | ||
|
|
||
| For Kubernetes deployments, apply the 25.1 `tower-cron.yml` to your cron pod and wait for the cron pod to be running before applying the `tower-svc.yml` to your backend pod and restarting the service. If the cron pod update is interrupted, you may need to restore the instance from your DB backup and start again. See [Kubernetes deployment](https://docs.seqera.io/platform-enterprise/latest/enterprise/kubernetes) for more information. | ||
| See [Upgrade installation](https://docs.seqera.io/platform-enterprise/25.1/enterprise/upgrade) for installation upgrade guidance. | ||
|
|
||
| For custom deployments with third-party services such as ArgoCD, [contact support](https://support.seqera.io) for assistance during upgrade. | ||
| ::: |
There was a problem hiding this comment.
Removed breaking changes as these specifically were introduced in older versions of the platform and now live in the breaking-changes file.
We should continue to publish them here as-well when they are relevant.
Comment on lines
+16
to
+22
| :::warning[Version compatibility] | ||
| Seqera is backward-compatible with the previous version. As such, existing pipelines, workspaces, and studios will continue to function. | ||
|
|
||
| However, default values for components (such as Nextflow) may change between versions. This can require updates to specific pipeline definitions or syntax to ensure compatibility. | ||
|
|
||
| Please refer to the [functionality matrix](../functionality_matrix) for detailed information regarding default component versions. | ||
| ::: |
There was a problem hiding this comment.
Honestly this is more aspirational - I am not close enough on customer upgrades to know if this is fully representative.
justinegeffen
added
do not merge
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
No description provided.