Gradle Enterprise Upgrade Guide | Gradle Enterprise Docs

Standalone

Upgrading

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

Gradle Enterprise upgrades irreversibly update 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.

To upgrade K3s, Helm, and Gradle Enterprise, follow the same procedure in the appropriate installation guide. However, there are some notes to consider:

Run helm repo update gradle to update locally available charts.
Run helm upgrade instead of helm install.
Use the same Helm release name (ge-standalone in the examples in this guide).
When running a helm upgrade --reuse-values, Helm will reuse values that were previously used. This means that you can run:
```
$ helm upgrade \
    --namespace gradle-enterprise \
    --reuse-values \
    ge-standalone gradle/gradle-enterprise-standalone
```
or for airgap installations:
```
$ helm upgrade \
    --namespace gradle-enterprise \
    --reuse-values \
    ge-standalone gradle-enterprise-standalone-{chartVersion}.tgz
```
and not need to specify any values. If you do specify some changed values (for example, to use a new license file), they will be merged with your previous values.

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

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 gradle-enterprise ge-standalone --max 1

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

$ helm upgrade \
    --namespace gradle-enterprise \
    ge-standalone gradle/gradle-enterprise-standalone \
    --version «deployed-version»
    --reuse-values
    «new values options»

or for a Helm-managed airgap installation:

$ helm upgrade \
    --namespace gradle-enterprise \
    ge-standalone gradle-enterprise-standalone-«deployed-version».tgz \
    --version «deployed-version»
    --reuse-values
    «new values options»

Where «deployed-version» is the running version of Gradle Enterprise. 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 Gradle Enterprise 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.

Kubernetes

Upgrading

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

To upgrade Helm and Gradle Enterprise follow the same procedure as for an initial installation. However, there are some notes to consider:

Run helm repo update gradle to update locally available charts.
Run helm upgrade instead of helm install.
Use the same Helm release name (ge in the examples in this guide).
When running a helm upgrade, Helm will reuse values that were previously used. This means that you can run:
```
$ helm upgrade \
    --namespace gradle-enterprise \
    --reuse-values \
    ge gradle/gradle-enterprise
```
or for airgap installations:
```
$ helm upgrade \
    --namespace gradle-enterprise \
    --reuse-values \
    ge gradle-enterprise-{chartVersion}.tgz
```
and not need to specify any values. If you do specify some changed values (for example, to use a new license file), they will be merged with your previous values.

Alternatively, 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.
You will be able to update any configuration values at upgrade time, but keep in mind that some values are immutable after initial installation, such as persistent volume sizes for provisioners that do not support dynamic resizing.
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 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 gradle-enterprise \
    --reuse-values \
    --set=global.scaling.replicas=1 \
    --version «deployed-version» \
    ge gradle/gradle-enterprise

Where «deployed-version» is the running version of Gradle Enterprise, 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 gradle-enterprise \
    --reuse-values \
    --set=global.scaling.replicas=N \
    --version {chartVersion} \
    ge gradle/gradle-enterprise

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 gradle-enterprise ge --max 1

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

$ helm upgrade \
    --namespace gradle-enterprise \
    ge gradle/gradle-enterprise \
    --version «deployed-version»
    --reuse-values
    «new values options»

or for a Helm-managed airgap installation:

$ helm upgrade \
    --namespace gradle-enterprise \
    ge gradle-enterprise-«deployed-version».tgz \
    --version «deployed-version»
    --reuse-values
    «new values options»

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 Gradle Enterprise 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 Storage Class

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

Appendix

Appendix A: Upgrade Notes

Gradle Enterprise 2023.1 long startup time

Gradle Enterprise 2023.1 had an issue that can result in a very long first startup time after upgrade for some installations. It is strongly recommended that customers who have not yet upgraded to 2023.1 instead upgrade directly to 2023.1.1 or later.

Build Cache Node and Test Distribution Agent now require a Java 17 runtime

The required runtime version of Java has changed from 11 to 17 in this release for both the Build Cache Node and the Test Distribution Agent. If you are currently using their JAR distribution, please install a Java 17 compatible runtime environment on your server. In the interim, you can continue to use older versions to connect to Gradle Enterprise.

For the Test Distribution Agent Docker image, the bundled JDK is used to run the agent process itself and to fork JVMs to execute tests. Therefore, if you are relying on the JDK 11 version provided by the image to execute tests, please follow the instructions in the documentation to build a custom image that also contains JDK 11.

Deprecation of pre-2021.3 versions of Test Distribution Agent, Test Distribution Gradle Plugin, and Gradle Enterprise Maven Extension (for use with Test Distribution)

Using Test Distribution with versions older than Test Distribution Gradle plugin 2.2, Gradle Enterprise Maven extension 1.11, or Test Distribution agent 1.6 is now deprecated. These versions were introduced before Gradle Enterprise 2021.3 and use a communication protocol that requires manually specifying JVM arguments on JDK 17 and later. Therefore, support for them will be removed in 2023.2. Please check your builds and agents and update them as necessary.

The maximum number of build cache entries may reduce after upgrading

Internal changes to the build cache service now require more disk space for internal bookkeeping, leaving less room for build cache entries. The degree of the change depends on the number of entries stored in the cache. Caches with a million entries or more may experience a reduction in available disk space for cache entries by up to 2GiB, which is expected to have a negligible impact on build cache effectiveness.

Deprecation of anonymous access to build cache configuration

Allowing anonymous access to the “Configure build caches” permission (formerly known as “Build cache admin” in earlier versions of Gradle Enterprise) is deprecated. It will be removed in future versions of Gradle Enterprise.

Backups created by Gradle Enterprise 2019.2 or earlier can no longer be restored directly

Backups made using Gradle Enterprise 2019.2 or earlier cannot be restored directly to an installation of Gradle Enterprise 2023.1 (or later). Backups from any version after 2019.2 may still be restored directly to a Gradle Enterprise 2023.1 installation.

To restore a backup from Gradle Enterprise 2019.2 or earlier to a Gradle Enterprise 2023.1 installation, you will first need to restore to a pre 2023.1 version and then either upgrade that installation or create a backup of that installation and restore it to a 2023.1 installation.