Self-hosted Enterprise Edge

Upgrade Enterprise Edge versions

View as Markdown
Edge v17+ Enterprise

This guide walks you through upgrading Enterprise Edge self-hosted from version 17 onward.

Follow each major version upgrade in order: v17 to v18 v18 to v19 v19 to v20

Go to the section that matches your current version to get started.

Migrate from v17 to v18

Service account token creation removed. Start Edge with explicit backend tokens.

Migrate from v18 to v19

Strict and dynamic token-validation modes introduced. Strict mode becomes the default.

Migrate from v19 to v20

Dynamic mode removed. Service account and personal access tokens no longer accepted.

Before you upgrade

Complete this checklist before you upgrade your version:

1

Record your current runtime details

Document the following for your current deployment:

2

Inventory your tokens

For each token, record the following:

  • Startup tokens configured in TOKENS.
  • The environments and projects each token covers.
  • The SDKs and client applications that depend on each token.
3

Review the release notes

Review the release notes for your target version.

4

Confirm rollback readiness

Verify that you have the following in place:

  • Previous image or chart version is available.
  • Persistence snapshot or backup exists.
  • You have a clear owner and maintenance window for rollback if validation fails.

Migrate from v17 to v18

What changed

v18 removed service-account-driven token creation. Edge no longer creates missing frontend tokens at runtime.

Required actions

Complete the following steps before you upgrade:

1

Start Edge with explicit, valid backend tokens in TOKENS.

2

Verify that your startup tokens cover the environments and projects your frontend SDKs require.

Validate the upgrade

After you upgrade, verify that:

  • Edge starts and reaches READY.
  • Frontend API calls succeed for all expected tokens.
  • No unexpected 401 or 403 errors after cutover.

Migrate from v18 to v19

What changed

v19 introduced two edge mode token-validation behaviors:

  • Strict mode validates incoming tokens against Unleash and only accepts tokens whose project and environment scope matches, or is a subset of, the startup tokens in TOKENS. Strict mode became the default in later v19 builds.
  • Dynamic mode (legacy) allowed Edge to accept previously unseen tokens, validate them upstream, and expand its token coverage at runtime. Dynamic mode is deprecated in v20.

v19.10.0 also added pretrusted token support for teams migrating from the Unleash Proxy.

Required actions

Complete the following steps before you upgrade:

1

Keep TOKENS aligned to your actual usage scope.

2

If you still use dynamic mode, migrate to strict mode before you upgrade to v20. To determine your full token scope:

  • If you use a persistent backup (Redis, S3, or local file), check it to see which tokens Edge previously accepted. This gives a definitive view of the scope dynamic mode was allowing.
  • Monitor your frontend and backend SDK requests along with Edge logs to confirm no expected requests are being rejected.
3

Use PRETRUSTED_TOKENS only when you need temporary compatibility with legacy frontend token secrets during a Proxy migration.

4

Verify that all SDK requests are covered by the startup token scope.

Validate the upgrade

After you upgrade, verify that:

  • Requests across all required environments and projects return correct responses.
  • Token coverage is complete for all known clients.
  • Internal state endpoints (/internal-backstage/tokens, /internal-backstage/features) show expected data.

Migrate from v19 to v20

What changed

v20 enforces the deprecations introduced in v19. Run a full end-to-end validation, not just the items listed below.

Required actions

Complete the following steps before you upgrade:

1

Replace any service account or personal access tokens in TOKENS with a backend token that covers the required projects and environments.

2

Remove any DYNAMIC or STRICT behavior toggles from your runtime configuration.

3

Verify that your explicit TOKENS configuration covers all required projects and environments.

4

Validate readiness and feature responses in a staging or UAT environment before you roll out to production.

Validate the upgrade

After you upgrade, verify that:

  • GET /internal-backstage/health returns 200.
  • GET /internal-backstage/ready returns 200.
  • Frontend and backend API responses match expected flag behavior.

Rollout runbook

Follow these steps for each environment, starting with UAT or staging:

1

Deploy the Edge target version with your intended production configuration.

2

Validate health, readiness, and token coverage.

3

Test business-critical application flows.

4

Roll out gradually in production (canary or phased).

5

Re-run validation checks in production.

Rollback criteria

Roll back to the previous version if any of these remain unresolved after remediation:

  • Edge does not consistently reach READY.
  • Critical SDK paths return 401 or 403 unexpectedly.
  • Feature evaluation results are inconsistent for the same token and context.

After rollback, complete a token-scope and persistence analysis before you retry the upgrade.

Troubleshooting

Most upgrade issues stem from removed features that previously masked token-configuration gaps. The following covers the most common failures and how to resolve them.

Frontend SDKs start returning unauthorized responses that previously succeeded.

This happens when Edge was relying on a service account token to create frontend tokens at runtime. After the upgrade, Edge no longer does this.

Fix: Verify that the backend tokens in TOKENS cover all environments and projects that your frontend SDKs require.

After upgrading, some requests succeed while others fail unpredictably across both frontend and backend SDKs.

This typically occurs when Edge runs behind a load balancer with a persistence backup configured. In dynamic mode, Edge accepted previously unseen tokens and expanded its scope at runtime. In strict mode, each Edge instance only serves tokens that fall within the startup token scope. If your backup contains stale state from dynamic mode, different instances behind a load balancer can have different views of which tokens are valid, causing intermittent failures depending on which instance handles the request.

Fix: Verify that the backend tokens in TOKENS cover all environments and projects that your backend SDKs require. If you want to preserve your backup cache, start a single Edge node first with a correct token set and run it for 5 minutes. This forces the backup to a known good state before you scale back up.

Edge does not start and reports that the provided token is not valid.

This happens when TOKENS contains a personal access token or service account token instead of a backend token. v20 rejects these token types at startup.

Fix: Replace the personal access token or service account token with a backend token scoped to the projects and environments your SDKs require.

Edge starts successfully, but downstream SDKs receive unauthorized errors when accessing specific environments.

This is the same root cause as above: TOKENS contains a personal access token or service account token. In some cases Edge starts but the token does not have the correct scope to serve data for the requested environment.

Fix: Replace the personal access token or service account token with a backend token scoped to the projects and environments your SDKs require.