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.
There are two steps to deploying Gradle Enterprise to a Kubernetes cluster:
Running the Gradle Enterprise installer to produce an installation shell script, tailored to your environment
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.
This section outlines the installation resource requirements and configuration aspects that need to be resolved during installation.
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.|
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.
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.
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.
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.
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.
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.
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.
Prior to installation you will be provided a customer ID and installation ID. You will need to provide these as parameters (
install-id) to the install command shown in the next step.
Execute the following command from the installation machine:
mkdir -p ~/gradle-enterprise && \ cd ~/gradle-enterprise && \ 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> \ --installation-id=<install-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.
Instructions on the console will ask you to open
http://localhost:8800on 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
8800on the IP address of your Docker VM. You can find the IP of your VM by running
docker-machine ipfrom 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.
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.
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.
You can optionally provide contact information for your users should they experience problems. This will be displayed on the
/helppage, which users are directed to when problems occur.
If using HTTPS as recommended, you’ll need to provide your SSL Private Key and SSL Certificate.
For Storage see the above listed requirements.
You may optionally configure Gradle Enterprise to automatically delete older build scans. See the build scan retention section for more details.
Refer to the Backup and disaster recovery section for information on backups.
Select Save changes, then select Continue to next step to proceed with the installation.
If the Airgap cluster setting was selected, then Docker images will be downloaded.
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
.shipfolder) 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.
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.
The Gradle Enterprise Kubernetes installer creates a service named
gradle-proxy exposing ports
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
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:
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.
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.
|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.|
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.
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.
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
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.
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.
Backup location can be changed to a different volume by enabling the Use custom location for backup archives setting and specifying a Backup directory on a different volume.
If anything other than Gradle Enterprise could potentially write data to your data volume, it is recommended not to enable automatic deletion.
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
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.
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.
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.
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.
Select the “Secure Gradle Enterprise” option. An initialization key will now be visible, which is required in a subsequent step.
Continue with the installation as described above.
Copy the Initialization key and follow the link to
https://«hostname»/admin/initto initialize the system user account.
Enter the initialization key into the box provided and click Access.
The system user account has a fixed username of
system. Enter a password to use for the system user account and click Initialize.
In some environments, it may be desirable to allow access to build scans and associated functions for everyone. This can be achieved by checking “Allow anyone to access build scans” in the installation settings console.
Enabling this option allows anyone to access all build scan information without being authenticated. It does not affect access control to other functions such as build cache administration or application administration.
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 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:
System performance metrics
Gradle Enterprise database statistics
Continue your installation journey by learning more about Build Scans and Build Cache here.