This manual covers the installation and operation of Gradle Enterprise into an existing Kubernetes cluster.

This approach to operating Gradle Enterprise is only relevant if you are already operating a Kubernetes cluster. If you are not operating a Kubernetes cluster, you can alternatively install the Gradle Enterprise appliance.

How it works

There are two steps to deploying Gradle Enterprise to a Kubernetes cluster:

  1. Running the Gradle Enterprise installer to produce an installation shell script, tailored to your environment

  2. Executing the installation shell script to install Gradle Enterprise onto your Kubernetes cluster

The Gradle Enterprise installer is a locally run web application, that can be run on any machine with access to the Internet (it does not need to be run on the cluster). After entering your configuration, the installation shell script (and supporting files) will be created on the host running the installer.

If that Internet connected machine can’t talk with the Kubernetes cluster, the generated files will have to be copied to the airgapped datacenter to execute the installation shell script from there.

It is not necessary for Gradle Enterprise to have access to the Internet once running on the cluster.

Subsequently, updating your Gradle Enterprise version or changing installation configuration involves regenerating the installation script and running it again.

Before you install

This section outlines the installation resource requirements and configuration aspects that need to be resolved during installation.

Supported Kubernetes versions

Gradle Enterprise has been tested as compatible with Kubernetes API versions 1.9.x to 1.17.x. Later versions may be compatible but have not been verified to work.

There are known issues with Kubernetes versions 1.9.4 and 1.9.5 around volume subpaths that make them incompatible with Gradle Enterprise.

Installation system requirements

The Gradle Enterprise installer needs to be executed from a machine with access to the internet. The resulting installation shell script needs to be executed from a machine with kubectl configured to communicate with your cluster. Those might be the same machine. Otherwise, the folder where the Gradle Enterprise installer was executed will have to be copied across. The user running the installer should also have permissions to create Kubernetes resources in the designated namespace.

Storage requirements

Storage Class

Gradle Enterprise uses persistent volume claims for storing logs and data. During the installation you will need to provide the name of the desired storage class to be used for provisioning persistent volumes.


The recommended minimum capacity to provide for Builds Scans is 250 GB, 10 GB for Build Cache, and 10 GB for Test Distribution file cache. If you are producing many build scans a day or intend to retain build scans for long periods of time you may want to consider provisioning more storage. If your storage provisioner does not allow expanding volumes you should also consider preparing for future data growth.


Disk performance has a significant impact on Gradle Enterprise. For production workloads, storage volumes should exhibit SSD-class disk performance of at least 3000 input/output operations per second (IOPS).

Networking configuration

Firewall and proxy configuration

The system running the installer will need access to the internet for retrieving application and installer images as well as validating license information. If you require a proxy for internet access this should be pre-configured on the system running the installer. You should be able to use command line tools like curl as well as issue commands like docker pull against public registries.

Application hostname

When installing Gradle Enterprise, you will be asked to provide a hostname. This should be the hostname that users of the installation use to access it and therefore should resolve within your network. This may depend on how you intend on directing external traffic into your cluster to access Gradle Enterprise. Please refer to this section for more information.

HTTPS SSL certificate

It is strongly recommended that production installations of Gradle Enterprise are configured to use HTTPS with a trusted certificate.

Gradle Enterprise natively supports serving traffic over HTTPS when configured with a certificate and key. If you intend to use an ingress controller for directing external traffic to Gradle Enterprise, you may opt to terminate HTTPS there.

Untrusted SSL certificates

By default, Gradle Enterprise uses the default trust settings of the Java runtime that it ships with when connecting to other systems using SSL. If your organization uses certificates that are not signed by a trusted certificate authority, you must perform additional configuration for this to work. This may be the case if you use self-signed certificates or an internal certificate authority.

Additional certificates to trust can be configured by during installation/configuration by enabling “Trust additional certificates for SSL communication” and uploading all required certificates as a single PEM file.

If using self-signed certificates, the certificate of each service must be uploaded. If using an internal certificate authority, its certificate must be uploaded.

Saving the installation directory

The Gradle Enterprise installer produces installation shell scripts and saves the entered configuration in the directory from which the installer is run. In order to make reconfiguring and upgrading easier, this directory should be saved and stored somewhere for later use. Reusing this directory when reconfiguring or upgrading saves having to reenter your installation configuration.

Consider dedicating a persistent storage area where this directory can be copied or archived to after installation.


Creating the install script

  1. Prior to installation you will be provided a customer ID and installation ID. You will need to provide these as parameters (cust-id resp. install-id) to the install command shown in the next step.

  2. Execute the following command from the installation machine:

    mkdir -p ~/gradle-enterprise && \
    cd ~/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.0 app \
      --customer-id=<cust-id> \
    If you are using Docker on a non-Linux system to perform the installation then you must run the installer from a folder inside your user home directory in order for the installer to save the generated installation scripts to your local machine.
  3. Instructions on the console will ask you to open http://localhost:8800 on a browser.

    If you are using a non-Linux system and Docker Toolbox (i.e. boot2docker) to run Docker in a virtual machine then you will instead need to browse to port 8800 on the IP address of your Docker VM. You can find the IP of your VM by running docker-machine ip from a command line. Additionally, if you are using a proxy server for internet access this you must configure this IP to bypass your internal proxy.
  4. Provide the name of the existing Kubernetes namespace that Gradle Enterprise resources should be created in. If you have not yet created this namespace you should do so now. Lookup this documentation as reference.

  5. If your Kubernetes cluster is not able to pull Docker images from public internet registries than select the Airgap cluster setting. You will need to provide the address of an internal Docker registry where Gradle Enterprise images will be pushed to by the installer. If your Kubernetes cluster additionally requires the use of a pull secret to pull images from this registry you may provide the name of the pull secret as well. You will need to create this pull secret in the same namespace as specified above in step 4.

  6. You can optionally provide contact information for your users should they experience problems. This will be displayed on the /help page, which users are directed to when problems occur.

  7. If using HTTPS as recommended, you’ll need to provide your SSL Private Key and SSL Certificate.

  8. For Storage see the above listed requirements.

  9. You may optionally configure Gradle Enterprise to automatically delete older build scans. See the build scan retention section for more details.

  10. Refer to the Backup and disaster recovery section for information on backups.

  11. Select Save changes, then select Continue to next step to proceed with the installation.

  12. If the Airgap cluster setting was selected, then Docker images will be downloaded.

  13. Next, the installer will ask you to execute:


    If the machine doesn’t have access to the Kubernetes cluster, copy the contents of the current folder (including the hidden .ship folder) to a machine within the airgapped network. This script will install all Gradle Enterprise resources into your Kubernetes cluster. If performing an airgap install, all necessary images will also be pushed to your internal Docker registry.

  14. The installer will persist all configuration values and install script in the directory from which you ran the installer. Consider storing this directory somewhere safe and reusing it when reconfiguring or upgrading your installation.

Exposing Gradle Enterprise outside your cluster

The Gradle Enterprise Kubernetes installer creates a service named gradle-proxy exposing ports 80 and 443 for accessing the application. This service uses a ClusterIP for communication meaning it is not accessible outside of the Kubernetes cluster by default. To access Gradle Enterprise outside of your cluster you will need to create some kind of entrypoint to this service into the cluster. Potential methods for this are via an ingress, explicit node port, external IP service or a load balancer. The method you choose depends on your cluster and network configuration.

We do not recommend editing the existing gradle-proxy service to enable external access. Changes to configuration or subsequent Gradle Enterprise updates will overwrite these changes. If you want to use a node port or external IP instead, you should define a new service in the same namespace.

Operational support scripts

The Gradle Enterprise installer generates a number of support scripts in addition to the installation script in the ./installer/scripts folder in the installation directory. These scripts include:

Script Description

Installs (or upgrades) Gradle Enterprise resources in your Kubernetes cluster

Removes all Gradle Enterprise resources from your Kubernetes cluster

Generates a support bundle containing various log files used for troubleshooting Gradle Enterprise issues

Triggers a backup of Gradle Enterprise database

Copies selected backup archive from Gradle Enterprise server to the local system

Restores Gradle Enterprise data from a previously created backup archive

Sends a test email using the SMTP settings specified in the “Email notifications” section.

It is recommended that you keep these scripts available for future use. Should they be misplaced, simply run the installer again to regenerate them.


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

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

  • To avoid the need to reenter all configuration values, use the same install directory used for the previous installation/upgrade.

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


Build scan retention

For most installations, disk usage will be dominated by build scan data. The amount of data used and rate of growth is dependent on the number and size of builds being captured. By default, build scans are stored indefinitely.

To limit the amount of disk space used to store build scan data, enable the Delete old build scans option. Each day, build scans for builds that occurred more than the specified number of days ago will be deleted.

delete old build scans

Active disk space monitoring and management

Gradle Enterprise can also monitor the amount of disk space free and can take various actions to stop the disk from running out of space.

It is recommended that administrators enable at least some of these settings, as recovering space from a completely full disk can be difficult.

disk usage thresholds 2019.2
Email warnings

An administrator can be notified if the installation’s free disk space goes below a given percentage. This requires administrator email details and SMTP server settings to be configured for the Gradle Enterprise instance.

email settings 2019.2

The warning emails will be triggered when the system goes below the configured percentage of disk space free on the data volume, and will send further updates for each further percentage point change.

When an administrator receives a disk space warning email, they should review their data retention settings, and either:

  • Increase the disk space available to Gradle Enterprise, or

  • Enable the Delete old build scans setting if not enabled or reduce the number of days to retain build scans for

Deleting old build scans

The system can be configured to delete older build scans once disk space free goes below a given percentage. This will delete build scans, starting at the oldest, until disk space is above the configured threshold. This will happen even if the Delete old build scans setting is not enabled, and will delete build scans younger than the given retention window.

If some other process is filling up the Gradle Enterprise volume, the system may keep deleting build scans until none are left. This option should only be enabled on systems where the data volume is isolated from other processes and other things that might fill up a disk, such as log directories.

If an email warning threshold is set, administrators will be sent notification that scan deletion has been triggered. If no warning email threshold is set, no notification will be sent.

Rejecting incoming build scans

The system can be configured to reject incoming build scans once disk space free goes below a given percentage. Build scans will be rejected with an informative error message explaining the reason for the rejection. This stops the system from further increasing disk usage until the administrator can step in to resolve the issue.

An email notification will always be sent when the server starts rejecting build scans.

On a volume that only has Gradle Enterprise data, the following settings are recommended:

  • Warning emails at 15% free disk space.

  • Reject build scans at 5% free disk space. Gradle Enterprise needs a small amount of free space available to recover disk space when removing old data, so it is strongly recommended to stop incoming build scans before the disk is completely full.

  • Optionally delete older build scans at 10% free disk space.

Some things to consider:

  • If backups are created on the same volume, make sure to leave enough room for them in your thresholds. For example, if the total space that your backups take up is 40% of the disk, the above recommended settings would be 55%, 50% and 45%. This goes for any other data on the same volume.

  • If anything other than Gradle Enterprise could potentially write data to your data volume, it is recommended not to enable automatic deletion.

Backup and disaster recovery

Gradle Enterprise provides system backup and restore capabilities to facilitate disaster recovery. Backups can be triggered manually or scheduled to be done automatically on a periodic basis, and require no system downtime.

The backup process produces a single compressed archive which can be used to restore all user data to a state at the time of the backup.

Only user data is captured in each backup. Admin console settings, including SSL certificates, passwords, etc are not included in backup archives. We suggest keeping a copy of the .ship folder created by the installer should you need to restore these settings.

Creating backups

Backup settings can be configured in the Backup section of the installer. The retention policies apply to both automatic and manual backups. You can additionally configure Gradle Enterprise to automatically perform backups on a regular schedule, either daily, weekly or via a custom schedule defined as a cron expression.

backup 2019.2

If “Send email when backup finishes” is checked, Gradle Enterprise will send a notification using the settings specified in “Email notifications” when the backup is complete. This is particularly important in the case of failures.

Manual backups

In addition to configuring automatic scheduled backups, you may trigger a manual backup at any time by running the following command from the installation system.


You can download your newly created backup locally by running:


The backup archive will be copied to the folder from which the script is executed. If multiple backups exist you will be prompted to select the backup you would like to copy.

Restoring from a backup

Once a backup archive is created you may use it to restore a Gradle Enterprise instance to the backup state at any time.

./installer/scripts/ /path/to/

This script will require some downtime on Gradle Enterprise until the restore has finished.

Access control

Gradle Enterprise supports individual user login and access control. User accounts and permissions can be created and managed locally in Gradle Enterprise, or can be sourced from an LDAP service, including Active Directory, or a SAML 2.0 identity provider. For more details on creating users or setting up an LDAP or SAML 2.0 identity provider, refer to the Gradle Enterprise administration manual.

Enabling access control

  1. Select the “Secure Gradle Enterprise” option. An initialization key will now be visible, which is required in a subsequent step.

    access control enable k8s
  2. Continue with the installation as described above.

  3. Copy the Initialization key and follow the link to https://«hostname»/admin/init to initialize the system user account.

    access control initialization key
  4. Enter the initialization key into the box provided and click Access.

  5. The system user account has a fixed username of system. Enter a password to use for the system user account and click Initialize.

    access control system user setup 2019.1
  6. The system user account has now been initialized and can be used to either create local users or configure an external identity provider.

Build scan viewing and publishing

By default, Gradle Enterprise disables anonymous viewing of build scans but enables anonymous publishing of build scans.

access control anon scan access 2019.4

When anonymous build scan viewing or publishing is disabled, users must also be granted the associated access control role to be able to view or publish build scans. Assigning users to access control roles is discussed in Gradle Enterprise Adminsitration Manual.

Authenticated build scan publishing requires individual users configuring access keys for their build environment which may be an impediment when initially evaluating and trialling Gradle Enterprise. For production installations, it is recommended to disable anonymous build scan publishing. Please consult the Gradle Enterprise Gradle Plugin User Manual or Gradle Enterprise Maven Extension User Manual for guidance on how to configure a build environment for authenticated build scan publishing.


If you are experiencing issues with Gradle Enterprise, the Gradle build scan plugin, or the Gradle Enterprise Maven extension please submit a support ticket at, including details of the issue and an attached support bundle.

Support bundles assist our engineers in troubleshooting your issue by providing the following information about your Gradle Enterprise installation:

  • Server logs

  • System performance metrics

  • Gradle Enterprise database statistics

Generating a support bundle

To generate a support bundle execute the following script created by the installer:

Generation of the support bundle may take several minutes to complete.

Next steps

Continue your installation journey by learning more about Build Scans and Build Cache here.