Upgrade

ESS 3.0 Breaking Changes

ESS 3.0 is a major release with breaking changes. Key changes requiring client application updates:

• Authentication: Clients now authenticate directly with an external IdP and exchange the token for an ESS Access Token via the Platform Management token exchange endpoint. The ESS OpenID Broker is no longer required.

• Access Grants: The UMA service has been removed. Access Grants are now receipts — once approved, recipients access resources directly with their ESS Access Token.

• Canonical URIs: Access Grant issuing and notification subscriptions must use canonical resource URIs (the /sc/ form).

• Provisioning: All user provisioning is now through the Platform Management API.

ESS 3.0: New Deployment Model

The inrupt-kustomizer Docker image is no longer published. ESS is now deployed using Kustomize manifests from a Git repository provided by Inrupt. See the Installation guide for the new deployment procedure.

ESS is deployed using Kustomize manifests from a repository provided by Inrupt. The manifests can act as the base for major/minor upgrades as well as for the initial installation.

See also Release Notes.

Procedure

Note

Both the installation and the upgrade tutorials follow the Infrastructure as Code (IaC) practice for managing the system and assumes the ESS installation directory is under source control.

Step 1: Pull the New Release Tag

1. Go to your ESS installation directory (your fork of the Kustomize repository):

   cd ess-kustomize-releases

2. Fetch the latest tags from the upstream Inrupt repository:

   git fetch upstream --tags

3. Checkout a new branch for the upgrade and merge the new release tag:

   git checkout -b upgrade-to-v<NEW_VERSION>
   git merge v<NEW_VERSION>

4. Resolve any conflicts in your overlay and commit.

Step 2: Review and Update Configuration

Important

Configuration requirements may change between versions. Review the release notes and any version-specific documentation in the repository for new or changed configuration options.

1. Review the release notes for the target version for any configuration changes.

2. Update your configuration (secrets, environment variables, signing keys) as needed for the new version.

CRITICAL SECURITY REQUIREMENT

NEVER commit files containing secrets such as .env or JWT to version control. These files must be managed securely.

Store secrets securely using a cloud secrets management service, enterprise secrets vault, or Kubernetes Secrets with encryption at rest.

Kafka Message Encryption

ESS' services communicate with each other by sending messages through Kafka.

By default, Inrupt enables data encryption for all data that pass through the Kafka messaging system.

You MUST set the data encryption key values to a strong password.

For more information on the Kafka configurations, see ESS' Kafka Configuration.

Step 3: Optional. Customize Your Deployment Configuration

Optionally, you can further customize your ESS deployment using Kustomize overlays, such as to use certificates from an official Certificate Authority (CA).

For examples on customizing your deployment with overlays, see Customize ESS.

Step 4: Deploy

Apply your overlay to the cluster:

kubectl apply -k overlays/my-env

Tip

The deploy operation is idempotent. If the deploy operation does not complete successfully, you can safely retry the operation.

Warning: Self-signed Certificates

The provided base overlays create self-signed certificates. These self-signed certificates are for development purposes only. In production, ESS should be run with certificates from an official Certificate Authority (CA). For an example of how you can customize your deployment to use your production certificates, see Use Official Certificate Authority.

1. You can view the ESS components and services that are running:

   kubectl -n ess get all

2. To verify, go to https://start.{ESS DOMAIN}/.