Upgrade
ESS 3.1.0: Database Credential Separation
ESS 3.1.0 adds support for separate DML and DDL database credentials. The default configuration uses a single set of credentials — no changes are required to upgrade. To enable credential separation, see the 3.x Changelogs.
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
Go to your ESS installation directory (your fork of the Kustomize repository):
Fetch the latest tags from the upstream Inrupt repository:
Checkout a new branch for the upgrade and merge the new release tag:
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.
Review the release notes for the target version for any configuration changes.
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 4: 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 5: Deploy
Apply your overlay to the cluster:
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.
You can view the ESS components and services that are running:
To verify, go to
https://start.{ESS DOMAIN}/.
Last updated