Develocity Upgrade Guide

You are viewing documentation for Develocity versions before 2024.3!

If you’re using 2024.3 or newer, refer to the latest upgrade documentation.

If you have any questions, please contact the Develocity support team or your customer success representative.

Overview

This page provides an overview of the steps you should follow to upgrade Develocity.

Standalone

Upgrading

Before upgrading, check the release notes for the given release for any special considerations when upgrading from older versions of Develocity.

It’s recommend to use the same namespace when upgrading Develocity, as namespace changes create a new installation and require migration of data.

Any new or updated values you specify (for example, to use a new license file) will be merged with previous values when you run helm upgrade.

To force helm upgrade to use only the values that you set at upgrade time, run with --reset-values instead of --reuse-values.

Watch Out

Running helm upgrade with --reset-values will cause any previous values to be lost. All values (including license files, SSL certificates, etc.) will need to be set as part of the command.

For major version upgrades (for example, 2024.1 to 2024.2 or later), if data is stored in a user-managed database and superuser credentials are not supplied, the database setup script must be run before the upgrade.
The corresponding script for the major version to which the system is being upgraded can be downloaded from the appendix.

The version of the database setup script must match with the Develocity version you want to upgrade to.
For example if you want to upgrade to Develocity 2024.2 you must download the gradle-enterprise-database-setup-zip-2024.2.zip file which contains the script for this version of Develocity.

Upgrading Develocity irreversibly changes the database schema. This means you will need to restore the database from a backup if you need to downgrade or roll back the upgrade.
It’s strongly recommend to make a database backup before upgrading.

Online

1. Upgrade K3s

Use the compatibility matrix to identify the latest K3s version supported by the version of Develocity you are upgrading to.

Running the following command will:

Download the new k3s binary.
Update the systemd unit or openrc init script to reflect the arguments passed to the command.
Restart the k3s service.

$ curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=«k3s-version» sh - (1)

1	`«k3s-version»`, the K3s version you identified with the compatibility matrix.

2. Upgrade Helm

Use the compatibility matrix to identify the latest Helm version supported by the version of Develocity you are upgrading to.

Running the following command will:

Download the Helm installation script.
Set the permissions of the script, only the owner has read, write and execute permissions.
Install the Helm version which is specified with the -v flag.

$ curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
$ chmod 700 get_helm.sh
$ ./get_helm.sh -v «helm-version» (1)

1	`«helm-version»`, the Helm version you identified with the compatibility matrix.

2. Upgrade Develocity

To upgrade Develocity:

First, run the helm repo update gradle command to update locally available charts:

$ helm repo update gradle

Second, run the upgrade command:

$ helm upgrade \
    --namespace develocity \
    --reuse-values \(1)
    ge-standalone gradle/gradle-enterprise-standalone (2)

1	The `--reuse-values` parameter instructs Helm to reuse previous values.
2	Use the Helm release name you used during installation (`ge-standalone` in the examples in this guide).

Airgap

Upgrading an airgap instance of Develocity requires downloading the updates, transferring them to the host machine, and then installing them. Downloading an update for Develocity requires your license file.

1. Download required files

1.1. Download K3s

Use the compatability matrix to identify the latest version of K3s supported by your version of Develocity.

Download the K3s images, binary, and install script:

$ curl -LO https://github.com/k3s-io/k3s/releases/«k3s-version»/download/k3s

$ curl -LO \
  https://github.com/k3s-io/k3s/releases/«k3s-version»/download/k3s-airgap-images-amd64.tar.gz

$ curl -L -o install_k3s.sh https://get.k3s.io

If you are running Red Hat Enterprise Linux with SELinux enabled, download the K3s policy package:

SELinux policy package download

Lookup the latest version of the K3s SELinux Policy package:

$ K3S_SELINUX_DOWNLOAD_URL=$(curl -s https://api.github.com/repos/k3s-io/k3s-selinux/releases/latest | jq -r '.assets[] | select( .name | endswith("el8.noarch.rpm") ) | .browser_download_url') && echo $K3S_SELINUX_DOWNLOAD_URL

You can view the versions available and find the download links on the K3s SELinux releases page.

Then download it:

$ curl -L -o k3s-selinux.el8.noarch.rpm $K3S_SELINUX_DOWNLOAD_URL

1.2. Download Helm

Use the compatibility matrix to identify the latest version of Helm supported by your version of Develocity.

Download the Helm binary:

$ curl -L -o helm-linux-amd64.tar.gz https://get.helm.sh/helm-v«helm-version»-linux-amd64.tar.gz

You can see all available Helm releases on the Helm releases page.

1.3. Download airgap bundle

Save your Develocity license to the transfer directory as develocity.license.

Download and verify the airgap bundle:

$ curl -LOJd @develocity.license \
    https://registry.gradle.com/airgap/gradle-enterprise-standalone-«chart-version»-bundle.tar.gz (1)

1	`«chart-version»`, the Develocity version you want to upgrade to.

$ curl -LOJd @develocity.license \
    https://registry.gradle.com/airgap/gradle-enterprise-standalone-«chart-version»-bundle.tar.gz.sha256

$ sha256sum -c gradle-enterprise-standalone-«chart-version»-bundle.tar.gz.sha256

If the checksum verification fails, check the contents of the downloaded files for error messages.
If the error message indicates that your license is invalid/expired/not airgap enabled, you will need to request an updated license file by contacting your customer success representative.

Instead of running the above curl commands, you can download the airgap bundle by navigating to https://registry.gradle.com/airgap in your browser and following the instructions on the page.

2. Transfer files

Check that the transfer directory has the following files (additional files are fine):

k3s-airgap-images-amd64.tar.gz
k3s
install_k3s.sh
k3s-selinux.el8.noarch.rpm (only if you are running SELinux)
helm-linux-amd64.tar.gz
gradle-enterprise-standalone-«chart-version»-bundle.tar.gz

Once you’ve verified that you have the required files, transfer them to the host where you are installing Develocity.

3. Upgrade K3s

Follow these instructions on the host where you are installing Develocity with your transferred files present in the current directory.

If you are running Red Hat Enterprise Linux with SELinux enabled, first install the necessary policy packages:

SELinux Policy installation

Install the `container-selinux` package

Install the K3s SELinux Policy package you downloaded:

$ sudo yum install -y k3s-selinux.el9.noarch.rpm

Install K3s and make it available to the current user:

$ sudo mkdir -p /var/lib/rancher/k3s/agent/images/ && \
  sudo cp k3s-airgap-images-amd64.tar.gz /var/lib/rancher/k3s/agent/images/

$ (cd /var/lib/rancher/k3s/agent/images/ && sudo gunzip -f k3s-airgap-images-amd64.tar.gz)

$ sudo cp k3s /usr/local/bin && sudo chmod a+rx /usr/local/bin/k3s

$ sudo chmod a+rx ./install_k3s.sh && INSTALL_K3S_SKIP_DOWNLOAD=true ./install_k3s.sh

$ sudo chown $UID /etc/rancher/k3s/k3s.yaml && \
  mkdir -p "${HOME}/.kube" && \
  ln -sf /etc/rancher/k3s/k3s.yaml "${HOME}/.kube/config"

Verify that you can interact with the K3s cluster:

$ kubectl get namespace

Output

NAME                STATUS   AGE
default             Active   1h
kube-system         Active   1h
kube-public         Active   1h
kube-node-lease     Active   1h

4. Upgrade Helm

Follow these instructions on the host where you are installing Develocity with your transferred files present in the current directory.

To install Helm:

$ tar -zxvf helm-linux-amd64.tar.gz && sudo mv linux-amd64/helm /usr/local/bin/helm

Verify that helm is installed and working:

$ helm version

Output

version.BuildInfo{Version:"v3.15.4", GitCommit:"fa9efb07d9d8debbb4306d72af76a383895aa8c4", GitTreeState:"clean", GoVersion:"go1.22.6"}

5. Upgrade Develocity

5.1. Import the new container images

The new Develocity images need to be imported into K3s’s embedded container registry.

$ tar zxvf gradle-enterprise-standalone-«chart-version»-bundle.tar.gz (1)
$ sudo k3s ctr images import gradle-enterprise-standalone-«chart-version»-images.tar (2)

1	Unpacks the airgap bundle. You may have already done this, in which case you can skip this command.
2	Imports Develocity’s images into K3s

5.2. Upgrade Develocity

You can now upgrade Develocity:

$ helm upgrade \
    --namespace develocity \
    --reuse-values \(1)
    ge-standalone gradle-enterprise-standalone-«chart-version».tgz (2)

1	The `--reuse-values` parameter instructs Helm to reuse previous values.
2	Use the Helm release name you used during installation (`ge-standalone` in the examples in this guide).

Changing configuration values

If you need to update your configuration, you can do so by changing your configuration values.

Changing namespaces

It’s recommended to use the same namespace when upgrading Develocity.
For example, if you initially installed Develocity into the develocity namespace, your upgrade should also use that same namespace.

Kubernetes

This chapter assumes that you have a base knowledge of Kubernetes.

Upgrading

Before upgrading, be sure to check the upgrade notes section in the release notes for any special considerations when upgrading from older versions of Develocity.

Any new or updated Helm config values you specify (for example, to use a new license file) will be merged with previous Helm config values when you run the helm upgrade command.

To force helm upgrade to use only the values that you set at upgrade time, run with --reset-values instead of --reuse-values.

Running helm upgrade with --reset-values will cause any previous values to be lost. All values (including license files, SSL certificates, etc.) will need to be set as part of the command.

If using helm template, all values must be supplied for each invocation, including any files, as if you had used --reset-values.

You will be able to update any configuration values at upgrade time, but remember that some values are immutable after initial installation.
For example, persistent volume sizes for provisioners that don’t support dynamic resizing can’t be updated.

For major version upgrades (for example, 2024.1 to 2024.2 or later), if data is stored in a user-managed database and superuser credentials aren’t supplied, the database setup script must be run before the upgrade. The correct script for the major version to which the system is being upgraded can be downloaded from the appendix.

Upgrading Develocity irreversibly changes the database schema. This means that upgrades are irreversible unless the database is restored from a backup. As such, we strongly recommend users take a database backup before upgrading, and be prepared to restore it if the upgrade encounters a critical issue.

Upgrading with multiple replicas

If you have configured more than one replica, you must scale the replicas down to one before upgrading to avoid having mixed versions running at the same time.

Before applying the upgrade, run the following command to scale the application down to one replica:

$ helm upgrade \
    --namespace develocity \
    --reuse-values \
    --set=global.scaling.replicas=1 \
    --version «deployed-version» \
    ge gradle/gradle-enterprise (1)

1	Replace `gradle/gradle-enterprise` with `gradle-enterprise-«chart-version».tgz` for airgap installations.

Where «deployed-version» is the running version of Develocity, not the version being upgraded to.

The upgrade to the new version can now be executed. If your upgrade processes uses --reuse-values, you will need to include a --set=global.scaling.replicas=N argument where N is the desired replica number.

The following example performs a version upgrade and changes the replica number in one operation:

$ helm upgrade \
    --namespace develocity \
    --reuse-values \
    --set=global.scaling.replicas=N \
    --version «deployed-version» \
    ge gradle/gradle-enterprise (1)

1	Replace `gradle/gradle-enterprise` with `gradle-enterprise-«chart-version».tgz` for airgap installations.

Online

1. Upgrade Helm

Identify the latest Helm versions supported by the version of Develocity you are upgrading to using the compatibility matrix.

Running the following command will:

Download the Helm installation script.
Set the permissions of the script, only the owner has read, write and execute permissions.
Install the Helm version which is specified with the -v flag.

$ curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
$ chmod 700 get_helm.sh
$ ./get_helm.sh -v «helm-version» (1)

1	`«helm-version»`, the Helm version you identified with the compatibility matrix.

2. Upgrade Develocity

To upgrade Develocity:

Run helm repo update gradle to update locally available charts.
Run the upgrade command:

$ helm upgrade \
    --namespace develocity \
    --reuse-values \ (1)
    ge gradle/gradle-enterprise (2)

1	The `--reuse-values` parameter instructs Helm to reuse previous values.
2	Use the Helm release name you used during installation (`ge` in the examples in this guide).

Airgap

Upgrading an airgap instance of Develocity requires downloading the updates, transferring them to a machine with access to the Kubernetes cluster and container registry, and then installing them. Downloading an update for Develocity requires your license file.

If you are using helm template (or --reset-values), you will need to specify all installation options again, including files. You will need to transfer these files to the machine used to access the cluster.

1. Download required files

1.1 Download Helm

Use the compatibility matrix to identify the latest version of Helm supported by your version of Develocity.

Download the Helm binary:

$ curl -L -o helm-linux-amd64.tar.gz https://get.helm.sh/helm-v«helm-version»-linux-amd64.tar.gz

You can see all available Helm releases on the Helm releases page.

1.2. Download Airgap Bundle

Save your Develocity license to the transfer directory as develocity.license.

Download and verify the airgap bundle:

$ curl -LOJd @develocity.license \
    https://registry.gradle.com/airgap/gradle-enterprise-«chart-version»-bundle.tar.gz

$ curl -LOJd @develocity.license \
    https://registry.gradle.com/airgap/gradle-enterprise-«chart-version»-bundle.tar.gz.sha256

$ sha256sum -c gradle-enterprise-«chart-version»-bundle.tar.gz.sha256

Instead of running the above curl commands, you can download the airgap bundle by navigating to https://registry.gradle.com/airgap in your browser and following the instructions on the page.

2. Transfer files

Check that the transfer directory has the following files (additional files are fine):

helm-linux-amd64.tar.gz
gradle-enterprise-«chart-version»-bundle.tar.gz

Once you’ve verified that you have the required files, transfer them to the host where you are installing Develocity.

3. Upload images

Follow these instructions on the host with connectivity to the internal container registry with your transferred files present in the current directory.

You must be logged in to the registry before running these commands.

Expand the bundle and upload the images to the internal container registry:

$ tar zxvf gradle-enterprise-«chart-version»-bundle.tar.gz
$ ./upload-images.sh --registry=registry.example.com/gradle-enterprise

4. Upgrade Helm

Follow these instructions on the host with connectivity to the Kubernetes cluster with your transferred files present in the current directory.

To install Helm:

$ tar -zxvf helm-linux-amd64.tar.gz && sudo mv linux-amd64/helm /usr/local/bin/helm

Verify that helm is installed and working:

$ helm version

Output

version.BuildInfo{Version:"v3.15.4", GitCommit:"fa9efb07d9d8debbb4306d72af76a383895aa8c4", GitTreeState:"clean", GoVersion:"go1.22.6"}

5. Upgrade Develocity

Then upgrade Develocity:

$ tar zxvf gradle-enterprise-«chart-version»-bundle.tar.gz (1)
$ helm upgrade \
    --namespace develocity \
    --reuse-values \(2)
    ge gradle-enterprise-«chart-version».tgz (3)

1	Unpacks the airgap bundle. You may have already done this, in which case you can skip this command.
2	The `--reuse-values` parameter instructs Helm to reuse previous values.
3	Use the Helm release name you used during installation (`ge` in the examples in this guide).

See also

Install the container-selinux package

Install the `container-selinux` package