Kubernetes Online Upgrade

This section provides step-by-step instructions for upgrading a Kubernetes Develocity environment with internet access.

Upgrade Helm

Running the following commands 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 specified with the -v flag.

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
chmod 700 get_helm.sh
./get_helm.sh -v v4.1.3

For more information, see the official Helm installation documentation.

Verify that helm is installed and working:

helm version

Database

It’s strongly recommended to make a database backup before upgrading.

Upgrading Develocity irreversibly changes the database schema.
You will need to restore the database from a backup if you need to roll back the upgrade.

User-Managed Database

For major version upgrades (for example, 2025.4 to 2026.1), 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 corresponding scripts can be downloaded via the following links:

Depending on the size of your database, it may take from a few minutes to up to hours.

Scale Down the Application to One Replica

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

 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 «PREVIOUSLY_DEPLOYED_VERSION» \(1)
  ge \
  gradle/gradle-enterprise
1 «PREVIOUSLY_DEPLOYED_VERSION» is the running version of Develocity (e.g. 2025.4.5), not the version you are upgrading to.

Upgrade Develocity

Update Repository

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

helm repo update gradle

Adjust values.yaml Configuration

Adjust your values.yaml configuration file. You can find a detailed list of required changes in the Changes section.

You can discover your current configuration by running the following command:

helm get values \
  --namespace develocity \(1)
  ge \(2)
  > values.yaml (3)
1 The namespace used to install Develocity.
2 Release name.
3 Output file.

Adjust Unattended Configuration

If you are using unattended configuration, export the current configuration using the Admin UI. Then adjust the exported configuration according to the Changes section.

You can validate your unattended configuration against the schema by using the Develocity command line tool (develocityctl):

develocityctl config-file validate unattended-configuration.yaml

If your unattended configuration is embedded in the values.yaml file, you can validate it with the following command:

cat values.yaml | yq '.global.unattended.configuration' | develocityctl config-file validate -

Unattended configuration is versioned. If an older version is provided, the application migrates the config to the latest version automatically. If you use version control, it’s recommended that you export your unattended configuration after the upgrade and store the latest version in your repository. See Migrating Unattended Configuration for details.

Decide on the Upgrade Command

You may need to run different upgrade commands depending on your configuration changes.

The helm upgrade command is used to upgrade an existing release. It has several flags that control how the values are used for the upgrade. Specifically, the --reuse-values and --reset-values flags modify the behavior around the values passed to the upgrade.

  • --reuse-values: Keeps existing values and allows the setting of additional values.

  • --reset-values: Discards any previously set values and requires all values to be set.

Both flags give you fine-grained control over how values are managed during an upgrade, depending on whether you want to preserve or reset your previous configurations.

For more information about the helm upgrade command, refer to the official Helm documentation.

No Changes

Use case: You want to upgrade but keep all the values from the current deployment without any modifications.

This is useful to ensure that existing values remain unchanged during an upgrade.
This is the most straightforward option if no configuration needs to be modified.

helm upgrade \
  --namespace develocity \(1)
  --reuse-values \(2)
  --version 2026.1.0 \(3)
  ge \(4)
  gradle/gradle-enterprise (5)
1 The namespace used to install Develocity
2 Reuse the configuration from the current deployment without any modifications
3 The Develocity version. If omitted, the latest version will be installed
4 The release name
5 The chart name

Simple Changes

Use case: You have an existing configuration and want to update the license value and disable ingress SSL, but keep the rest of the configuration.

helm upgrade \
  --namespace develocity \(1)
  --reuse-values \(2)
  --set-file global.license.file=./develocity.license \(3)
  --set ingress.ssl.enabled=false \(4)
  --version 2026.1.0 \(5)
  ge \(6)
  gradle/gradle-enterprise (7)
1 The namespace used to install Develocity
2 Reuse the configuration from the current deployment without any modifications
3 The path to the new license file
4 Disable the Ingress SSL
5 The Develocity version. If omitted, the latest version will be installed
6 The release name
7 The chart name
This method works correctly only if you add new values or override existing values.
It won’t remove any previously set values, so that you may have a corrupted configuration.

Example:

previously-applied-config.yaml
objectStorage:
  type: s3
  s3:
    bucket: example-bucket
    region: example-aws-region-1
    credentials:
      source: environment
new-config.yaml
objectStorage:
  type: s3
  s3:
    bucket: example-bucket
    region: example-aws-region-1
    credentials:
      type: instanceProfile

Upgrade command:

helm upgrade \
  --namespace develocity \
  --reuse-values \(1)
  --values new-config.yaml \(2)
  --version 2026.1.0 \
  ge \
  gradle/gradle-enterprise
1 Reuse the configuration from the current deployment without any modifications
2 Additionally, apply the partial configuration from the new-config.yaml file

You might expect the source: environment to be removed and the type: instanceProfile to be added, but the result is different:

objectStorage:
  type: s3
  s3:
    bucket: example-bucket
    region: example-aws-region-1
    credentials:
      source: environment
      type: instanceProfile

The application throws an error since the old configuration block is no longer supported, but it’s still present.

UPGRADE FAILED: execution error at (gradle-enterprise/templates/enterprise-app/deployment.yaml:3:3):
The `objectStorage.s3.credentials.source` attribute was removed.
Please use `objectStorage.s3.credentials.type instead.
 The old attribute isn’t ignored during the upgrade process to quickly detect misconfigurations.

Complex Changes

The --reset-values flag will discard all the values from the previous configuration.

Helm will use the default values defined in the chart during the upgrade, and any custom values previously set (whether through --set, --set-file, --values, or from the original release) will be ignored unless explicitly provided during the upgrade.

Use case: You want to upgrade to Develocity 2026.1 and adjust the Object Storage configuration (see the example above).

helm upgrade \
  --namespace develocity \(1)
  --reset-values \(2)
  --values values.yaml \(3)
  --set-file global.license.file=./develocity.license \(4)
  --version 2026.1.0 \(5)
  ge \(6)
  gradle/gradle-enterprise (7)
1 The namespace used to install Develocity
2 Discard old configuration settings
3 The path to the entire configuration file. No settings are preserved from the previous configuration
4 The path to the Develocity license file (if not included in values.yaml)
5 The Develocity version. If omitted, the latest version will be installed
6 The release name
7 The chart name

Use dry-run to Verify the Upgrade

Before upgrading, you can use the --dry-run flag to verify the upgrade process.
This will show you the changes that would be made without actually applying them.

For example (if no changes were required):

helm upgrade \
  --namespace develocity \
  --reuse-values \
  --version 2026.1.0 \
  ge \
  gradle/gradle-enterprise \
  --dry-run

The actual command may differ depending on the outcome from the previous step.

If the --dry-run command completes successfully, you can proceed with the upgrade.
Otherwise, review the output and make any necessary changes to your configuration.

--dry-run validates syntax, verifies the chart structure, validates your configuration with schema, and checks the generated Kubernetes manifests for errors. However, it won’t detect issues like typos in optional fields or guarantee the application configuration will function correctly.

Execute the Upgrade

Remove --dry-run from the command above and execute the upgrade.

For example (if no changes were required):

helm upgrade \
  --namespace develocity \
  --reuse-values \
  --version 2026.1.0 \
  ge \
  gradle/gradle-enterprise

Verify the Upgrade

After executing the upgrade, verify that the Helm release has been updated:

helm --namespace develocity list
Output
NAME      NAMESPACE     REVISION    UPDATED            STATUS      CHART      APP VERSION
ge        develocity    2           2026-03-25         deployed    2026.1.0   2026.1.0

You can inspect the status of the Develocity Pods:

kubectl --namespace develocity get pods

Wait until all Pods have a status of Running.

Develocity has a /ping endpoint, which can be used to verify that the application is up and running:

curl -sw \\n --fail-with-body --show-error https://«develocity-host»/ping

It should return {"status":"UP"} as response message.

Scale Up the Application to N Replicas

 Before you scale up the application, ensure the upgrade went well and the application is working. 
helm upgrade \
  --namespace develocity \
  --reuse-values \
  --set=global.scaling.replicas=N \(1)
  --version «NEWLY_DEPLOYED_VERSION» \(2)
  ge \(3)
  gradle/gradle-enterprise
1 N is the number of replicas you want to scale up to.
2 «NEWLY_DEPLOYED_VERSION» is the version of Develocity you just upgraded to (e.g. 2026.1.0).
3 The release name.