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

Installation and operation

Gradle Enterprise leverages Replicated Ship for installation, configuration and software updates. Ship orchestrates downloading and installing the Gradle Enterprise application into an existing Kubernetes cluster.

The Gradle Enterprise installer generates the necessary Kubernetes resource definitions for installation into an existing cluster. Customizations to these resources are done via the graphical installer. Details on running the installer and cluster prerequisites are described below.

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.

The installer itself is executed using Docker Compose. The Compose file format used is 3.3 which requires Docker 17.06 or later and Docker Compose 1.14.0.

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.

Capacity

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.

Performance

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.

Installation

Installing Gradle Enterprise

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

  2. Execute the following command from the installation machine:

    curl -sSL -o docker-compose.yml \
      "https://get.replicated.com/compose/ship.yml?customer_id=<customer id>&installation_id=<installation id>" && \
      docker-compose pull && \
      docker-compose up --abort-on-container-exit
    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.

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

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

    help
  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:

    ./installer/scripts/install.sh

    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 in a folder named .ship in the directory from which you ran the installation script. You may want to save this somewhere for future use when upgrading Gradle Enterprise or updating configuration.

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. Instead, if you with to use a node port or external IP you should define a new service in the same namespace.

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 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 installation machine and install directory used for the previous installation/upgrade or copy the old .ship folder to the new installation directory.

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

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

install.sh

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

uninstall.sh

Removes all Gradle Enterprise resources from your Kubernetes cluster

support_bundle.sh

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

create_backup.sh

Triggers a backup of Gradle Enterprise database

copy_backup.sh

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

restore_backup.sh

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.

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.

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

./installer/scripts/create_backup.sh

You can download your newly created backup locally by running:

./installer/scripts/copy_backup.sh

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/restore_backup.sh /path/to/my_backup.7z

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

Support

If you are experiencing issues with Gradle Enterprise or the build scan plugin please submit a support ticket at support.gradle.com, 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:

./installer/scripts/support_bundle.sh
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.