Introduction
Prior to version 2022.1, Gradle Enterprise has been distributed as a Replicated Appliance or Replicated Ship / Kubernetes application.
From 2022.1 onwards, Gradle Enterprise is also distributed and installed using the Helm Kubernetes package manager. This is the preferred method to install Gradle Enterprise, and the previous distribution methods are now considered deprecated and will not be supported past 2022.
Migration options
There are two deployment options:
-
A standalone distribution for installation into a single host, similar to the existing appliance installation.
-
A distribution for installation into a Kubernetes cluster, similar to the existing Kubernetes installation.
This guide covers the following migration paths:
Migration of data
In all cases, data is preserved, including Gradle Enterprise configuration (i.e. from the Administration page). That is, there is no explicit data migration required in order to migrate a Replicated-based installation to a Helm-based one.
Appliance to standalone migration
Prior to starting, please review the Gradle Enterprise Helm Standalone Installation Manual which explains Helm and the Gradle Enterprise standalone distribution.
Prerequisites
-
To minimise downtime, this procedure recommends starting the K3s software while the existing appliance installation is still running. Please ensure that the host has at least 1GB of memory available in addition to its current usage to cover for the overhead.
-
The new Gradle Enterprise distribution mechanism has a new license file format. Please contact Gradle support to get an updated license file.
-
Airgap installations require a specific license entitlement. If this is a requirement, please contact your customer success representative.
Migration steps
Update to the latest Gradle Enterprise version
Upgrade to the latest version by clicking on the Check Now button and installing any updates found. This will ensure that the migration is from and to the same Gradle Enterprise version.

Upload required files to the host
Upload the following files to the Gradle Enterprise host:
-
Your new Gradle Enterprise license file.
-
Any SSL certificates being used.
Install K3s and helm
Please follow the instructions on installing K3s and Helm in the installation manual.
Create a values.yaml configuration file
Helm is configured using a combination of settings stored in a YAML file and standalone files such as the Gradle Enterprise license and SSL certificates.
Please review the Helm configuration section from the installation manual for details. We recommend to start with the values.yaml
template file included in the helm distribution. See here for instructions how to retrieve it.
This section walks through translating the existing Replicated appliance configuration into a Helm values.yaml
.
Create the values.yaml
file, and populate it based on the following settings in the Replicated Settings page.
Network section
Translate the existing settings to the values.yaml
file:
Replicated setting | Helm configuration key |
---|---|
Hostname |
Set |
Use HTTP / Use HTTPS |
Set |
Use HTTP with external HTTPS termination |
Set |
HTTP port / HTTPS port |
Set |
SSL Private Key / SSL Certificate |
Set |
Examples:
-
Using HTTP with the default port
global: hostname: ge.example.com ingress: ssl: enabled: false
-
Using HTTP with a custom port
global: hostname: ge.example.com ingress: port: http: 8180 ssl: enabled: false
-
Using HTTPS with a generated certificate and default ports
global: hostname: ge.example.com
-
Using HTTPS with a generated certificate and custom ports
global: hostname: ge.example.com ingress: port: http: 8180 https: 8543
-
Using HTTPS with custom certificate and ports
global: hostname: ge.example.com ingress: ssl: port: http: 8180 https: 8543 key: | -----BEGIN RSA PRIVATE KEY----- MIIEpQIBAAKCAQEA4qV8JlqDMi7y85Ykq8dn7uIsi609D6KuFtlc+UvNYjatz0+u QzIr3iw//qf7sM8nx8fhGwuWvUWeCE6zbgKjuxDH82J9NQ0ctf70n0qVTeyW1CKR w/koEXyecIZIOA9Jh7KNkShfp/x5T3GZ4QK//A/4oJyhD3IeK/nEXr5mSe2AzGxq ... XlOfXr/xvkXA66PROgvVxfwpN/GNrLXFi1HvMg7MVZJUZQpNzpAzw5JTk2MbawOl G7tI0qQ6F20e5R4tPpEDKCFZykyvgGMhfLzsvVlrgaVW8QbVK4YWNtQ= -----END RSA PRIVATE KEY----- cert: | -----BEGIN CERTIFICATE----- MIIDKjCCAhKgAwIBAgIRAPNTIHf6/oUuzMKm3ffGNOgwDQYJKoZIhvcNAQELBQAw HDEaMBgGA1UEAxMRYXV0by1nZW5lcmF0ZWQtY2EwHhcNMjExMTMwMTU1NDU5WhcN MjExMjAxMTU1NDU5WjAjMSEwHwYDVQQDExhvbmx5LWZvci51bml0LXRlc3QubG9j ... Cn/3yUirFVTslrSYKAemLw8btLO6FDF9dc/lq1o7tKsYVuhEcjqnTah7puJjEN9h z+P5RmRxU/kaaFB+Vuw1pRezbaAtZNorVgXnBwrdseY4zLGyhAcGcR9v+VtCiQ== -----END CERTIFICATE-----
Alternatively, the key and certificate can be provided to the
helm
command via--set-file
parameters. See the installation manual for details. -
Using HTTP with external HTTPS termination and custom ports
global: hostname: ge.example.com externalSSLTermination: true ingress: ssl: enabled: false port: http: 8180 https: 8543
Storage section
Replicated setting | Helm configuration key |
---|---|
Installation directory |
Set |
Logs directory |
Set |
Backup directory |
Set |
Examples:
-
Defaults
# Default configuration. No values required.
-
Custom locations
global: storage: directory: /mnt/big-volume/ge logs: directory: /var/log/gradle-enterprise backup: directory: /mnt/vol2/ge-backups
Database section
By default, Gradle Enterprise will use an embedded database. Configuration settings only need to be set when connecting to a user-managed database.
Please review the Database configuration section of the installation manual for details. Different values are required based on which type of credentials are provided.
Replicated setting | Helm configuration key |
---|---|
Store data in user-managed database |
Set |
Host |
Set |
Port |
Set |
Database name |
Set |
Extra JDBC parameters |
Set |
Database superuser username |
Set |
Database superuser password |
Set |
Database application user password |
Set |
Database migration user password |
Set |
Examples:
-
Store data in embedded database
# Default configuration. No values required.
-
Store data in user-managed database and provide database superuser credentials
database: location: user-managed connection: host: database.example.com port: 5432 databaseName: gradle_enterprise params: "?connectTimeout=60" credentials: superuser: username: postgres password: superuserPassword
-
Store data in user-managed database and do not provide database superuser credentials
database: location: user-managed connection: host: database.example.com port: 5432 databaseName: gradle_enterprise params: "?connectTimeout=60" credentials: app: password: appUserPassword migrator: password: migratorUserPassword
Airgap installations
Airgap installation requires downloading a Gradle Enterprise airgap bundle on an internet-connected host and then transferring it to the installation host.
Airgap installations should add the below image pull policy to prevent the app from trying to pull Gradle Enterprise container images from the internet at runtime:
global:
image:
imagePullPolicy: Never
Chart and image download
Installation steps are slightly different, depending on whether an online or airgap installation is being performed.
Online installation chart download
Add the Gradle Helm repository:
helm repo add gradle https://helm.gradle.com
helm repo update gradle
Verify that Helm has the latest Gradle Enterprise standalone chart:
helm search repo gradle-enterprise-standalone
You should see the latest available:
NAME CHART VERSION APP VERSION DESCRIPTION
gradle/gradle-enterprise-standalone 2022.3.0 2022.3 Official Gradle Enterprise Chart
Verify that this is the same version as is installed in the existing installation. If it is not, then either the existing installation needs to be upgraded or the local Helm repository cache should be updated again by running helm repo update gradle
.
Airgap installation chart and image download
Verify that your license is airgap-enabled. If you examine the license file content, you should see airgap
listed as an entitlement. If you need to perform an airgap installation but do not have the airgap
entitlement on your license, please contact your customer success representative.
On an internet connected host, with your Gradle Enterprise license file available:
-
Download the airgap bundle for the version that you are installing:
curl -LOJd @/path/to/gradle-enterprise.license https://registry.gradle.com/airgap/gradle-enterprise-standalone-2022.3-bundle.tar.gz
You can optionally verify the downloaded bundle file.
-
Transfer the downloaded bundle file to your installation host.
On the installation host:
-
Expand the bundle:
tar zxvf gradle-enterprise-standalone-2022.3-bundle.tar.gz
-
Run the following command to import images into K3s:
k3s ctr images import gradle-enterprise-standalone-2022.3-images.tar
Stop the existing instance
At this point, expect Gradle Enterprise to be unavailable for up to 30 minutes.
-
Click the Stop now button in the Replicated console
-
Wait for the application to be completely stopped
Install the Gradle Enterprise standalone Helm chart
Online installation
Install Gradle Enterprise by issuing the following command:
helm install \
--create-namespace --namespace gradle-enterprise \
ge gradle/gradle-enterprise-standalone \
--values /path/to/values.yaml \
--set-file global.license.file=/path/to/gradle-enterprise.license \
# [other options] (1)
1 | Further options:
|
Airgap installation
helm install \
--create-namespace --namespace gradle-enterprise \
ge gradle-enterprise-standalone-2022.3.0.tgz \(1)
--values /path/to/values.yaml \
--set-file global.license.file=/path/to/gradle-enterprise.license \
# [other options] (2)
1 | This is the path to the .tgz Helm chart file included in the downloaded airgap bundle. |
2 | Further options:
|
Verify system status
Gradle Enterprise service availability
You can inspect the status of the Gradle Enterprise pods by running kubectl get pods
:
kubectl --namespace gradle-enterprise get pods
NAME READY STATUS RESTARTS AGE
gradle-enterprise-operator-76694c949d-md5dh 1/1 Running 0 84m
gradle-proxy-0 1/1 Running 0 83m
gradle-database-65d975cf8-dk7kw 2/2 Running 0 83m
gradle-enterprise-app-0 1/1 Running 0 83m
gradle-metrics-cfcd8f7f7-zqds9 1/1 Running 0 83m
gradle-test-distribution-broker-6fd84c6988-x6jvw 1/1 Running 0 83m
gradle-build-cache-node-57b9bdd46d-2txf5 1/1 Running 0 84m
gradle-keycloak-0 1/1 Running 0 83m
The app will be ready once all pods report as Running
.
Service connectivity verification
Please verify that your system is being connected-to correctly. Which services to check will depend on which you use:
-
If authentication is required, can users log in?
-
Are build scans being collected correctly? See
/scans
. -
Are build cache nodes connected? See
/cache-admin
. -
Are test distribution agents connected?
/admin/test-distribution
.
Data verification
Please inspect your system to validate that historical data has been migrated. Viewing /scans
and ordering by oldest build scan will show the oldest scans in your system.
Support
If any steps do not result in the expected state, please contact Gradle support.
Cleanup
Once you have verified that your system is functional and has migrated configuration and data correctly, you may uninstall previously installed components at your convenience.
-
Uninstall Replicated. It is important to do this prior to a system restart as otherwise Replicated may attempt to start the old installation of Gradle Enterprise.
-
Docker is no longer needed, and may also be uninstalled.
Ship-based Kubernetes to Helm-based Kubernetes cluster migration
Prior to starting, please review the Gradle Enterprise Helm Kubernetes Installation Manual which explains Helm and the Gradle Enterprise distribution.
Prerequisites
-
The new Gradle Enterprise distribution mechanism has a new license file format. Please contact Gradle support to get an updated license file.
-
Typically the previous Ship-based Gradle Enterprise installation steps will have been executed on a host with access to your Kubernetes cluster. This migration guide assumes that this host is available for execution of commands, and that the previously created
gradle-enterprise
directory containing installation and support scripts is present. References to "the host" in this guide refer to this host. -
You will need your current Ship customer ID and installation ID. Please contact Gradle Support if you do not have these recorded.
-
These instructions assume that only one Gradle Enterprise instance is installed in your Kubernetes cluster. For assistance in migrating an instance which shares a Kubernetes cluster with other instances, please contact Gradle Support.
-
In particular, review the installation options in the installation manual and know the installation method and required steps prior to starting steps in this guide. You should know the shape of the
helm install
command prior to starting.
Migration steps
Update to the latest Gradle Enterprise version
Upgrade to the latest version by following the guidelines in Gradle Enterprise Kubernetes Administration Manual. This will ensure that the migration is from and to the same Gradle Enterprise version.
Upload required files to the host
Upload the following files to the host:
-
Your new Gradle Enterprise license file.
-
Any SSL certificates being used.
Install Helm
Please follow the instructions on installing Helm in the installation manual.
Run the Ship app to review current settings
To view the current system configuration, first run the Ship app. It should be run in the gradle-enterprise
directory created during the previous installation.
cd path/to/gradle-enterprise
docker run -p 8800:8800 --rm -it -v `pwd`:/out \
-v /var/run/docker.sock:/var/run/docker.sock \
replicated/ship:0.54.1 app \
--customer-id=<cust-id> \
--installation-id=<install-id>
This should show the app starting followed by some lines like this:
Please visit the following URL in your browser to continue the installation http://localhost:8800
Visit that port on the hostname of your installation host in your web browser:

The current configuration should be visible. This can be used as a reference when creating a Helm configuration file below.
Create a values.yaml configuration file
Helm is configured using a combination of settings stored in a YAML file and standalone files such as the Gradle Enterprise license and SSL certificates.
Please review the Helm configuration section from the installation manual for details.
This section walks through translating the existing Replicated ship configuration into a Helm values.yaml
.
Create the values.yaml
file, and populate it based on the following settings from the Ship application settings screen.
Cluster info section
Translate the existing settings to the values.yaml
file:
Replicated setting | Helm configuration key |
---|---|
Kubernetes namespace |
Specified as a part of helm install command. Check the installation manual for details. |
Installation on Openshift platform |
Set |
Airgap cluster |
See |
Examples:
-
Defaults
# Default configuration. No values required.
-
Openshift
global: openshiftInstallation: true
-
Airgap
See the docker registry settings below.
Docker registry settings section
Replicated setting | Helm configuration key |
---|---|
Docker registry address |
Set |
Registry is a mirror |
Nothing to set in Helm config. You will need to set up your mirror with appropriate credentials to pull images from |
Registry requires authentication |
Set |
Examples:
-
Airgap registry setup without credentials
global: image: registry: registry.example.com/gradle-enterprise
-
Airgap registry setup with credentials
global: image: registry: registry.example.com/gradle-enterprise imagePullSecret: example-image-pull-secret-name
Network section
Please review the section on exposing Gradle Enterprise outside your cluster in the installation manual. Existing Ship Kubernetes installations will already be routing traffic to the application’s gradle-proxy
service in some way. This guide assumes that this will continue and attempts to configure the proxy to accept traffic in the same way.
Replicated setting | Helm configuration key |
---|---|
Hostname |
Set |
Use HTTP / Use HTTPS |
Set |
Use HTTP with external HTTPS termination |
Set |
SSL Private Key / SSL Certificate |
Set |
Examples:
-
Using HTTP with the default port
global: hostname: ge.example.com
-
Using HTTPS with a custom certificate
global: hostname: ge.example.com proxy: ssl: enabled: true key: | -----BEGIN RSA PRIVATE KEY----- MIIEpQIBAAKCAQEA4qV8JlqDMi7y85Ykq8dn7uIsi609D6KuFtlc+UvNYjatz0+u QzIr3iw//qf7sM8nx8fhGwuWvUWeCE6zbgKjuxDH82J9NQ0ctf70n0qVTeyW1CKR w/koEXyecIZIOA9Jh7KNkShfp/x5T3GZ4QK//A/4oJyhD3IeK/nEXr5mSe2AzGxq ... XlOfXr/xvkXA66PROgvVxfwpN/GNrLXFi1HvMg7MVZJUZQpNzpAzw5JTk2MbawOl G7tI0qQ6F20e5R4tPpEDKCFZykyvgGMhfLzsvVlrgaVW8QbVK4YWNtQ= -----END RSA PRIVATE KEY----- cert: | -----BEGIN CERTIFICATE----- MIIDKjCCAhKgAwIBAgIRAPNTIHf6/oUuzMKm3ffGNOgwDQYJKoZIhvcNAQELBQAw HDEaMBgGA1UEAxMRYXV0by1nZW5lcmF0ZWQtY2EwHhcNMjExMTMwMTU1NDU5WhcN MjExMjAxMTU1NDU5WjAjMSEwHwYDVQQDExhvbmx5LWZvci51bml0LXRlc3QubG9j ... Cn/3yUirFVTslrSYKAemLw8btLO6FDF9dc/lq1o7tKsYVuhEcjqnTah7puJjEN9h z+P5RmRxU/kaaFB+Vuw1pRezbaAtZNorVgXnBwrdseY4zLGyhAcGcR9v+VtCiQ== -----END CERTIFICATE-----
Alternatively, the key and certificate can be provided to the
helm
command via--set-file
parameters. See the installation manual for details. -
Using HTTP with external HTTPS termination
global: hostname: ge.example.com externalSSLTermination: true
Storage section
To ensure that your data is preserved when performing migration steps below, it is important that exactly the same storage class and capacities are used.
Replicated setting | Helm configuration key |
---|---|
Storage class |
Set all of |
Build scans storage capacity |
Set |
Build scans backups storage capacity |
Set |
Build cache storage capacity |
Set |
Test Distribution file cache storage capacity |
Set |
Example:

global:
storage:
data:
class: some-provisioned-io-storage-class
backup:
class: some-provisioned-io-storage-class
logs:
class: some-provisioned-io-storage-class
database:
storage:
data:
capacity: 500Gi
backup:
capacity: 500Gi
buildCacheNode:
storage:
data:
capacity: 50Gi
testDistribution:
storage:
data:
capacity: 30Gi
Horizontal scaling section
Replicated setting | Helm configuration key |
---|---|
Number of replicas |
Set |
Examples:
-
Horizontal scaling disabled
# Default configuration. No values required.
-
Horizontal scaling enabled
global: scaling: replicas: 2
Database section
By default, Gradle Enterprise will use an embedded database. Configuration settings only need to be set when connecting to a user-managed database.
Please review the Database configuration section of the installation manual for details. Different values are required based on which type of credentials are provided.
Replicated setting | Helm configuration key |
---|---|
Store data in user-managed database |
Set |
Host |
Set |
Port |
Set |
Database name |
Set |
Extra JDBC parameters |
Set |
Database superuser username |
Set |
Database superuser password |
Set |
Database application user password |
Set |
Database migration user password |
Set |
Examples:
-
Store data in embedded database
# Default configuration. No values required.
-
Store data in user-managed database and provide database superuser credentials directly
database: location: user-managed connection: host: database.example.com port: 5432 databaseName: gradle_enterprise params: "?connectTimeout=60" credentials: superuser: username: postgres password: superuserPassword
-
Store data in user-managed database and provide database superuser credentials as ConfigMap/Secret
database: location: user-managed connection: configMapName: my-example-db-connection-details credentials: superuser: secretName: my-example-db-superuser-credentials
-
Store data in user-managed database and do not provide database superuser credentials (direct values)
database: location: user-managed connection: ... credentials: app: password: app_password migrator: password: migrator_password
-
Store data in user-managed database and do not provide database superuser credentials (secrets)
database: location: user-managed connection: ... credentials: app: secretName: my-example-db-application-credentials migrator: secretName: my-example-db-migrator-credentials
Terminate the Ship app
Once your values.yaml
has been populated from the current settings, you may close the browser window and terminate the Ship app process by issuing a CTRL-C
in the terminal in which it is running.
Verify that all persistent volumes used by existing app have Retain
reclaim policy.
kubectl get pv | grep " gradle-enterprise/"
The output should look something like this:
NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE pvc-4367dd37-233c-43f5-998a-0b6f979626cb 200Mi RWO Delete Bound gradle-enterprise/gradle-test-distribution-logs-volume local-path 76m pvc-49421860-1100-4b8e-8ac6-8711343e1628 200Mi RWO Delete Bound gradle-enterprise/gradle-database-logs-volume local-path 76m pvc-ed0a52c5-a7a4-4c93-b2a8-3a190f866db7 200Mi RWO Delete Bound gradle-enterprise/logs-gradle-keycloak-0 local-path 76m pvc-c0d91c7b-4f3e-41e1-a379-1673b07f4408 10Gi RWO Delete Bound gradle-enterprise/gradle-database-backups-volume local-path 76m pvc-f92182bc-8d44-4c41-82e5-3719c1226444 200Mi RWO Delete Bound gradle-enterprise/gradle-metrics-volume local-path 76m pvc-71fc04d0-b395-43b3-89be-9fbcb55c9301 10Gi RWO Delete Bound gradle-enterprise/gradle-database-volume local-path 76m pvc-c1f84161-8cc6-4c41-ac5a-c78b3c2dfd41 10Gi RWO Delete Bound gradle-enterprise/gradle-build-cache-volume local-path 76m pvc-537be141-4be6-4e34-8c1a-d6b161e06ede 200Mi RWO Delete Bound gradle-enterprise/gradle-build-cache-node-logs-volume local-path 76m pvc-b6eadedf-eddd-460f-9b67-f852559a9627 200Mi RWO Delete Bound gradle-enterprise/logs-gradle-enterprise-app-0 local-path 75m pvc-f46ad5b2-1f2e-429d-88da-88cd33689c16 500Mi RWO Delete Bound gradle-enterprise/logs-gradle-proxy-0 local-path 75m pvc-2ca92343-2bc9-4946-94f2-de7ca7243284 200Mi RWO Delete Bound gradle-enterprise/gradle-enterprise-operator-logs-volume local-path 75m pvc-d712f0de-324f-43c0-8508-96d5de148f68 10Gi RWO Delete Bound gradle-enterprise/gradle-test-distribution-broker-file-cache-volume local-path 75m
If any have a Delete
reclaim policy, it is very likely that data will be lost during the upgrade process.
Please review the Kubernetes documentation to understand the difference between Delete
and Retain
policies, and to see commands to update the policy.
The following steps can be used to update the reclaim policy:
-
All Gradle Enterprise persistent volume claim names start with
gradle-enterprise/
. If there are volume claim names that do not match the names shown in the output above, please contact Gradle Support so ensure that you do not accidentally change the policy for an incorrect persistent volume. -
Run the following command to update the reclaim policy of matching volumes:
kubectl get pv \ | grep " gradle-enterprise/" \ | awk '{print $1}' \ | while read v ; do kubectl patch pv $v -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' ; done
You should see output like this:
persistentvolume/pvc-ed0a52c5-a7a4-4c93-b2a8-3a190f866db7 patched persistentvolume/pvc-b6eadedf-eddd-460f-9b67-f852559a9627 patched persistentvolume/pvc-f46ad5b2-1f2e-429d-88da-88cd33689c16 patched persistentvolume/pvc-49421860-1100-4b8e-8ac6-8711343e1628 patched persistentvolume/pvc-c0d91c7b-4f3e-41e1-a379-1673b07f4408 patched persistentvolume/pvc-f92182bc-8d44-4c41-82e5-3719c1226444 patched persistentvolume/pvc-71fc04d0-b395-43b3-89be-9fbcb55c9301 patched persistentvolume/pvc-c1f84161-8cc6-4c41-ac5a-c78b3c2dfd41 patched persistentvolume/pvc-537be141-4be6-4e34-8c1a-d6b161e06ede patched persistentvolume/pvc-2ca92343-2bc9-4946-94f2-de7ca7243284 patched persistentvolume/pvc-d712f0de-324f-43c0-8508-96d5de148f68 patched persistentvolume/pvc-4367dd37-233c-43f5-998a-0b6f979626cb patched
Rechecking the volume states should show that they all have a Retain
policy:
kubectl get pv | grep " gradle-enterprise/"
pvc-1da2bfc4-41f8-469a-a8e5-bd4544f42a2a 10Gi RWO Retain Bound gradle-enterprise/gradle-database-volume local-path 13m pvc-8e13739c-f445-4537-acfb-27cb6f0cea54 200Mi RWO Retain Bound gradle-enterprise/logs-gradle-keycloak-0 local-path 13m pvc-36ce81f7-1e74-407a-84cc-41678bd802d9 200Mi RWO Retain Bound gradle-enterprise/gradle-database-logs-volume local-path 13m pvc-a004b6d8-94e8-4f9d-9c4c-77f0a67a6015 10Gi RWO Retain Bound gradle-enterprise/gradle-test-distribution-broker-file-cache-volume local-path 13m pvc-0a0e05f1-d8aa-4407-b66a-3d7f275c7000 200Mi RWO Retain Bound gradle-enterprise/logs-gradle-enterprise-app-0 local-path 13m pvc-8df76bb3-7132-4ff9-88d8-27ebce374508 200Mi RWO Retain Bound gradle-enterprise/gradle-test-distribution-logs-volume local-path 13m pvc-83750521-8b28-45c9-9860-ade8add0e08b 500Mi RWO Retain Bound gradle-enterprise/logs-gradle-proxy-0 local-path 13m pvc-c6d74ff6-f8c9-4366-b07a-ca86c8c48a3f 200Mi RWO Retain Bound gradle-enterprise/gradle-metrics-volume local-path 13m pvc-342ba3e8-5646-4b71-8c90-cfa92c50e41f 10Gi RWO Retain Bound gradle-enterprise/gradle-database-backups-volume local-path 13m pvc-6eb4b99e-32db-4ef5-bc5c-e653e63d1098 200Mi RWO Retain Bound gradle-enterprise/gradle-build-cache-node-logs-volume local-path 13m pvc-6f2df0c5-4e8e-48b3-8896-3983b665b9e3 200Mi RWO Retain Bound gradle-enterprise/gradle-enterprise-operator-logs-volume local-path 13m pvc-aeb436f9-c084-4b41-83a2-050e3a062661 10Gi RWO Retain Bound gradle-enterprise/gradle-build-cache-volume local-path 13m
Chart and image download
Installation steps are slightly different, depending on whether an online or airgap installation is being performed.
Online installation chart download
On your installation host, add the Gradle Helm repository:
helm repo add gradle https://helm.gradle.com
helm repo update gradle
Verify that Helm has the latest Gradle Enterprise chart:
helm search repo gradle-enterprise
You should see the latest available:
NAME CHART VERSION APP VERSION DESCRIPTION
gradle/gradle-enterprise 2022.3.0 2022.3 Official Gradle Enterprise Chart
Verify that this is the same version as is installed in the existing installation. If it is not, then either the existing installation needs to be upgraded or the local Helm repository cache should be updated again by running helm repo update gradle
.
Airgap installation chart and image download
Verify that your license is airgap-enabled. If you examine the license file content, you should see airgap
listed as an entitlement. If you need to perform an airgap installation but do not have the airgap
entitlement on your license, please contact your customer success representative.
On an internet connected host, with your Gradle Enterprise license file available:
-
Download the airgap bundle for the version that you are installing:
curl -LOJd @/path/to/gradle-enterprise.license https://registry.gradle.com/airgap/gradle-enterprise-2022.3-bundle.tar.gz
You can optionally verify the downloaded bundle file.
-
Transfer the downloaded bundle file to your installation host, if the above was run on a different host.
On the installation host:
-
Expand the bundle:
tar zxvf gradle-enterprise-2022.3-bundle.tar.gz
-
Run the following command to upload images to your internal container registry. You must be logged in to the registry prior to running the command. The
upload-images.sh
script is included in the airgap bundle and extracted in the step above../upload-images.sh --registry=registry.example.com/gradle-enterprise
Uninstall the existing installation
At this point, expect Gradle Enterprise to be unavailable for up to 30 minutes. |
The uninstall script does not remove persistent volumes, and those set to a Retain
policy above will remain available until the new installation picks them up.
Run the uninstall script for the current installation:
# from the previously-created grade-enterprise directory
./installer/scripts/uninstall.sh
In addition, some extra persistent volume claims may need to be deleted. Check if any are left (subsequent commands assume the application is installed in the gradle-enterprise
namespace - please adjust to your setup):
kubectl -n gradle-enterprise get pvc
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE logs-gradle-keycloak-0 Bound pvc-8e13739c-f445-4537-acfb-27cb6f0cea54 200Mi RWO local-path 23m logs-gradle-enterprise-app-0 Bound pvc-0a0e05f1-d8aa-4407-b66a-3d7f275c7000 200Mi RWO local-path 23m logs-gradle-proxy-0 Bound pvc-83750521-8b28-45c9-9860-ade8add0e08b 500Mi RWO local-path 23m
If any are left, remove them by executing the following command:
kubectl -n gradle-enterprise delete pvc \
$(kubectl -n gradle-enterprise get pvc -o jsonpath='{.items[*].metadata.name}')
persistentvolumeclaim "logs-gradle-keycloak-0" deleted persistentvolumeclaim "logs-gradle-enterprise-app-0" deleted persistentvolumeclaim "logs-gradle-proxy-0" deleted
Make all persistent volumes available
At this point, all persistent volumes should be marked as Released
. To confirm:
kubectl get pv | grep " gradle-enterprise/"
pvc-1da2bfc4-41f8-469a-a8e5-bd4544f42a2a 10Gi RWO Retain Released gradle-enterprise/gradle-database-volume local-path 27m pvc-342ba3e8-5646-4b71-8c90-cfa92c50e41f 10Gi RWO Retain Released gradle-enterprise/gradle-database-backups-volume local-path 27m pvc-36ce81f7-1e74-407a-84cc-41678bd802d9 200Mi RWO Retain Released gradle-enterprise/gradle-database-logs-volume local-path 27m pvc-aeb436f9-c084-4b41-83a2-050e3a062661 10Gi RWO Retain Released gradle-enterprise/gradle-build-cache-volume local-path 27m pvc-6eb4b99e-32db-4ef5-bc5c-e653e63d1098 200Mi RWO Retain Released gradle-enterprise/gradle-build-cache-node-logs-volume local-path 27m pvc-a004b6d8-94e8-4f9d-9c4c-77f0a67a6015 10Gi RWO Retain Released gradle-enterprise/gradle-test-distribution-broker-file-cache-volume local-path 27m pvc-8df76bb3-7132-4ff9-88d8-27ebce374508 200Mi RWO Retain Released gradle-enterprise/gradle-test-distribution-logs-volume local-path 27m pvc-6f2df0c5-4e8e-48b3-8896-3983b665b9e3 200Mi RWO Retain Released gradle-enterprise/gradle-enterprise-operator-logs-volume local-path 27m pvc-c6d74ff6-f8c9-4366-b07a-ca86c8c48a3f 200Mi RWO Retain Released gradle-enterprise/gradle-metrics-volume local-path 27m pvc-8e13739c-f445-4537-acfb-27cb6f0cea54 200Mi RWO Retain Released gradle-enterprise/logs-gradle-keycloak-0 local-path 27m pvc-0a0e05f1-d8aa-4407-b66a-3d7f275c7000 200Mi RWO Retain Released gradle-enterprise/logs-gradle-enterprise-app-0 local-path 27m pvc-83750521-8b28-45c9-9860-ade8add0e08b 500Mi RWO Retain Released gradle-enterprise/logs-gradle-proxy-0 local-path 27m
To make these available for the new installation to pick up, run the following command
kubectl get pv \
| grep " gradle-enterprise/" \
| awk '{print $1}' \
| while read v ; do kubectl patch pv $v --type json -p '[{"op": "remove", "path": "/spec/claimRef/uid"}]' ; done
persistentvolume/pvc-1da2bfc4-41f8-469a-a8e5-bd4544f42a2a patched persistentvolume/pvc-342ba3e8-5646-4b71-8c90-cfa92c50e41f patched persistentvolume/pvc-36ce81f7-1e74-407a-84cc-41678bd802d9 patched persistentvolume/pvc-aeb436f9-c084-4b41-83a2-050e3a062661 patched persistentvolume/pvc-6eb4b99e-32db-4ef5-bc5c-e653e63d1098 patched persistentvolume/pvc-a004b6d8-94e8-4f9d-9c4c-77f0a67a6015 patched persistentvolume/pvc-8df76bb3-7132-4ff9-88d8-27ebce374508 patched persistentvolume/pvc-6f2df0c5-4e8e-48b3-8896-3983b665b9e3 patched persistentvolume/pvc-c6d74ff6-f8c9-4366-b07a-ca86c8c48a3f patched persistentvolume/pvc-8e13739c-f445-4537-acfb-27cb6f0cea54 patched persistentvolume/pvc-0a0e05f1-d8aa-4407-b66a-3d7f275c7000 patched persistentvolume/pvc-83750521-8b28-45c9-9860-ade8add0e08b patched
Now all persistent volumes should report as being Available
:
kubectl get pv | grep " gradle-enterprise/"
pvc-1da2bfc4-41f8-469a-a8e5-bd4544f42a2a 10Gi RWO Retain Available gradle-enterprise/gradle-database-volume local-path 32m pvc-342ba3e8-5646-4b71-8c90-cfa92c50e41f 10Gi RWO Retain Available gradle-enterprise/gradle-database-backups-volume local-path 32m pvc-36ce81f7-1e74-407a-84cc-41678bd802d9 200Mi RWO Retain Available gradle-enterprise/gradle-database-logs-volume local-path 32m pvc-aeb436f9-c084-4b41-83a2-050e3a062661 10Gi RWO Retain Available gradle-enterprise/gradle-build-cache-volume local-path 32m pvc-6eb4b99e-32db-4ef5-bc5c-e653e63d1098 200Mi RWO Retain Available gradle-enterprise/gradle-build-cache-node-logs-volume local-path 32m pvc-a004b6d8-94e8-4f9d-9c4c-77f0a67a6015 10Gi RWO Retain Available gradle-enterprise/gradle-test-distribution-broker-file-cache-volume local-path 32m pvc-8df76bb3-7132-4ff9-88d8-27ebce374508 200Mi RWO Retain Available gradle-enterprise/gradle-test-distribution-logs-volume local-path 32m pvc-6f2df0c5-4e8e-48b3-8896-3983b665b9e3 200Mi RWO Retain Available gradle-enterprise/gradle-enterprise-operator-logs-volume local-path 32m pvc-c6d74ff6-f8c9-4366-b07a-ca86c8c48a3f 200Mi RWO Retain Available gradle-enterprise/gradle-metrics-volume local-path 32m pvc-8e13739c-f445-4537-acfb-27cb6f0cea54 200Mi RWO Retain Available gradle-enterprise/logs-gradle-keycloak-0 local-path 32m pvc-0a0e05f1-d8aa-4407-b66a-3d7f275c7000 200Mi RWO Retain Available gradle-enterprise/logs-gradle-enterprise-app-0 local-path 32m pvc-83750521-8b28-45c9-9860-ade8add0e08b 500Mi RWO Retain Available gradle-enterprise/logs-gradle-proxy-0 local-path 32m
Install Helm-based Gradle Enterprise version
Follow the guidelines in installation manual and install Gradle Enterprise using Helm.
An example set of steps are shown below, assuming a direct install without extracting the Helm chart.
Online installation
Install Gradle Enterprise by issuing the following command:
helm install \
--create-namespace --namespace gradle-enterprise \
ge gradle/gradle-enterprise \
--values /path/to/values.yaml \
--set-file global.license.file=/path/to/gradle-enterprise.license \
# [other options] (1)
1 | Further options:
|
Airgap installation
helm install \
--create-namespace --namespace gradle-enterprise \
ge gradle-enterprise-2022.3.0.tgz \(1)
--values /path/to/values.yaml \
--set-file global.license.file=/path/to/gradle-enterprise.license \
# [other options] (2)
1 | This is the path to the .tgz Helm chart file included in the downloaded airgap bundle. |
2 | Further options:
|
Verify system status
Persistent volume binding
Checking the persistent volumes should show them all bound again:
kubectl get pv | grep " gradle-enterprise/"
pvc-a004b6d8-94e8-4f9d-9c4c-77f0a67a6015 10Gi RWO Retain Bound gradle-enterprise/gradle-test-distribution-broker-file-cache-volume local-path 57m pvc-342ba3e8-5646-4b71-8c90-cfa92c50e41f 10Gi RWO Retain Bound gradle-enterprise/gradle-database-backups-volume local-path 57m pvc-c6d74ff6-f8c9-4366-b07a-ca86c8c48a3f 200Mi RWO Retain Bound gradle-enterprise/gradle-metrics-volume local-path 57m pvc-6eb4b99e-32db-4ef5-bc5c-e653e63d1098 200Mi RWO Retain Bound gradle-enterprise/gradle-build-cache-node-logs-volume local-path 56m pvc-36ce81f7-1e74-407a-84cc-41678bd802d9 200Mi RWO Retain Bound gradle-enterprise/gradle-database-logs-volume local-path 57m pvc-aeb436f9-c084-4b41-83a2-050e3a062661 10Gi RWO Retain Bound gradle-enterprise/gradle-build-cache-volume local-path 56m pvc-1da2bfc4-41f8-469a-a8e5-bd4544f42a2a 10Gi RWO Retain Bound gradle-enterprise/gradle-database-volume local-path 57m pvc-6f2df0c5-4e8e-48b3-8896-3983b665b9e3 200Mi RWO Retain Bound gradle-enterprise/gradle-enterprise-operator-logs-volume local-path 56m pvc-8df76bb3-7132-4ff9-88d8-27ebce374508 200Mi RWO Retain Bound gradle-enterprise/gradle-test-distribution-logs-volume local-path 57m pvc-83750521-8b28-45c9-9860-ade8add0e08b 500Mi RWO Retain Bound gradle-enterprise/logs-gradle-proxy-0 local-path 57m pvc-0a0e05f1-d8aa-4407-b66a-3d7f275c7000 200Mi RWO Retain Bound gradle-enterprise/logs-gradle-enterprise-app-0 local-path 57m pvc-8e13739c-f445-4537-acfb-27cb6f0cea54 200Mi RWO Retain Bound gradle-enterprise/logs-gradle-keycloak-0 local-path 57m
Gradle Enterprise service availability
You can inspect the status of the Gradle Enterprise pods by running kubectl get pods
:
kubectl --namespace gradle-enterprise get pods
NAME READY STATUS RESTARTS AGE
gradle-enterprise-operator-5646785cc5-hk7br 1/1 Running 0 8m39s
gradle-database-5946778f79-5nfbf 2/2 Running 0 8m39s
gradle-proxy-0 1/1 Running 0 8m39s
gradle-metrics-7478b7875b-vp7j9 1/1 Running 0 8m39s
gradle-enterprise-app-0 1/1 Running 0 8m39s
gradle-build-cache-node-7bcb768f55-hb7zv 1/1 Running 0 8m39s
gradle-test-distribution-broker-5698459b8-z9skv 1/1 Running 0 8m39s
gradle-keycloak-0 1/1 Running 0 8m39s
The app will be ready once all pods report as Running
.
Service connectivity verification
Please verify that your system is being connected-to correctly. Which services to check will depend on which you use:
-
If authentication is required, can users log in?
-
Are build scans being collected correctly? See
/scans
. -
Are build cache nodes connected? See
/cache-admin
. -
Are test distribution agents connected?
/admin/test-distribution
.
Data verification
Please inspect your system to validate that historical data has been migrated. Viewing /scans
and ordering by oldest build scan will show the oldest scans in your system.
Support
If any steps do not result in the expected state, please contact Gradle support.
Appendix A: Unattended installation
If you are configuring Gradle Enterprise using an Unattended installation file, you must add additional parameters to the helm install
commands above:
--set-file=global.unattended.configuration=/path/to/unattended.yaml
--set-file=global.unattended.key=/path/to/unattended.key
Appendix B: Contacting support
Contact Gradle support by creating a support ticket at support.gradle.com, including:
-
Details of the type of migration
-
The version being migrated from/to
-
Steps taken so far
-
Errors or unexpected behavior
Appendix C: Verifying the airgap bundle
You can verify the downloaded file by downloading a SHA256 checksum and using the sha256sum
utility to verify the bundle file:
curl -LOJd @/path/to/gradle-enterprise.license https://registry.gradle.com/airgap/gradle-enterprise-2022.3-bundle.tar.gz.sha256
sha256sum -c gradle-enterprise-2022.3-bundle.tar.gz.sha256
or, for the standalone bundle:
curl -LOJd @/path/to/gradle-enterprise.license https://registry.gradle.com/airgap/gradle-enterprise-standalone-2022.3-bundle.tar.gz.sha256
sha256sum -c gradle-enterprise-standalone-2022.3-bundle.tar.gz.sha256