Upgrading¶
The release notes list the breaking changes of each release
and how to upgrade. This page describes how existing setups and data are
affected by the changes since the tag v0.3.0 (2023) and the images
published from dev before the move to FOCA 0.17 (tagged latest and by
date, with FOCA 0.12); for images from dev since then, see Images from
dev since FOCA 0.17.
Upgrading from 0.5.0? See From 0.5.0; from 0.4.0, see
From 0.4.0 too.
From 0.5.0¶
The API implements TRS 2.0.2, and TRS-Filer runs on FOCA 0.23 (see FOCA's migration guide); existing data needs no changes. Check clients and custom configs:
-
Optional object storage: file contents can be stored in S3-compatible object storage (
custom.storage.backend: s3, see File storage). Nothing changes by default (mongodb); existing files stay in MongoDB, as there is no migration of stored files. With object storage, back up the bucket with the database (see Backups). The app creates a new index ontoolson startup (see Backups), as for the other indexes. With several replicas, enablebackend: s3only once all of them run this version: earlier versions don't read files in object storage. -
GET /toolsfilters bytags(comma-separated; tools must have all of them) instead of refusing the filter with400 Bad Request. Tools get their tags on registration (tagsofToolRegister, strings without commas) and return them; stored tools have none (see Listing tools). - The descriptor type
SMK(Snakemake) is supported: versions and files of typeSMKare registered, and theSMKandPLAIN_SMKpaths of the descriptor, test and file endpoints behave as those of the other types, instead of giving400 Bad Request(see Descriptor types). - Descriptors are served as plain text (
text/plain) for thePLAIN_types ({type}/descriptorand{type}/descriptor/{relative_path}, e.g.,PLAIN_CWL), instead of404 Not Found, and so are tests ({type}/tests: the array of file wrappers, astext/plain) (see Descriptor types). Thetext/plainresponses of the descriptor endpoints have no schema in the served specification. - Media types (breaking for some clients):
{type}/descriptor,{type}/descriptor/{relative_path}and{type}/testscheckAccept, which they ignored before: clients that don't accept the media type of the type (application/jsonfor descriptor types,text/plainfor theirPLAIN_forms) get406 Not Acceptableinstead of a response they didn't ask for (e.g.,Accept: text/plainwithCWL; usePLAIN_CWLinstead). Clients that send noAccept,*/*, or the media type of the type are not affected. Their responses carryVary: Accept(see Media types). {type}/descriptor/{relative_path}finds files in subdirectories by encoded paths (tools%2Fecho.cwl, as in the specification) and by plain ones (tools/echo.cwl), instead of404 Not Found; paths encoded twice (tools%252Fecho.cwl), which clients had to send before, still work (see Relative paths). The parameterrelative_pathhas formatpathin the served specification.- Versions take a
description(ToolVersionRegister), which they return; registrations with it failed with400 Bad Requestbefore. - The served specification (
openapi.json, Swagger UI) has the app'sinfo(titleTRS-Filer, license and contact), instead of the TRS specification's. - TRS 2.0.2 (breaking): the served specification is that of the TRS
release 2.0.2 instead of a commit of TRS
developbefore it (see Supported TRS version), and the service info reports TRS version2.0.2(type.version) instead of2.0.1. Custom configs that setservice_info.service.type.versionkeep their value; set it to2.0.2. The response ofGET /tools/{id}/versions/{version_id}/{type}/files?format=zipis declared as a binary file (application/zip), as it is served; clients generated from the specification may change. - The read operations of TRS and the service info are declared public
(
security: []), and TRS's security schemeBEARERas an HTTP bearer scheme (it was left out); nothing changes for clients, as no endpoint required a token before. Config overlays withpatchesofapi.specs.trsmust patch the operations of the new specification, andnullin patches now removes the key instead of setting it tonull(FOCA 0.23). Config overlays that setapi.specs.trs.pathmust listapi/20250902.4854e2f.openapi.yamlinstead ofapi/20230406.1dd4bf8.openapi.yaml, in the order of the base config. - Versions take the versions of their languages (
descriptor_type_versionofToolVersionRegister, by descriptor type), which they return; registrations with it failed with400 Bad Requestbefore. - GA4GH I/O Schemas of workflows (experimental) are documented: files of
type
OTHERnamedga4gh-io.schema.json, stored and served as before. The new optioncustom.io_schema.validation(falseby default, so nothing changes) checks them on registration, each in a process of its own (about 50 to 100 MB of memory, one at a time), withincustom.io_schema.timeoutseconds (see Checking I/O Schemas). - Tokens for writes (breaking): registering, changing and deleting tools,
versions and tool classes (
POST,PUTandDELETE, see Registering tools) need an access token (RFC 9068,at+jwt) of a trusted OpenID Connect provider; without a valid token, they answer401 Unauthorized. Any authenticated user can register tools and add tool classes; changing tools needs a role on them or the roleadmin(a group mapped to it), replacing and deleting tool classes the roleadmin; other users get403 Forbidden(see the next item). Reads stay public. The app refuses to start until the deployment sets its identity provider and admin group (see Access control). To upgrade:- Register TRS-Filer's clients (e.g., a portal, a gateway or the
scripts that register tools) with your identity provider, so that
they get access tokens of type
at+jwtfor an audience of TRS-Filer, with the group claim (or the scope that releases it via user info). - Add to your config overlay (with the Helm chart: the value
config, without which rendering fails)security.auth.issuers,security.auth.audience,security.access_control.claim_groups(andsecurity.auth.userinfo_claimsif the identity provider releases the claim via user info only) andsecurity.access_control.group_mappingwith your admin group (see Deployment configuration). - Let the clients send the token (
Authorization: Bearer <token>) with writes. - Custom config overlays that replace the default one (e.g., a
docker-compose.override.yamlthat setsFOCA_CONFIG_OVERLAY, or aconfig.local.yaml) must set these keys too, or the app refuses to start. If you deployed a copy of the Helm chart with a config overlay of its own (as the 0.5.0 deployment README described), move that overlay's content intoconfigand drop your template changes: the chart setsFOCA_CONFIG_OVERLAYitself. - Restrictions of writes in front of the app (e.g., methods allowed only from some addresses at the ingress controller) are no longer needed for access control; keep them if you want both, and at least until the upgrade is complete: during a rolling update, pods of the old version still accept writes without a token.
- Register TRS-Filer's clients (e.g., a portal, a gateway or the
scripts that register tools) with your identity provider, so that
they get access tokens of type
FOCA's service clients are not supported (the app refuses to start with
them). The rules of access control are stored in the collection
policy_rules of the app's database; FOCA's permissions API is served at
/admin/access-control/ (see Permissions
API). Docker Compose trusts a fictitious
identity provider (config.dev.yaml, which requires no admins and
verifies no audiences), so writes are refused until you set yours in a
local override (Compose passes TRS_FILER_CONFIG_OVERLAY, if set, to the
app as FOCA_CONFIG_OVERLAY, which lists the overlays); for
local development without an identity provider, see Running without
authentication.
- Owners of tools (breaking): the user registering a tool becomes its
owner, as for services in Cloud Registry (see Roles on
tools). Owners replace and delete their
tools and versions, and grant the roles owner and maintainer (add and
replace versions) to other users and to their groups via the new
endpoints /tools/{id}/permissions; admins can do everything. PUT
/tools/{id} replaces only tools that the user may change (403
Forbidden otherwise; it adds tools with the identifier of no tool, as
before), and PUT /toolClasses/{id} replaces tool classes only for admins.
Any authenticated user can add tool classes (POST /toolClasses, PUT
/toolClasses/{id} with new identifiers, and by registering tools with new
ones), as custom.access_control.tool_classes: open (the default) says. To
upgrade:
1. Tools stored before have no owners: only admins can change them.
Grant each the owner that should manage it (PUT
/tools/{id}/permissions/users/{userId} with {"role": "owner"}, as
an admin); the user identifier is the sub claim of the user's
tokens.
2. Config overlays that replace the read rules get-tools (e.g., for
readers, with /ga4gh/trs/v2/tools/*) by name: the base config now
has get-tools for /tools/:id only, plus list-versions and
get-versions. Rules for all paths under /tools/ would also let
their subjects list (GET) or, for writes, change (PUT, DELETE)
the roles on tools: replace them as in Requiring login for
reads and the editors
example of Admins.
3. Config overlays that give security.access_control.policies as a
list replace the new rules of the base config (register-tools,
owners-*, maintainers-*, add-tool-classes), so users can't
register or change tools: switch to named rules, or add these rules
to the list. Don't override security.access_control.resource_roles
or unset keep_group_subjects (the values of the group claim are now
also subjects, for roles of groups).
4. Nothing to do for the new internal fields of tools (_createdBy,
_createdAt and _updatedAt, not served): tools stored before get
_updatedAt on their next change, but neither who registered them
nor when. Instances of the old version that still run next to the
new one (e.g., in a rolling update of a setup of your own) serve
these fields of tools that the new version writes, i.e., who
registered them: stop them before the new version takes writes. With
the Helm chart, the new release replaces the old one anyway (see
below).
- Modes of adding tool classes: custom.access_control.tool_classes
supports controlled (only admins add tool classes) and moderated
(tool classes of other users, and their tools, are pending until an admin
approves them, PUT /toolClasses/{id}/approval; GET /approvals lists
them), which the app refused on startup before (see Adding tool
classes). GET /approvals pages
its results as GET /tools does (offset, limit and the page links,
see Approving tool classes). The TRS
reads accept a token (optional), for the pending tools and tool classes
that its user may see; invalid tokens are still read as anonymous. Tool classes store
who added them, and pending ones and their tools a flag (internal fields
_createdBy and _pending, not served; tool classes stored before have
no _createdBy). To upgrade:
1. Deprecated custom.toolclass.validation (breaking for some
setups): true now sets the mode controlled, with a warning on
startup; set custom.access_control.tool_classes: controlled
instead and remove validation, which is removed in the next
breaking release. Behaviour changes with it: users other than
admins can't add tool classes explicitly anymore (POST
/toolClasses, PUT /toolClasses/{id} with new identifiers: 403
Forbidden instead of adding them), and admins add tool classes by
registering tools with new ones (instead of 400 Bad Request).
Combined with moderated, the app refuses to start.
2. Config overlays that give security.access_control.policies as a
list: add the new rule list-approvals ([p, "*",
/ga4gh/trs/v2/approvals, "GET|HEAD"]), or users other than admins
get 403 Forbidden from GET /approvals.
3. Instances of the old version that still run next to the new one
serve the internal fields of the tool classes that the new one adds
(who added them), and pending tools to everybody: stop them before
the new version takes writes.
-
Limit of unused tool classes per user (behaviour change): users other than admins may only have added 10 tool classes that no tool has (
custom.access_control.max_unused_tool_classes, by default); further ones get409 Conflict, also when they register a tool with a new tool class (see Adding tool classes). Tool classes stored before count for nobody. Setnullto keep adding tool classes without limit. The app creates two new indexes on startup (tools bytoolclass.id, tool classes by_createdBy), as for the other indexes. -
Helm chart (breaking): the chart is a thin chart over FOCA's library chart
foca-common, with camelCase values, and releases of earlier charts can't be upgraded: uninstall them and install the new chart, moving the data, as described in From earlier charts (helm upgradefails for them). Rendering fails for the earlier values, which are renamed or removed:host_nameishostName,trs_fileristrsFiler, andtrs_filer.configis the top-levelconfig.trs_filer.imageis split intotrsFiler.image(by defaultdocker.io/elixircloud/trs-filer) andtrsFiler.tag(by default the chart'sappVersion:devin the repository, the release version in released charts).trs_filer.appNameis removed: resources are named after the release (<app>, e.g.,trs-filer, and<app>-mongodbfor MongoDB, wasmongodb-<appName>;fullnameOverridesets<app>), with the standard labels instead ofapp: <appName>(see Names and labels).- The config Job, its ServiceAccount, Role and RoleBinding
(
<appName>-configurer) andapiServerare removed: the chart renders the config overlay (ConfigMap<app>-config) itself, and no pod gets a service account token. The image has nocurl,jq,yqorupdate-config-map.shany more. trs_filer.forwardedAllowIps(by default*) is removed: Gunicorn trustsX-Forwarded-*headers from the local host only, so theself_linkandnext_pageheaders of listings gethttpbehind a proxy that terminates TLS, untilFORWARDED_ALLOW_IPSis set to the proxy's addresses intrsFiler.extraEnv(see Forwarded headers). Theurlof tools comes fromhostNameand keepshttps.mongodb.dbName(by defaulttrs-filer-db) is removed: the app's database istrsStore, that of the base config, also for the rules of access control; the restore moves the data there.mongodb.volumeSizeismongodb.persistence.size.
New values: trsFiler.gunicorn (Gunicorn's settings), trsFiler.replicas
with a PodDisruptionBudget, trsFiler.extraEnv, extraEnvFrom and
rolloutOnSecrets, probes (trsFiler.probePath and the probe specs),
trsFiler.preStopSleepSeconds, a Gateway API HTTPRoute
(trsFiler.httpRoute), mongodb.persistence and an external MongoDB
(mongodb.enabled: false); values.schema.json checks the values (see
Deployment). The chart in the repository needs helm
dependency build deployment before installing; released charts contain
the library chart.
From 0.4.0¶
TRS-Filer now runs on FOCA 0.22 (from 0.19; see FOCA's migration guides for 0.20, 0.21 and 0.22). Check clients, custom configs and log checks:
- Requests that fail the validation of the API specification keep the
validator's reason as
detail(exceptions.validation_reasons). Where the invalid fields are known, their responses gain the memberstype(FOCA's problem type, a URL ending in/problems/invalid-request/),code(invalid-request) anderrors, which lists them. - Logs: requests (
Incoming request) name the route of the request instead of its path, and rejected requests (Request rejected) name the locations and codes of their invalid fields (otherwise the mappeddetail) instead of the validator's reason. Paths and reasons are logged only atDEBUG, so rejected values no longer show up atINFO. FOCA warns once per worker of what it deprecates ahead of its release on ASGI. - Requests that TRS-Filer itself refuses (e.g.,
limit=0, deleting the last version of a tool, or a tool class that tools use) get their reason asdetailinstead of the genericThe request is malformed.(see Errors); clients that compareddetailwith the generic text must checkstatusinstead. - Query parameters that an operation doesn't declare now give
400 Bad Requeston all operations, also onGET /service-info,GET /toolClasses,POST /toolsandPOST /toolClasses, which ignored them (see Errors). - JSON bodies with unpaired surrogates (e.g.,
"\ud800") get400 Bad Requestbefore TRS-Filer sees them, with adetailthat names neither the field nor the value. - Custom configs: string values with
${...}now reference environment variables (an unset variable stops the app), and$$stands for a literal$; write$$for each$that's meant literally there. Alogsection whose handlers orrootname a handler or filter that it doesn't configure stops the app (e.g.,handlersreplaced by one of your own, withoutroot.handlers). Errors of the custom configuration (custom) name the setting and the reason, without the invalid value. - MongoDB clients time out after 5 seconds (server selection and connect,
down from 30 and 20), so with MongoDB down, startup and requests fail
sooner; set them in
db.client_optionsorMONGO_URIif MongoDB takes longer in your deployment. - Responses have the header
X-Request-ID, generated by the app, which log records carry too; a request ID set by a proxy in front of the app isn't used (see FOCA'sserver.request_id.trust_incoming). - The image has no pip (and no uv): images derived from the TRS-Filer image
that run
pip installmust install with uv instead, mounted from a pinned stage (see FOCA's migration guide for 0.20). The image installs the locked versions of its dependencies (uv.lock), with hash checks. - Helm chart, security contexts: all pods run as non-root users with a
read-only root file system (Security
context). MongoDB runs as user and
group 999 from the start (before, its entrypoint started as root and
switched to that user); the data that it wrote belongs to that user
already, and
fsGroupkeeps the volume writable for it (with storage that appliesfsGroup). - Helm chart, NetworkPolicy: only the app may connect to MongoDB (Network
policies). Other workloads that connect
to MongoDB (e.g., backups) need a policy of their own, or set
mongodb.networkPolicy.enabled: false. - Helm chart, MongoDB authentication (breaking): MongoDB requires
credentials from an existing Secret (
mongodb.auth.existingSecret), and rendering fails without it. Existing databases have no users, and MongoDB creates none on an existing volume: create the Secret and the users before the upgrade, as described in Authentication, or setmongodb.auth.enabled: falseto keep MongoDB without authentication. - Helm chart, upgrades with
--reuse-valueskeep the earlier settings (no security contexts, no NetworkPolicy, no authentication unless they name the Secret withmongodb.auth.existingSecret): pass your values file instead, or use--reset-then-reuse-values(see Upgrades). - Helm chart: the configuration Job's ServiceAccount is bound to a Role
with only the rights that the Job uses (Role and RoleBinding
<appName>-configurer), instead of the ClusterRoleadmin(RoleBindingadmin-<appName>-configurer, which the upgrade removes). The Job finds the app's base config through the installed package, instead of a path that depended on the image's Python version, and works with older images too. With images of this release or later, it fails if the API server refuses reading or patching the ConfigMap or listing pods (before, it reported success): copies of the chart that add their own steps to the Job may need more rights in the Role. The Job restarts the pods with the labelapp: <appName>(the app's), no longer all pods whose names start with<appName>-. - Helm chart:
trs_filer.imagePullPolicysets the pull policy of the app's image (app and configuration Job); the default,Always, is the earlier behaviour, also for upgrades with--reuse-values. - Helm chart:
trs_filer.forwardedAllowIpssets the addresses that forwarded headers are trusted from; the default,*, is the earlier behaviour (see Forwarded headers). - Config:
custom.access_control.tool_classessets who may add tool classes; its default,open, is the earlier behaviour (see Adding tool classes).
Configuration¶
TRS-Filer runs on FOCA 0.23 and Python 3.13. Custom configs must apply the
config changes of FOCA 0.14 to 0.23 (see the FOCA release
notes and migration
guides), e.g., exceptions.mapping instead of the old exception members,
no server.environment or server.use_reloader, and no top-level
plugins section other than FOCA's (validated since FOCA 0.18, with
unknown keys refused; TRS-Filer loads no plugins);
server.max_content_length must be set (see Request size
limit). Configs are best written as
overlays of the base config (see Configuration), which
the image no longer has at /app/trs_filer/config.yaml (the package is
installed, not copied).
- The identifier character sets (
custom.tool.id.charset,custom.version.id.charset,custom.toolclass.id.charset) list the characters themselves (e.g.,ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789); expressions such asstring.ascii_uppercase + string.digitsare rejected on startup. - Identifiers of tool classes registered with the tool class endpoints
follow
custom.toolclass.id(they usedcustom.tool.id): by default lower-case letters and digits. custom.service(the public URL) defaults tohttp://localhost:8080; deployments set their own.- File contents are retrieved from URLs as configured in
custom.remote_files(see Remote files):httpURLs are only retrieved ifhttpis added toschemes, hosts that resolve to addresses that are not public only if listed inallowed_hosts, and responses other than2xxor larger thanmax_sizefail the registration with400 Bad Request(before, error pages were stored as content).
Service info¶
POST /service-info and the service_info collection are removed: the
service info is configured in service_info.service (FOCA's section, see
Service info); custom.service_info is
rejected on startup. The collection stays in existing databases, unused;
drop it if you like.
API¶
GET /tools:limit=0gave all tools; it now gives400 Bad Request, as do other limits below 1. Invalidoffsetandlimitvalues give400instead of422.limitis at most 1000 (larger values are reduced to 1000).next_pageis omitted on the last page, andlast_pageis counted in steps oflimitfrom the requested offset. Filters of versions and images apply to the same version and image (they overwrote each other). The linksnext_pageandlast_pagekeep the filters of the request (they had onlyoffsetandlimit). An emptyauthormatches only empty authors (it matched all tools), and the filtertagsfilters by the tags of tools (it was ignored). See Listing tools.- Registering or replacing a tool no longer changes an existing tool class:
the tool stores a copy of the stored tool class instead of the one it was
sent with. With
custom.toolclass.validation: true, a tool with an unknown tool class is no longer stored (before, it was stored although the request failed with400). See Tool classes. - Replacing a tool, version or tool class with an identical one succeeds
(it failed with
500). - Replacing tools and versions increments their
meta_version(it stayed at the initial value), as configured incustom.tool.meta_version.incrementandcustom.version.meta_version.increment. Adding, replacing or deleting a version also increments themeta_versionof its tool, so clients see that the tool changed; setcustom.tool.meta_version.on_version_change: falseto keep the tool's meta version unchanged on version changes. See Meta versions. - Deleting the last version of a tool gives
400 Bad Request; delete the tool instead. - Versions without
is_productionare registered as non-production versions (they failed with500).
Errors¶
Errors are problem details (title, status, detail), sent as
application/json, instead of objects with message and code (see
Errors). Requests that the validation of the API
specification rejects get the reason as detail (e.g., 'FOO' is not one
of ['CWL', ...]), no longer the generic The request is malformed.; set
exceptions.validation_details: false to keep the generic one (see
Errors). Requests that TRS-Filer itself refuses
(e.g., limit=0, deleting the last version of a tool, or a tool class that
tools use) get their reason as detail, too (see Errors);
before, the reason was only logged.
Database¶
Without MONGO_DBNAME, the image uses the database trsStore (as
configured) instead of trs-filer-db. Deployments with data in
trs-filer-db (e.g., the Docker Compose setup of earlier versions) set
MONGO_DBNAME=trs-filer-db, or move the data (see below). The Helm charts
up to 0.5.0 set it (value mongodb.dbName, by default trs-filer-db); the
current chart uses trsStore (see Helm chart).
MongoDB 4.4 or later is required (Docker Compose and the Helm chart use
7.0). MongoDB 7.0 can't open data files of 3.6, which earlier Compose
setups used: migrate them with mongodump (with MongoDB 3.6) and
mongorestore (with 7.0), e.g., into trsStore, or upgrade one major
version at a time. For the Helm chart, see Helm chart.
Image¶
- Image tags:
latestis the highest stable release from the first release with the new release process on, no longer the head ofdev, which is taggeddev(andsha-<commit>per commit); dated tags are no longer published. Pin a release (X.Y.Z) in deployments (see Versioning and releases). Images published by the new workflows are scanned, attested and signed (see Verifying images and charts). - Gunicorn is configured by
trs_filer/gunicorn_config.pyand the environment variableGUNICORN_CMD_ARGS(e.g.,--workers 2; see Server);GUNICORN_PROCESSES,GUNICORN_THREADSandTRS_CONFIGare no longer read, and Gunicorn always binds0.0.0.0:8080. - Forwarded headers (
X-Forwarded-*) are trusted from Gunicorn's default (127.0.0.1) only, no longer from every client: behind a proxy that terminates TLS, setFORWARDED_ALLOW_IPSto its addresses (with the Helm chart, intrsFiler.extraEnv, see Forwarded headers; the charts up to 0.5.0 set it, by default to*). - The image runs as user 1000 (also with a read-only root file system and a
writable
/tmp) and reports its version (e.g., in the service info) from the build argumentSETUPTOOLS_SCM_PRETEND_VERSION.
Docker Compose¶
The service is named trs-filer (was trs), and the app is published at
http://localhost:8080/ga4gh/trs/v2/ on the loopback interface only (was
port 80 on all interfaces). MongoDB data lives in the named volume
mongodb-data instead of ../data/trs/db: migrate it with mongodump and
mongorestore if needed (see Database). The Compose setup
applies the overlay config.dev.yaml (see Local
overrides).
Helm chart¶
Releases attach the chart (see Verifying images and
charts). Releases of earlier
charts (that of the tag v0.3.0, of 0.4.0 and 0.5.0, and those on dev
before the library chart) can't be upgraded to the current chart: uninstall
them and install it, moving the data by dump and restore, as described in
From earlier charts. Check two things
before you start, as charts before 0.4.0 differ from the commands
there:
- The names of MongoDB's Deployment and claim (
kubectl get deploy,pvc -n <namespace>): the charts up to 0.5.0 called themmongodb-<appName>(trs_filer.appName, by defaulttrs-filer); charts before July 2024, including that ofv0.3.0, called themmongodb. Use that name (OLDbelow) in the dump. Charts before 0.4.0 ran MongoDB without authentication: leave out-u,-pand--authenticationDatabasein the dump, and create the Secret with MongoDB's credentials before installing the current chart (see Installation). -
The running MongoDB version: the chart runs MongoDB 7.0 (
mongodb.image, see Version). Charts before January 2026 ranmongo:3.6; the chart ondevsince then ran the floatingmongo:noble(MongoDB 8.2, 8.3 or 9.0, depending on when the pod last started). The dump and restore move the data to the new version; check the version (and the feature compatibility version) of the running server (withmongosh, ormongo, the old shell, in images before 6.0):kubectl exec deploy/OLD -n <namespace> -- sh -c \ '"$(command -v mongosh || echo mongo)" --quiet --eval "printjson({version: db.version(), fcv: db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1}).featureCompatibilityVersion})"'If MongoDB doesn't start any more (
CrashLoopBackOff, e.g., after a restart pulled a newermongo:noblethat can't open the data), its log names the versions (kubectl logs deploy/OLD -n <namespace> --previous): set an image that can open the data (e.g.,kubectl set image deploy/OLD OLD=docker.io/library/mongo:8.3 -n <namespace>; the container is named after the Deployment), wait until it runs, then dump. If themongorestoreof an old image refuses--dryRun, leave out the check of the dump, and compare the counts below after the restore instead. If the restore into 7.0 fails on the options of an index, restore with--noIndexRestore: the app creates its indexes on startup; or setmongodb.imageto the dumped major and minor version (mind the kernel requirements of 8.x, see Version).
Also count the documents of each collection before the dump, for a
comparison after the restore (in trs-filer-db, and in trsStore after
it):
kubectl exec deploy/OLD -n <namespace> -- sh -c \
'"$(command -v mongosh || echo mongo)" --quiet trs-filer-db --eval "db.getCollectionNames().forEach(c => print(c, db[c].countDocuments ? db[c].countDocuments({}) : db[c].count()))"'
The claim mongodb of charts before July 2024 isn't annotated to be kept:
before uninstalling, keep its volume as a fallback by setting the reclaim
policy of its PersistentVolume to Retain
(kubectl patch pv "$(kubectl get pvc mongodb -n <namespace> -o
jsonpath='{.spec.volumeName}')" -p '{"spec": {"persistentVolumeReclaimPolicy":
"Retain"}}'), and delete the volume once the new release works (kubectl
delete pv <name> deletes only the PersistentVolume object: delete its
storage, e.g., the disk, with your storage provider). The chart of the tag
v0.3.0 deploys the app with the API extensions/v1beta1, which
Kubernetes no longer serves since 1.16; if helm uninstall fails because
the release's manifest contains removed APIs, map them first with the
mapkubeapis plugin (helm
mapkubeapis trs-filer -n <namespace>). The service_info collection of
the dump is no longer used (see Service info).
Values¶
Rendering fails for the values of the charts up to 0.5.0 (see From
earlier charts for the renamed ones).
Values of the chart of v0.3.0 have no successor: clusterType is removed,
as the chart creates an Ingress (trsFiler.ingress.enabled, by default
true; HTTPS via cert-manager with trsFiler.ingress.https), a Gateway
API HTTPRoute (trsFiler.httpRoute) or, with neither, an OpenShift Route
(with TLS at the router), as v0.3.0 did with clusterType: openshift (see
Exposing the app). hostName has no
default (host_name was a test host). The default image is
elixircloud/trs-filer (was lvarin/trs-filer:0.1.0), and MongoDB's is
docker.io/library/mongo:7.0 (was mongo:3.6, and mongo:noble on dev).
The chart in the repository has the placeholder version 0.0.0 (was
2.0.0); released charts have the release's version.
Images from dev since FOCA 0.17¶
Images from dev built since the move to FOCA 0.17 (dev, sha-<commit>)
ran on an unreleased FOCA commit; the first release since then runs on
FOCA 0.19. Besides the detail of rejected requests (see Errors), the startup warning
about the placeholders of the service info changes: FOCA logs it
(logger foca.api.service_info) while id, organization.url,
contactUrl or documentationUrl are in a reserved example domain (RFC
2606, e.g., org.example.trs or https://trs.example.org), instead of the
app (logger trs_filer.app), which warned of the placeholders id and
organization (name or URL) of the base config only; a placeholder
organization.name is no longer warned of. FOCA's plugin store
(collection plugin_store) and plugin listing are for gateway apps:
TRS-Filer creates no collections or indexes beyond its own, so its
database user needs no new rights.