Upgrade

Starting in 2.0, to set up a deployment, ESS provides various Kustomize overlays These overlays can act as the base for major/minor upgrades as well as for the initial installation.

Note

Starting in ESS 2.1, the image reference to PostgreSQL, in Inrupt’s non-production overlay (i.e., the standalone overlay), has been upgraded from version 14 to 15. Customers who are using Inrupt’s standalone overlay need to reset their state or upgrade Postgres.

This change does NOT affect those deployments that use the production overlay (i.e., the scalable-cloud overlay). Customers using the scalable-cloud overlay use their own stateful services and are not impacted by the change.

Starting in 2.0, follow the instructions below to upgrade minor version; e.g., from 2.0 to 2.1.

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.

The tutorial illustrates the steps assuming GitHub as the source control system.

Step 1: Prepare the Installation Directory

1. Go to your ESS installation directory.

   cd ${HOME}/ess
   

2. Checkout a new branch.

3. Remove all files in this branch to have an empty ${HOME}/ess directory.

   Important

   Ensure that the directory is empty.

4. Login to Inrupt’s private Docker registry. When prompted for your password, enter your entitlement token:

   docker login  --username <userid> docker.software.inrupt.com
   

5. Get the latest 2.1 version of the inrupt-kustomizer:

   docker pull docker.software.inrupt.com/inrupt-kustomizer:2.1
   

6. Initialize an empty installation directory with a base overlay for your environment:

   Important

   If the directory is not empty, the inrupt-kustomizer does not attempt to initialize the directory with the base configuration files.

   docker run -it -v ${HOME}/ess:/kustomize docker.software.inrupt.com/inrupt-kustomizer:2.1
   

   Follow the prompts to install the base overlay for your upgrade version, same as the initial installation.

Step 2: Update Inputs and Build

During the initialization, Inrupt generates a readme.txt file in the installation directory. The file provides instructions on updating inputs for your deployment and building the deployment file.

1. Go to the installation directory.

   cd ${HOME}/ess
   

2. Using the instructions in the readme.txt file, update the inputs in the base overlay for your deployment.

   Tip on 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.

   As part of updating the inputs for your deployment, define the data encryption keys for Kafka. Specifically, in the kafka-credentials.env file, downloaded as part of the installation:

   • Set INRUPT_KAFKA_SOLIDRESOURCE_CIPHER_PASSWORD to a strong password. This is used for encrypting and decrypting Solid resource notification events.

   • Set INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD to a strong password. This is used for encrypting and decrypting Audit events.

   • Set INRUPT_KAFKA_SOLIDACCESSCONTROLRESOURCE_CIPHER_PASSWORD to a strong password. This is used for encrypting and decrypting Access Control Resource (ACR) notification events.

   Tip

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

   Update any other input(s) as specified in the kafka-credentials.env file.

   For more information on the Kafka configurations in the kafka-credentials.env file, see ESS’ Kafka Configuration.

3. After updating the inputs, build the deployment file per the instructions in the readme.txt file.

4. Commit all changes in the directory to source control.

   Important

   Ensure that the repo is private.

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).

Note

You can opt to customize after setting up a base deployment.

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

Step 4: Deploy

After you have built the deployment file, you can deploy.

1. If not already, go to the installation directory:

   cd ${HOME}/ess
   

2. Deploy to your Kubernetes environment:

   kubectl apply -f kustomized.yaml
   

   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.

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

   kubectl -n ess get all
   

4. For local standalone deployments, add the ESS service domains to the /etc/hosts file on your local machine.

   The following steps are specific to Linux operating system.

   1. Get your local Kubernetes cluster IP address:

      K8_IP=$(kubectl get nodes -o jsonpath="{.items[*].status.addresses[?(@.type=='InternalIP')].address}")
      

   2. Get a list of the ESS service domains:

      ESS_DOMAINS=$(grep "host: " kustomized.yaml | awk '{print $3}' | sort -u | tr -d '\r' | tr '\n' ' ')
      

   3. Backup your /etc/hosts file:

      sudo cp /etc/hosts /etc/hosts.bak
      

   4. Update the /etc/hosts:

      sudo sed -n -e '/# ESS-DOMAINS-BEGIN/,/# ESS-DOMAINS-END/!p' -e '$a# ESS-DOMAINS-BEGIN\n'"$K8_IP $ESS_DOMAINS"'\n# ESS-DOMAINS-END' -i /etc/hosts
      

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