Upgrade Enterprise
Before proceeding, preserve the database and matching SESSION_SECRET, CertOps wrapping keys, SSO keyring, license, and deployment configuration. Use the backup procedure in the Core docs version paired with your Enterprise release. Read the target release notes and its Core compatibility manifest. An Enterprise upgrade includes the paired Core runtime; do not independently upgrade the Core subchart.
Reverting an image or chart does not reverse database migrations. Recovery requires a matching backup or an explicitly supported migration path.
Operator action: This upgrade invalidates older certificate rollout authorizations. Review pending or interrupted distribution, request a new rollout and obtain independent approval when required. History and receipts remain available; reconcile uncertain host effects before retrying work.
Inventory name length (Enterprise 0.17.3)
Upgrading to Enterprise 0.17.3 applies Core migration 67
(inventory_and_auto_sync_name_length). Apply that migration before deploying
API or worker processes that accept 255-character inventory and auto-sync
names. Whitespace-only names become unnamed; other existing names are not
rewritten. Image rollback does not reverse the migration.
Certificate migration histories
Enterprise 0.18.2 already includes basic material distribution and review. Upgrades preserve supported migration versions, names and timestamps; recognized preview histories may retain different version allocations. Do not edit the migration ledger to force an upgrade. Unknown or inconsistent histories stop before applying SQL and need investigation. Upgrade the paired API, workers and dashboard together after taking a database and matching-secret backup. Recovery uses that backup with the matching earlier application; changing images does not reverse migrations. Distribution lifecycle and retention controls remain separate from this release scope.
CertOps fingerprint inventory upgrade
For upgrades that include Enterprise 0.17.2 and its paired Core 0.17.2 runtime or later, drain automation and prevent lifecycle writes during the upgrade. Upgrading from 0.16.1 applies Core migrations 56–66, including notifications, CSR workflows, multi-configuration auto-sync and additive fingerprint identity migrations 62–66. Then deploy the paired API, workers, ingestion and Enterprise overlays together before resuming management. Older writers must not continue against the new management-period schema. Review ambiguous historical retirement evidence; verify grouping, rotation, endpoint removal/re-add and decommission eligibility before restoring normal traffic. Legacy retirement clients must supply an identity precondition. Preserve the database backup and matching secrets for recovery; an image downgrade does not undo these migrations.
Each release ships as: new image tags in Harbor, a new Helm chart version in
Harbor, and a new install bundle in Harbor. Replace NEXT_VERSION below with
the version you are upgrading to. The bundle VERSION file records the
version you extracted; TokenTimer support will confirm the target release
when you renew.
Retrieve the target bundle
The bundle is published as a generic OCI artifact, pulled with ORAS (a single static binary):
oras login harbor.tokentimer.ch -u 'robot$tokentimer-enterprise+<company>-<your-id>'
# Enter the robot token at the password prompt.
read -r -p 'Target Enterprise release: ' NEXT_VERSION
oras pull harbor.tokentimer.ch/tokentimer-enterprise/bundles/tokentimer-enterprise:"${NEXT_VERSION}"
tar -xzf "tokentimer-enterprise-${NEXT_VERSION}.tar.gz"
Docker Compose
cd compose
# Bump TT_ENTERPRISE_TAG in .env if you pin versions, then:
docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml up -d
Helm
read -r -p 'Target Enterprise release: ' NEXT_VERSION
helm upgrade tokentimer oci://harbor.tokentimer.ch/tokentimer-enterprise/charts/tokentimer-enterprise \
--version "$NEXT_VERSION" \
-n tokentimer \
-f my-values.yaml
Re-check tokentimer.config.baseUrl and tokentimer.config.apiUrl in
my-values.yaml after upgrade if you use SSO; chart defaults are
localhost-oriented and are not auto-corrected from ingress hostnames.
Config changes in my-values.yaml (URLs, OIDC/SAML env, SMTP, and so on)
take effect after the upgrade rolls the API and dashboard pods. The chart
annotates Deployments so helm upgrade triggers that rollout automatically.
Editing a running ConfigMap with kubectl alone does not restart pods.
Registry token renewal
Your robot account expires at the same time as your license. When you renew,
you receive a new robot token and must update your Docker login and the
Kubernetes pull secret. Existing pods continue running with their cached
image layers; only the next helm upgrade or docker compose pull
re-authenticates. See
Rotating credentials at renewal.
Verify after upgrade
Confirm successful migrations, API/dashboard health, worker scheduling, the effective license, and administrator access. Check your first alert; if SSO is configured, check sign-in with an existing administrator before inviting users.
License lifecycle
The license JWT drives feature gating at runtime:
| State | Behavior |
|---|---|
| Valid license | Enterprise features enabled, bell icon clean |
Grace period (at most 30 days past expiry; TT_LICENSE_GRACE_DAYS cannot extend past 30) | Features still work, responses carry the X-License-Warning header, bell icon shows yellow |
| Past grace | SSO endpoints redirect to /login?error=license_<provider>_required, auto-sync POST/PUT/run return 403; existing configs can still be read and deleted (cleanup is allowed) |
Admins can also import or remove a license JWT from
System Settings > License at runtime. TT_LICENSE_KEY takes precedence over database imports, which take precedence over the mounted file. Resolution order and the grace period
variable (TT_LICENSE_GRACE_DAYS, default and maximum 30) are documented in the
Configuration reference.
Existing open management periods may rotate to a different fingerprint even when other sources retain the old certificate and quota usage temporarily exceeds the limit. New period enrollment still requires admission; joining an already managed fingerprint adds no unit. Core migration 64 (Cloud migration 82) repairs the earlier admission function without rewriting historical migrations or management history.