> 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

{% hint style="info" %}
**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/releases/changelog.md).
{% endhint %}

{% hint style="danger" %}
**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](/ess/services/service-platform-management/token-exchange.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](/ess/services/service-platform-management/platform-management-api.md).
  {% endhint %}

{% hint style="success" %}
**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](/ess/installation.md) guide for the new deployment procedure.
{% endhint %}

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](/ess/releases.md).

## 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 %}

{% hint style="warning" %}
**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](/ess/services/appendix/appendix-kafka-configuration.md).
{% endhint %}

### Step 4: 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](/ess/installation/customize-configurations.md).

### Step 5: 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](/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}/`**.