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.

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.

Candidate certificate distribution migrations

The coordinated distribution PR is an unreleased candidate. Its Core source keeps AD CS migrations 68 and 70–72 and console migration 69, preserves mainline job-alert context and retirement safeguards at 73, then adds distribution migrations 74–76. Recognized older preview histories keep every applied version/name/timestamp: distribution-first (70–72), enrollment-first (70–73), and the previous AD-CS-first distribution preview (73–75) append the missing job-alert/lifecycle migration at 76 rather than renumbering ledger rows. Unknown, mixed or gapped histories stop before applying SQL. Use matching candidate API, worker and dashboard images and preserve the database and secrets before testing an upgrade. Image rollback does not undo these migrations; published 0.17.3 tags do not acquire candidate changes from a source pin.

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.