Standalone

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.

Gradle recommends that administrators continue to use the same namespace when upgrading Develocity, as namespace changes create a new installation and require migration of data. For example, if you initially installed Develocity into the gradle-enterprise namespace, your upgrade should also use that. The default for the following snippets is develocity.

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.

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 (e.g. 2021.2.4 to 2021.3 or later), if data is stored in a user-managed database and superuser credentials are not supplied, the database setup script must be run prior to 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 you will need to restore the database from a backup if you need to downgrade or roll back the upgrade. It is strongly recommend to take a database backup before upgrading.

Online

1. Upgrade K3s and Helm

First, use the compatability matrix to identify the latest k3s and Helm versions supported by the version of Develocity you are upgrading to.

Then upgrade K3s:

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

and Helm:

$ 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»
2. Upgrade Develocity

To upgrade Develocity:

  1. Execute helm repo update gradle to update locally available charts.

  2. Execute the upgrade command:

$ helm upgrade \
    --namespace develocity \
    --reuse-values \ (1)
    ge-standalone gradle/{chartName} (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
a. 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
b. Download Helm

Use the compatability 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.
c. Download install 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
$ 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 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 contains 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

  1. Install the container-selinux package. This is a package that can be found in Red Hat Enterprise Linux’s default repository. Install this package on the airgapped server just like you would install any other package. If your organization has an internal mirror of the Red Hat package repositories, you can run:

    $ sudo yum install -y container-selinux

  2. Install the K3s SELinux Policy package you downloaded:

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

Then install and set up K3s:

  1. 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"

  2. Verify that you can interact with the K3s cluster:

    $ kubectl get ns

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

version.BuildInfo{Version:"v3.13.3", GitCommit:"c8b948945e52abba22ff885446a1486cb5fd3474", GitTreeState:"clean", GoVersion:"go1.21.5"}
5. Upgrade Develocity
a. Import the new 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
b. 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

To change configuration values without changing the version of Develocity, follow the same procedure as for upgrading, but specify the current version to ensure that a later version does not accidentally get installed.

For airgap installations, you should already have the necessary files on the host from the installation process.

To check the currently deployed version, run:

$ helm history --namespace develocity ge-standalone --max 1

To apply new configuration values to an online installation, run:

$ helm upgrade \
    --namespace develocity \
    ge-standalone gradle/{chartName} \
    --version «deployed-version»
    --reuse-values
    «new values options»

or for an airgap installation:

$ helm upgrade \
    --namespace develocity \
    ge-standalone gradle-enterprise-standalone-«deployed-version».tgz \
    --version «deployed-version»
    --reuse-values
    «new values options»
Since you are using the same version of Develocity, you should already have the gradle-enterprise-standalone-«deployed-version».tgz Helm chart file on the host. If not, you can obtain it by following step 1.c above. The K3s and Helm files are not necessary.
Ensure the chart file’s version matches the version of the installed Develocity instance. If you use a different version, Develocity’s images may not be present on the host, and Develocity will not start. To use a later version of Develocity, follow the upgrade instructions earlier in this guide.

Where «deployed-version» is the running version of Develocity. The above examples reuse previous values by default. Any specified values will override the existing values. Alternatively, if you wish to specify all values explicitly (ignoring any previously set values), 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.

Configuration values are provided to Helm when running the helm command by:

  • providing a Helm values file (which can contain inline files) with --values

  • providing files (such as the Develocity license or certificates) with --set-file

If you have made local modifications to a Helm values file, apply the changes to your installation by running an upgrade command (see above) with a --values «updated-values-file» option.

If you have made local modifications to a file you previously provided via --set-file, apply the changes to running an upgrade command (see above) with a --set-file option.

Changing namespaces

Gradle recommends that administrators continue 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

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

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 keep in mind that some values are immutable after initial installation. For example, persistent volume sizes for provisioners that do not support dynamic resizing cannot be updated.

For major version upgrades (e.g. 2021.2.4 to 2021.3 or later), if data is stored in a user-managed database and superuser credentials are not supplied, the database setup script must be run prior to 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/{chartName} (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 compatability matrix.

Then upgrade Helm:

$ 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»
2. Upgrade Develocity

To upgrade Develocity:

  1. Execute helm repo update gradle to update locally available charts.

  2. Execute the upgrade command:

$ helm upgrade \
    --namespace develocity \
    --reuse-values \ (1)
    ge gradle/{chartName} (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 access to the 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
a. Download Helm

Use the compatability 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.
b. Download install 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

If 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 contains 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 prior to running these commands.

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

$ tar zxvf {chartName}-{versionWithPatch}-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

version.BuildInfo{Version:"v3.13.3", GitCommit:"c8b948945e52abba22ff885446a1486cb5fd3474", GitTreeState:"clean", GoVersion:"go1.21.5"}
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).

Changing configuration values

To change configuration values, follow the same procedure as for upgrading, but specify the current version to ensure that a later version does not accidentally get installed.

To check the currently deployed version, run:

$ helm history --namespace develocity ge --max 1

To apply new configuration values to a Helm-managed online installation, run:

$ helm upgrade \
    --namespace develocity \
    ge gradle/{chartName} \
    --version «deployed-version»
    --reuse-values
    «new values options»

or for a Helm-managed airgap installation:

$ helm upgrade \
    --namespace develocity \
    ge gradle-enterprise-«deployed-version».tgz \
    --version «deployed-version»
    --reuse-values
    «new values options»
Since you are using the same version of Develocity, you should already have the gradle-enterprise-«deployed-version».tgz Helm chart file on the host. If not, you can obtain it by following this step of the installation guide.
Ensure the chart file’s version matches the version of the installed Develocity instance. If you use a different version, Develocity’s images may not be present on the host, and Develocity will not start. To use a later version of Develocity, follow the upgrade instructions earlier in this guide.

Where «deployed-version» is the running version of Develocity. The above examples reuse previous values by default. Any specified values will override the existing values. Alternatively, if you wish to specify all values explicitly (ignoring any previously set values), 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.

Configuration values are provided to Helm when running the helm command by:

  • providing a Helm values file (which can contain inline files) with --values

  • providing files (such as the Develocity license or certificates) with --set-file

If you have made local modifications to a Helm values file, apply the changes to your installation by running an upgrade command (see above) with a --values «updated-values-file» option.

If you have made local modifications to a file you previously provided via --set-file, apply the changes to running an upgrade command (see above) with a --set-file option.

Changing namespaces

Gradle recommends that administrators continue 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.

Changing storage class

Storage classes cannot be changed once a persistent volume claim is in place. If you need to alter any configured Develocity storage classes, please contact Gradle support for assistance.

Appendix

Appendix A: Database setup scripts