Gradle Enterprise Helm Standalone Installation Manual

Gradle Enterprise is a Kubernetes-based application, distributed as a Helm chart. Helm is a package manager for Kubernetes applications.

The standalone installation of Gradle Enterprise described in this manual involves installing the K3s lightweight Kubernetes distribution onto a host, then using Helm to install and upgrade Gradle Enterprise in the K3s instance on that host.

Helm manages all Gradle Enterprise components, tracking what has been installed and upgrading them gracefully.

The helm command is used to install Gradle Enterprise into K3s and manages each installation / upgrade as a Helm release. See the Helm documentation for explanation of Helm concepts.

It is not necessary to have prior familiarity with Kubernetes concepts to install the Gradle Enterprise standalone distribution.

Gradle Enterprise can store data in either:

The two have different trade-offs. Please consider these prior to installation of Gradle Enterprise.

By default, Gradle Enterprise stores Build Scan data in the configured PostgreSQL database. This has the advantage of being simple to deploy and operate. It has the disadvantage of being expensive and difficult to scale for larger installations. Utilizing an additional S3-compatible store is a compelling deployment option for larger installations that produce large volumes of data.

Please see the Administration Manual for more details.

We focus our support efforts on Ubuntu 18.04/20.04/22.04, RHEL 8.4/8.5/8.6, Debian 11, and Amazon Linux 2. Gradle Enterprise is expected to work on most modern Linux systems.

The minimum installation requirements are:

For AWS EC2 users, the xlarge instance size provides 4 vCPU / 16 GiB Memory.

If you need to scale beyond a single node, we recommend instead following the Gradle Enterprise Kubernetes Helm Installation Manual.

Helm configuration can be provided in several ways:

Nested items in the values file have equivalents on the command line. So a values file with this content:

is equivalent to passing --set global.hostname=ge.example.com --set database.type=embedded on the command line.

It is also possible to put more complex data into a Helm values file, such as a whole file:

Unless otherwise indicated, most values are optional and have usable defaults.

Although the most commonly required configuration options are documented below, the example values file that can be found here and is included in the distribution has descriptions for all supported configuration options. After installing Helm and adding the Gradle Helm repository, this file can be viewed by running the following command:

The output of this command can be redirected to a file to use as the starting point for your configuration:

It’s also possible to see these values when installing from an airgap bundle. After downloading the bundle and transferring it to a host with Helm installed, extract and then run helm show values with the included chart:

In an airgap installation, the container images are preloaded into K3s. Helm is then configured so that no attempt is made to pull images from the outside world.

You will have been provided with a Gradle Enterprise license file. This file can be used in any testing, staging or production deployments.

Your Gradle Enterprise license file must be provided to Helm. This can be done in a number of ways.

You can provide the file to helm using --set-file:

Alternatively, you can embed the file into your Helm values file:

It is also possible to specify the Gradle Enterprise license in its compact form, which is just the "data" part of the license.

This can be more convenient in some provisioning setups.

As described above, a hostname for the application must be supplied:

Connecting to the application over HTTPS is strongly recommended. Gradle Enterprise can be configured to securely serve traffic over HTTPS based on user-provided certificates. If certificates are not supplied, self-signed certificates will be generated and used, though this is not recommended for production operation.

The ports that the application accepts traffic on can be altered from the default of 443 (or 80 if accepting plain HTTP):

The Gradle Enterprise standalone distribution will store its data in a specified directory. By default, this is /opt/gradle.

Logs and backups will be stored in subdirectories of that directory by default. These two locations can be set to something different, to allow logs and backups to be stored on different volumes.

By default, Gradle Enterprise will use an embedded database that stores its data in a local directory. In this configuration, there is nothing else to set up regarding the database.

When Gradle Enterprise is configured to store data in a user-managed database, it must be provided with connection settings and credentials for the database.

Standard connection settings like host, port and database name must be provided. Optionally, additional JDBC parameters can be specified.

The port and params properties are optional.

The database must have already been created using CREATE DATABASE, the createdb command or an equivalent mechanism in a cloud database interface prior to configuring Gradle Enterprise with connection details.

There are two options for credentials. If provided with credentials for a database superuser (such as the postgres user that is common on PostgreSQL database instances), Gradle Enterprise can perform all further database setup, and can do so for all subsequent Gradle Enterprise upgrades. This is the recommended configuration.

Note that in some installations, and often in cloud-based databases, the typical credentials provided by the database provider are not a true superuser, but have many of the same abilities. For example, the supplied postgres account in Amazon RDS Postgres databases is not a true Postgres superuser but has the rds_superuser role. Such accounts are fine to configure Gradle Enterprise to use.

In some instances it may be preferable to not supply Gradle Enterprise with database superuser credentials. To set up your database without database superuser credentials, run the setup.sh script from the database setup scripts for your Gradle Enterprise version against it. When upgrading Gradle Enterprise, you will need to run the new version’s database setup script, too. The script will set up less privileged accounts for the application to use, and some privileged functions needed for the application to run.

The credentials for the accounts must then be set by the user and provided to Gradle Enterprise via Helm configuration.

Please contact Gradle support for assistance in running the script or questions about when to use non-superuser credentials.

Many aspects of Gradle Enterprise’s behaviour can be configured via the Admin user interface. These are described in the Administration Manual.

It is possible to pre-configure Gradle Enterprise with the same settings that can be set via the Admin UI. This is useful to create a working Gradle Enterprise instance in a completely automated way, with no need to configure anything via a user interface.

The settings take the form of a yaml file. This file can be hand-written or exported from Gradle Enterprise. For more details on creating a Gradle Enterprise configuration yaml file, see Unattended configuration in the Administration Manual.

Having prepared a Gradle Enterprise configuration file and optionally an encryption key, you can provide it to Helm in one of two ways.

Example key:

Example yaml file:

The file and encryption key can be provided inline in a Helm values file under the global.unattended property:

Or they can be supplied as helm arguments using --set-file:

If the host where you are installing Gradle Enterprise has internet connectivity, perform an online installation as described below.

Airgap installation involves downloading files, transferring them, installing supporting software, and running helm install.

We recommend you save all the files into a single “transfer directory”, so that it is easy to transfer to the host where you are installing Gradle Enterprise. For example:

At this point, it should be possible to see the Helm release installed:

You can inspect the status of the Gradle Enterprise pods:

For airgap installations, it is recommended to remove the following files after installation:

Once Gradle Enterprise has been installed, files used during installation are not required at runtime and can be removed if desired. However, the following files may be useful to preserve, as they may aid in future upgrades or maintenance:

If you are having difficulty with installing K3s, first review the following:

If you are experiencing issues with Gradle Enterprise, please see the Administration Manual for information about how to submit a support ticket.

Gradle Enterprise installations can use an embedded database provided as part of the installation, or a user-managed database for superior performance and operability. When using a user-managed database, Gradle Enterprise can be configured with superuser access to the database so that it can initialize and configure the database appropriately. Alternatively, this initialization and configuration can be executed manually, avoiding the need to provide Gradle Enterprise with superuser access to the database.

For installations using the superuser-less approach, new configuration requirements in Gradle Enterprise 2022.4 necessitate manually executing an updated configuration script as part of the upgrade.

If your installation uses the superuser-less approach, please contact Gradle Enterprise support to obtain the new configuration scripts before upgrading. If you are unsure whether your installation uses this approach and requires this extra upgrade step, please contact Gradle Enterprise support.

The improvements to the prediction model in this release require re-analyzing build history, which is initiated automatically after upgrading. Attempting to use Predictive Test Selection while this is occurring will result in all tests being selected for execution. The duration of this process depends on the amount of build history stored by your installation and the availability of CPU resources. It is estimated to take ~24 hours for an installation with a build history of 6 months of 60,000 builds per week and 8 processor cores. Due to this, it is recommended that installations using Predictive Test Selection perform the version upgrade at the end of week to allow this process to complete over the weekend.

Predictive Test Selection with Gradle Enterprise 2022.4 requires Gradle Enterprise Gradle plugin v3.12+ or Gradle Enterprise Maven extension v1.16+. Attempting to use Predictive Test Selection with older versions will result in all tests being selected for execution. The Predictive Test Selection Simulator is unaffected by this requirement.

Upon upgrading, a data reindexing process will be initiated in the background with Gradle Enterprise being usable for its duration. CPU usage will be increased and performance may be slightly degraded. For large installations storing many build scans, the reindexing process may take several hours. During this time, some builds may be omitted from cross-build data visualizations. Recent builds are prioritized, making their data available sooner.

Users of the Test Retry Gradle plugin can now achieve the same functionality with the Gradle Enterprise Gradle plugin.

While either can be used with Gradle Enterprise, it is recommended that Gradle Enterprise users adopt the Gradle Enterprise plugin’s retry functionality for ensured future compatibility and easier adoption of future Gradle Enterprise specific features. Please see the migration guide.