> For the complete documentation index, see [llms.txt](https://docs.inrupt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inrupt.com/ess/upgrade.md).

# Upgrade

ESS is deployed using [Kustomize](https://github.com/kubernetes-sigs/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](https://docs.inrupt.com/ess/releases.md).

{% hint style="warning" %}
Before you upgrade, read the [upgrade notes](#version-specific-upgrade-notes) for every version between your current version and the one you are upgrading to.
{% endhint %}

## Version-Specific Upgrade Notes

### ESS 3.5.0

{% hint style="info" %}
There is no ESS 3.4 release. ESS 3.5.0 is the next release after ESS 3.3.0, and you can upgrade directly from 3.3.
{% endhint %}

**Required before you upgrade**

* **Kubernetes**: ESS now requires Kubernetes 1.31 or later.
* **MCP clients**: The [MCP Service](https://docs.inrupt.com/ess/services/service-mcp.md) supports only MCP protocol revision **`2026-07-28`**, and **`getResource`** returns an embedded resource instead of plain text. Update MCP clients before you upgrade.
* **MCP tokens**: The MCP Service's built-in authorization server has been removed. MCP clients get tokens from the [Platform Management service](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md).
* **MCP image and settings**: The image is renamed from **`inrupt-ess-mcp-resource`** to **`inrupt-ess-mcp`**. In your overlay, rename **`INRUPT_MCP_RESOURCE_STORAGE_SERVICE`** to **`INRUPT_STORAGE_HTTP_BASE_URL`**, and **`INRUPT_MCP_RESOURCE_ACCESS_GRANT_SERVICE`** to **`INRUPT_VC_HTTP_BASE_URL`**.
* **Kafka**: ESS no longer encrypts Kafka message content, and no encryption keys are needed. In your overlay, remove the **`kafka-encrypted-channels`** component, and rename **`audit/outgoing-encrypted`** and **`audit/incoming-encrypted`** to **`audit/outgoing`** and **`audit/incoming`**. Applications outside ESS that read the audit topics must use the new topic names, **`auditv1eventsproducer`** and **`auditv1events`**, and read plain JSON. See [ESS' Kafka Configuration](https://docs.inrupt.com/ess/services/appendix/appendix-kafka-configuration.md#message-encryption).
* **Storage Metrics**: Storage Metrics is now a Deployment instead of a CronJob. Update dashboards and alerts that use **`com_inrupt_storage_metrics_MetricsCollector`** to use **`inrupt_storage_pods`**. If your overlay patches the CronJob, patch the Deployment instead; see [Modify Storage Metrics Collection](https://docs.inrupt.com/ess/installation/customize-configurations/customization-pod-maintenance/modify-storage-metrics.md).

**Changes that may affect your applications**

* **Token exchange**: Token exchange requests must now include **`subject_token_type`**.
* **Access Grant issuer metadata**: Clients that read issuer metadata from the Access Grant Service's root URL must use **`/.well-known/vc-configuration`**.
* **Solid OIDC Broker static clients**: Clients whose ID or secret contains `+` or `%` must form-urlencode them when using **`client_secret_basic`**.
* **Database connections**: Each ESS service now limits its database connections. If you run more Pods, check that your database has enough connections; see [Database Connections](https://docs.inrupt.com/ess/administration/scaling.md#database-connections).

See the [Release Notes](https://docs.inrupt.com/ess/releases.md) and [3.x Changelogs](https://docs.inrupt.com/ess/releases/changelog.md) for all changes.

### ESS 3.3.0

If you consume ESS audit events, note two changes in 3.3.0:

* The **`service-started`** and **`service-shutdown`** events are no longer emitted.
* Audit events for the Access Grant Service's **`/query`** and **`/verify`** endpoints are now opt-in via [**`INRUPT_VC_AUDIT_READ_OPERATIONS_ENABLED`**](https://docs.inrupt.com/ess/services/service-access-grant.md#inrupt_vc_audit_read_operations_enabled), which defaults to **`false`**. All other Access Grant Service endpoints remain unconditionally audited.

### ESS 3.1.0

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](https://docs.inrupt.com/ess/releases/changelog.md).

### ESS 3.0.0

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](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md). 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](https://docs.inrupt.com/ess/services/service-platform-management/platform-management-api.md).

**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](https://docs.inrupt.com/ess/installation.md) guide for the new deployment procedure.

## Procedure

{% hint style="info" %}
**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.
{% endhint %}

### Step 1: Pull the New Release Tag

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

   ```sh
   cd ess-kustomize-releases
   ```
2. Fetch the latest tags from the upstream Inrupt repository:

   ```sh
   git fetch upstream --tags
   ```
3. Checkout a new branch for the upgrade and merge the new release tag:

   ```sh
   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

{% hint style="warning" %}
**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.
{% endhint %}

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.

{% hint style="danger" %}
**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.
{% endhint %}

### Step 3: Optional. Customize Your Deployment Configuration

Optionally, you can further customize your ESS deployment using Kustomize [overlays](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#bases-and-overlays), such as to use certificates from an official Certificate Authority (CA).

For examples on customizing your deployment with overlays, see [Customize ESS](https://docs.inrupt.com/ess/installation/customize-configurations.md).

### Step 4: Deploy

Apply your overlay to the cluster:

```sh
kubectl apply -k overlays/my-env
```

{% hint style="info" %}
**Tip**

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

{% hint style="danger" %}
**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](https://docs.inrupt.com/ess/installation/customize-configurations/customization-security/use-production-lets-encrypt.md).
{% endhint %}

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

   ```sh
   kubectl -n ess get all
   ```
4. To verify, go to **`https://start.{ESS DOMAIN}/`**.
