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.

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 verified on Kubernetes 1.8.x and 1.9.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 system with kubectl configured to communicate with your cluster. 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 and 10 GB for Build 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.

SSL certificate

It is strongly recommended that production installations of Gradle Enterprise are configured to use HTTPS with a trusted certificate. This requires ownership of a certificate for the public hostname you intend to use that was issued by a trusted certificate authority.

Gradle Enterprise natively supports serving traffic securely over SSL. If you intend to use an ingress controller for directing external traffic to Gradle Enterprise you may opt to terminate SSL there. If you with to communicate to the Gradle Enterprise server via SSL you will need to provision a certificate and key prior to installation.

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:

    docker pull replicated/ship && \
    docker run -p 8800:8800 --rm -it -v `pwd`:/out \
      -v /var/run/docker.sock:/var/run/docker.sock \
      replicated/ship 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. Docker images will be downloaded in the background. Once finished, the installer will ask you to execute:


    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.

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

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
Due to a current technical restriction, deleting old build scans does not increase the amount of free disk space. Instead, disk space previously used to store build scans that have since been deleted is used for new build scans. Enabling deletion of old build scans will slow or stop the growth rate, but not reduce the amount of used space. This restriction will be removed in a future version of Gradle Enterprise.

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 and email notifications which 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.

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/my_backup.7z

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


If you are experiencing issues with Gradle Enterprise or the build scan plugin 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.