This manual covers the installation of Gradle Enterprise into a single host. It is useful for administrators and maintainers of Gradle Enterprise installations.
If your organisation has Kubernetes infrastructure or if you are familiar with Kubernetes and are comfortable operating a Kubernetes cluster, you may alternatively install Gradle Enterprise into an existing Kubernetes cluster.
If you are migrating from an existing Replicated Appliance Gradle Enterprise installation, please see the migration guide.
Before installation
Installation Overview
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.
Database type
Gradle Enterprise can store data in either:
-
An embedded database that uses a local directory or volume to store its data, or
-
A user-managed database that is completely separate from Gradle Enterprise.
The two have different trade-offs. Please consider these prior to installation of Gradle Enterprise.
Embedded database
When using the embedded database, Gradle Enterprise will run a PostgreSQL database in a container and store data in a local directory. In this mode Gradle Enterprise can run backups on a regular or cron-like schedule.
The embedded database has several advantages:
-
Simple setup: there is no other database to provision or configure.
-
The database will get upgraded in-place to the latest PostgreSQL version supported by Gradle Enterprise with the relevant Gradle Enterprise upgrade.
-
Gradle Enterprise features that need disk space usage information are supported.
-
For smaller installations it is often cheaper than using a separate database.
However, there are downsides to the embedded database, in particular for larger installations:
-
Disk I/O throughput can be a bottleneck to processing on a busy system. This can be difficult to tweak in many setups.
-
Backup management can get difficult past a certain database size. Specifically, backup generation can be slow and create load on the server, and managing backup files for a terabyte-sized database can be awkward.
-
There is no ability to keep a standby database available.
-
The database is a single point of failure. However for single-node Gradle Enterprise installations any system outage will likely take the service down, regardless of the database.
User-managed database
A user-managed database can be any PostgreSQL 12, 13, or 14 compatible database, but the most common usage is a cloud-based database provider such as Amazon RDS or Aurora. These have a number of advantages, particularly in large installations:
-
Database systems need a different set of resources to be provisioned to run smoothly. For example, a high-traffic Gradle Enterprise instance processing a lot of Build Scans will need a lot of memory, but the database needs a lot of I/O throughput and CPU. Separating the database to a different system that can be scaled differently can allow more cost-effective resource allocation.
-
Most cloud-based database providers have tools that allow efficient snapshotting of databases, both manually and scheduled. This allows faster and more convenient backup and data management.
-
Many cloud database instances allow scaling of resources easily after an initial installation. This makes adding more storage or upgrading the instance type easier than changing the configuration of nodes that Gradle Enterprise is installed on.
-
It is possible to run standby databases for failover in the case of an outage. If self-hosting, this can be done using something like wal-e, and many cloud database providers have this functionality built in to the service.
-
Some cloud database providers have hot standby and failover functionality built in to the service.
There are some downsides to using a user-managed database:
-
Extra system(s) to provision and configure.
-
Administrator must ensure network connectivity to the cloud instance, and consider network latency when choosing where to set up a database.
-
Backups must be completely managed by the administrator or cloud database tool.
-
Disk space management and alerting must be completely managed by the administrator or cloud database tool. Gradle Enterprise features that allow certain actions at disk space percentage thresholds are not available.
-
There are extra security considerations such as credential cycling.
Installation requirements
This section outlines the installation resource requirements and configuration aspects that need to be resolved during installation.
K3s requirements
Please review the latest K3s requirements prior to installation.
Helm requirements
Gradle Enterprise requires Helm version 3.x to install. It is recommended to use the latest version available as this will have all known security vulnerabilities addressed.
Network connectivity requirements
Runtime network connectivity requirements
Gradle Enterprise can be run on hosts that can pull images from the internet, referred to as an online install in this guide, or on hosts without internet connectivity, referred to as an airgap install in this guide.
When starting, online installations of Gradle Enterprise will validate its license with Gradle over the internet. Once running, Gradle Enterprise will periodically check for license updates.
An online installation of Gradle Enterprise will not start if it cannot connect to both registry.gradle.com and harbor.gradle.com . |
Airgap installations of Gradle Enterprise do not require internet connectivity when running (airgap installations do not validate the license on startup and do not periodically check for updates) and therefore do not require any special firewall rules. However, the airgap bundle used during installation must be downloaded from an internet-connected host. See Airgap installation for details.
Airgap installation requires a specific entitlement on your license. If you need an airgap-enabled license, please contact your customer success representative.
Installation network connectivity requirements
Downloading the Gradle Enterprise Helm chart requires internet access. For online installations, Helm is run on the installation host and installs Gradle Enterprise onto that host.
For airgap installations, a bundle including the Helm chart and the container images is downloaded to an internet-connected host. The bundle is then copied to the installation host and a command is run to import the images. Helm is then run on the installation host to install Gradle Enterprise.
Network connectivity verification
See Verifying network connectivity for instructions on verifying network access prior to installation.
CPU & memory requirements
-
Quad-core 2GHz or better CPU
-
16 GB free RAM
Storage requirements
Embedded database
By default, Gradle Enterprise stores its data in a database that is run as part of the application itself, with data being stored in a directory mounted on its host machine. It is also possible to store most data in a user-managed database - see the below for details.
Capacity
Gradle Enterprise stores the majority of its data in its “installation directory”, which defaults to /opt/gradle
. The recommended minimum initial capacity to provide for this directory is 250 GB. It is recommended to create a specific volume for the installation directory to avoid having another consume the space required for Gradle Enterprise, and to ensure at least 10% of the volume’s space is free at all times.
The amount of space used and rate of growth is dependent on your usage of Gradle Enterprise. See the disk space management section of the administration manual for information on avoiding running out of disk space for the installation directory.
The following are additional disk capacity requirements:
Location | |
---|---|
|
1 GB |
|
30 GB |
Backups
It is recommended to create backups of your Gradle Enterprise installation for disaster recovery purposes, by using Gradle Enterprise’s built-in backup scheduling. By default, backups are stored in the “backups” directory of the installation directory. To simplify disk space management, it is recommended to either mount a separate volume at this location or change this setting to a separate volume. The backup location can be specified at installation time, and changed later.
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). Most desktop-class, non-SSD disk drives do not provide this level of performance.
Amazon Web Services
If you are using Amazon Web Services (AWS) and Elastic Block Storage (EBS) to host your Gradle Enterprise instance you should ensure that you provision 3,000 or more IOPS for the data volume. Keep in mind that some general purpose volumes (e.g. gp2
) are limited to 3 IOPS per gigabyte, meaning that a 200 GB volume will only provide a maximum of 600 IOPS. If you are provisioning a volume smaller than 1TB you should consider using gp3
or a provisioned IOPS volume.
The recommendations above are based on average workloads. For projects with more complex builds or teams that produce a large number of build scans, Gradle Enterprise may require higher I/O performance than suggested. |
User-managed database
Gradle Enterprise can be configured to store data in a database that is hosted and managed separately to the rest of the application. This can help with performance in some circumstances by allowing database resources to be scaled separately to Gradle Enterprise. It can also simplify backups and volume management when using a database provider that provides tooling for these out of the box.
When using a user-managed database, some Gradle Enterprise administrative features such as automated backups and build scan disk space management features that respond to low disk space scenarios are not available. Additionally, some installation local disk storage is still required for log files and build cache artifacts. |
Compatibility
Gradle Enterprise needs to connect to a PostgreSQL version 12, 13 or 14 compatible database.
Performance and capacity considerations
For similar workloads, Gradle Enterprise will need similar storage capacity and IOPS throughput as for the embedded database mentioned above. Please see your database provider’s options for provisioning and ensure that they meet these requirements.
When Gradle Enterprise and the database are not deployed in a private network near each other, consideration should also be given to ensuring that the database is hosted as close to the Gradle Enterprise host as possible. In a cloud provider this typically means deploying within the same availability zone or equivalent. This will ensure the lowest latency and highest throughput. Gradle Enterprise will not perform adequately under load if latency to its database is too high.
Backups
When using a user-managed database, backups must be handled by the database provider. Gradle Enterprise built-in backups will not operate in this mode.
Networking configuration
Application hostname
When installing Gradle Enterprise, you will need 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. It is usually the name of the Gradle Enterprise host, or the hostname of a reverse proxy if one is being used.
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. It is also possible to terminate HTTPS connections in an external reverse proxy.
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.
Helm configuration
Many aspects of Gradle Enterprise can be configured inside the application in the Administration screens. Some things must be configured via Helm directly. These are typically things that are necessary to get Gradle Enterprise up and running and serving requests.
Prior to installing Gradle Enterprise, you will need to prepare a values.yaml
file and have your Gradle Enterprise license and SSL certificates available on the installation host.
Helm configuration introduction
Helm configuration can be provided in several ways:
-
Passing values directly to the
helm
command using--set
or--set-file
. -
Creating a yaml file and passing it to
helm
using--values
. -
Editing the default
values.yaml
in the chart prior to runninghelm
.
Nested items in the yaml file have equivalents on the command line. So a yaml file with these values:
global:
hostname: ge.example.com
database:
type: embedded
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 yaml file, such as a whole file:
global:
license:
file: |
multi
line
content
here
Unless otherwise indicated, most values are optional and have usable defaults.
Prior to installing Gradle Enterprise, you will need to prepare a values.yaml
file and have your Gradle Enterprise license and SSL certificates available on the installation host.
Example values file
Although the most commonly required configuration options are documented below, the example values file that 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:
helm show values gradle/gradle-enterprise-standalone
The output of this command can be redirected to a file to use as the starting point for your configuration:
helm show values gradle/gradle-enterprise-standalone > values.yaml
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:
helm show values gradle-enterprise-standalone-2022.2.0.tgz
Airgap configuration
In an airgap installation, the container images are pre-loaded into K3s. Helm is then configured so that no attempt is made to pull images from the outside world.
global:
image:
imagePullPolicy: Never
Gradle Enterprise license
Your Gradle Enterprise license file must be provided to Helm. You can provide the file to helm
using --set-file
:
(helm command) --set-file global.license.file=/path/to/gradle-enterprise.license
Alternatively, you can embed the file into your values file:
global:
license:
file: |
====================== GRADLE ENTERPRISE LICENSE V1.0 ======================
License file ID: YC3IWLASSXB5E
Issued to: ACME Co.
Issued at: 2022-02-11T05:11:38Z
Expires at: 2023-02-11T00:00:00Z
============================================================================
R0VMRgF4nBWOSZKCMAAAX+QUu3BUIJAIwUQiwsViEwMIDKOyvH701n3p6nJBYxoRHnAUnwHwKLjb
YZMAbN8B5BMv3HaCdc9PbcG+Hkdz93XW+gsOY34jP+WC1iKC38SeCCKANn57HP7Bx/lVmFCLROHL
Sv5hP4xlXO9kf40n35x4GgHhk5txTQQcMsmvG8Uz0W/hNN9eQlaMzsK8ZyKOSX0GsBN+dsp5Wq10
/kVuf6u8LfUCPc72q79TWCvmFvNQD6RemcTxAbfILTNuaMsNgLjdCjYVK7padCLiolv2wc1P3pXF
GoAExap9ZPKZTXpeaAaPeFF2qANCH/eXVW7+8kVxz0VH4PPnPjXc1yWzmHNTBu2WbpfDaSJil/g8
lqB6zfaOvfSKQGkVMNthtqjJdSCmne3gWXpFJpGAe7dKkrD9K/vpoUZNUWuV7dFbFpqkNhJn+XAQ
r2cjAak5TluR14aCsX6Fr4JgfSPyWNYdOB7DXrlnNT7d3p+/cFoqGVOvqjfDrnIkVBPLK5PCufU8
VQzz/fagwC6dMtq0MEw5bphm5+LQeFPg/AOoua9P
====================== END GRADLE ENTERPRISE LICENSE =======================
Gradle Enterprise license as compact string
It is also possible to specify the Gradle Enterprise license in its compact form, which is also just the "data" second part of the license.
global:
license:
file: R0VMRgF4nBWOSZKCMAAAX+QUu3BUIJAIwUQiwsViEwMIDKOyvH701n3p6nJBYxoRHnAUnwHwKLjb...
This can be more convenient in some provisioning setups.
Hostname
As described above, a hostname for the application must be supplied:
global:
hostname: ge.example.com
HTTPS
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.
HTTPS terminated at the built-in Ingress
When using the Gradle Enterprise supplied Ingress, HTTPS is enabled by default. It can be disabled to serve traffic over HTTP only:
ingress:
ssl:
enabled: false
SSL certificates can be provided inline in the configuration yaml:
ingress:
enabled: true
ssl:
cert: |
-----BEGIN CERTIFICATE-----
MIIDKjCCAhKgAwIBAgIRAPNTIHf6/oUuzMKm3ffGNOgwDQYJKoZIhvcNAQELBQAw
HDEaMBgGA1UEAxMRYXV0by1nZW5lcmF0ZWQtY2EwHhcNMjExMTMwMTU1NDU5WhcN
...
Cn/3yUirFVTslrSYKAemLw8btLO6FDF9dc/lq1o7tKsYVuhEcjqnTah7puJjEN9h
z+P5RmRxU/kaaFB+Vuw1pRezbaAtZNorVgXnBwrdseY4zLGyhAcGcR9v+VtCiQ==
-----END CERTIFICATE-----
key: |
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA4qV8JlqDMi7y85Ykq8dn7uIsi609D6KuFtlc+UvNYjatz0+u
QzIr3iw//qf7sM8nx8fhGwuWvUWeCE6zbgKjuxDH82J9NQ0ctf70n0qVTeyW1CKR
...
XlOfXr/xvkXA66PROgvVxfwpN/GNrLXFi1HvMg7MVZJUZQpNzpAzw5JTk2MbawOl
G7tI0qQ6F20e5R4tPpEDKCFZykyvgGMhfLzsvVlrgaVW8QbVK4YWNtQ=
-----END RSA PRIVATE KEY-----
Or supplied as helm
arguments using --set-file
:
(helm command) \
--set-file ingress.ssl.cert=/path/to/ssl.crt \
--set-file ingress.ssl.key=/path/to/ssl.key
HTTPS terminated externally
In many setups, a reverse proxy or load balancer will perform SSL termination. In these cases SSL certificates must be configured with that infrastructure.
Gradle Enterprise needs to know if the application will be accessed over HTTPS. This is done with the following configuration:
global:
hostname: ge.example.com
externalSSLTermination: true
Then SSL should be disabled on ingress into K3s:
ingress:
ssl:
enabled: false
Application ports
The ports that the application accepts traffic on can be altered from the default of 443 (or 80 if accepting plain HTTP):
ingress:
port:
http: 8080
https: 8443
Storage configuration
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.
global:
storage:
directory: /mnt/big-volume/ge # Default /opt/gradle
logs:
directory: /var/log/gradle-enterprise # Default (global.storage.directory)/logs
backup:
directory: /mnt/vol2/ge-backups # Default (global.storage.directory)/backups
Database configuration
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.
database:
location: user-managed
connection:
host: database.example.com
port: 5432
name: gradle_enterprise
params: "?connectTimeout=60"
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.
database:
location: user-managed
connection: ...
credentials:
superuser:
username: postgres
password: the_password
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 be preferable to not supply Gradle Enterprise with database superuser credentials. It is possible to instead run a database setup script on the database, which 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.
database:
location: user-managed
connection: ...
credentials:
app:
password: app_password
migrator:
password: migrator_password
Please contact Gradle support for assistance in setting up a database without providing superuser credentials.
Unattended application configuration
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:
aes256:B0uVHRDhng+PraUI:Aj25DOwJsrXnWYcprreHAS4l66k/7q5CIjFDg5PTR7U=
Example yaml file:
version: 4
systemPassword: "ObvvvqQww04Fn2jLBOOgjZDkXGL06fNmpueVcdk1lz0=:dBLNuLA/+qiwOqBQKf5pW89SV5mcQBJ4Vph/7lXerdD+2sLM8jij+2WJbBwXsqJ+mJugsveuUb+DyU3LBgkqcg=="
buildScans:
keepDays: 30
email:
administratorAddress: gradle-enterprise-adminstrator@example.com
fromAddress: gradle-enterprise@example.com
smtpServer: smtp.example.com:587
sslProtocol: startTls
authentication:
type: login
username: gradle-enterprise-adminstrator@example.com
password: "aes256:B0uVHRDhng+PraUI:2bOz71vKTexz0QH5:z7lO+1wOC/tA3izLAwV0BXMugg=="
The file and encryption key can be provided inline in a values file under the unattended
property:
unattended:
key: "aes256:B0uVHRDhng+PraUI:Aj25DOwJsrXnWYcprreHAS4l66k/7q5CIjFDg5PTR7U=" (1)
configuration: (2)
version: 4
systemPassword: "ObvvvqQww04Fn2jLBOOgjZDkXGL06fNmpueVcdk1lz0=:dBLNuLA/+qiwOqBQKf5pW89SV5mcQBJ4Vph/7lXerdD+2sLM8jij+2WJbBwXsqJ+mJugsveuUb+DyU3LBgkqcg=="
buildScans:
keepDays: 30
email:
administratorAddress: gradle-enterprise-adminstrator@example.com
fromAddress: gradle-enterprise@example.com
smtpServer: smtp.example.com:587
sslProtocol: startTls
authentication:
type: login
username: gradle-enterprise-adminstrator@example.com
password: "aes256:B0uVHRDhng+PraUI:2bOz71vKTexz0QH5:z7lO+1wOC/tA3izLAwV0BXMugg=="
1 | The encryption key used for any secrets in your configuration. In this example, the password for email authentication is encrypted. Not required if the configuration does not contain any encrypted passwords. Note that the systemPassword is a hashed value, not an encrypted on, and so does not require an encryption key. |
2 | The Gradle Enterprise configuration yaml is put inline underneath this property. Content needs to be indented such that it is all correctly under the unattended.configuration property. |
Or they can be supplied as helm
arguments using --set-file
:
(helm command) \
--set-file global.unattended.configuration=/path/to/gradle-enterprise-configuration.yaml \
--set-file global.unattended.key=/path/to/gradle-enterprise-configuration.key
Gradle Enterprise configuration that is set in Helm like this will not be reapplied (i.e. overwrite manual changes made in the Admin UI) in subsequent installations unless the contents of the config file(s) has changed. |
Installation
At a high level, installation involves several steps:
-
Install Helm and K3s.
-
Add and update the Gradle Helm repository.
-
Create a file with configuration and gather other necessary files such as the Gradle Enterprise license.
-
Run
helm install
.
Or, for airgapped customers:
-
Install Helm and K3s.
-
Add and update the Gradle Helm repository.
-
Create a file with configuration and gather other necessary files such as the Gradle Enterprise license.
-
Download the airgap bundle and transfer it to your installation host.
-
Import the container images into K3s.
-
Run
helm install
.
Please see the following sections for details.
Installation of prerequisites
The Gradle Enterprise host must have the following software installed.
K3s Installation
To install K3s, please follow the K3s Quick-Start Guide.
Once installed, run these commands to allow Helm and other tools to connect to K3s:
sudo chown $UID /etc/rancher/k3s/k3s.yaml
mkdir -p "${HOME}/.kube"
ln -s /etc/rancher/k3s/k3s.yaml "${HOME}/.kube/config"
You should be able to run kubectl
to interact with the K3s cluster:
kubectl get ns
which should produce something looking like:
NAME STATUS AGE
default Active 1h
kube-system Active 1h
kube-public Active 1h
kube-node-lease Active 1h
Helm Installation
Please follow the Helm installation guide to install Helm.
After installation, you should be able to run the helm
executable:
helm version
Online installation
If the host has internet connectivity, perform an online installation by updating the Helm repository and running helm install
, as described below.
Helm repository and the gradle-enterprise-standalone
chart
Gradle Enterprise is distributed from the https://helm.gradle.com/ Helm repository.
Start by adding the repository to your Helm installation, and fetching its contents into the local cache:
helm repo add gradle https://helm.gradle.com/
helm repo update gradle
The latest version can then be seen by running helm search repo
:
helm search repo gradle-enterprise
This will report the latest versions available for the two Gradle Enterprise charts:
NAME CHART VERSION APP VERSION DESCRIPTION
gradle/gradle-enterprise 2022.2 2022.2 Official Gradle Enterprise Chart
gradle/gradle-enterprise-standalone 2022.2 2022.2 Official Gradle Enterprise Chart
This guide covers installation of the gradle-enterprise-standalone chart. Installation of the gradle-enterprise chart is covered in the Gradle Enterprise Helm Kubernetes Installation Manual. |
Run Helm
With the repository updated, you can now perform an online installation by running helm install
:
helm install \
--create-namespace --namespace gradle-enterprise \
ge-standalone \(1)
gradle/gradle-enterprise-standalone \(2)
--values values.yaml \(3)
--set-file global.license.file=./gradle-enterprise.license(4)
1 | This is the Helm release name. It is used by Helm to identify the Gradle Enterprise installation. |
2 | The Gradle Enterprise chart to install.
|
3 | The values yaml with configuration values, including items such as the hostname. |
4 | The Gradle Enterprise license file. |
You may wish to pass other files using --set-file
, such as certificates for HTTPS, or unattended configuration files.
As discussed above, configuration values can be provided to Helm in a variety of ways. As well as being set in a values config file passed with --values
, values can also be set individually on the command line, using --set
. Similarly, as well as being passed using --set-file, files such as the Gradle Enterprise license or certificates can be passed inline in a values config file. Choose a combination that works for your own configuration management processes.
Airgap installation
Airgap installation involves downloading the airgap bundle, copying it to the Gradle Enterprise host, loading images into K3s and then running helm
.
The version used in examples below may not be the most recent - please see https://gradle.com/enterprise/releases/ for information about the latest version, and adjust the commands accordingly. |
License verification
Verify that your license is airgap-enabled. When viewing the license, you should see airgap
listed as an entitlement. If you need to perform an airgap installation but do not have the airgap
entitlement on your license, please contact your customer success representative.
Bundle download
On an internet connected host, with your Gradle Enterprise license file available:
-
Download the airgap bundle for the version that you are installing:
curl -LOJd @gradle-enterprise.license https://registry.gradle.com/airgap/gradle-enterprise-standalone-2022.2-bundle.tar.gz
You can optionally verify the downloaded bundle file.
-
Transfer the downloaded bundle file to your installation host.
Image import
On the installation host:
-
Expand the bundle:
tar zxvf gradle-enterprise-standalone-2022.2-bundle.tar.gz
-
Run the following command to import images into K3s:
k3s ctr images import gradle-enterprise-standalone-2022.2-images.tar
Run Helm
On the installation host, install Gradle by running helm install
:
helm install \
--create-namespace --namespace gradle-enterprise \
ge-standalone \(1)
gradle-enterprise-standalone-2022.2.0.tgz \
--values values.yaml \(2)
--set-file global.license.file=./gradle-enterprise.license(3)
1 | This is the Helm release name. It is used by Helm to identify the Gradle Enterprise installation. |
2 | The values yaml with configuration values, including items such as the hostname. |
3 | The Gradle Enterprise license file. |
You may wish to pass other files using --set-file
, such as certificates for HTTPS, or unattended configuration files.
As discussed above, configuration values can be provided to Helm in a variety of ways. As well as being set in a values config file passed with --values
, values can also be set individually on the command line, using --set
. Similarly, as well as being passed using --set-file, files such as the Gradle Enterprise license or certificates can be passed inline in a values config file. Choose a combination that works for your own configuration management processes.
Post-installation
System check
At this point, it should be possible to see the Helm release installed:
$ helm --namespace gradle-enterprise list
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
ge-standalone gradle-enterprise 1 2022-02-28 03:01:58.704019291 +0000 UTC deployed gradle-enterprise-standalone-2022.2 2022.2
You can inspect the status of the Gradle Enterprise pods by running kubectl get pods
:
$ kubectl -n gradle-enterprise get pods
NAME READY STATUS RESTARTS AGE
gradle-enterprise-operator-76694c949d-md5dh 1/1 Running 0 84m
gradle-proxy-0 1/1 Running 0 83m
gradle-database-65d975cf8-dk7kw 2/2 Running 0 83m
gradle-enterprise-app-0 1/1 Running 0 83m
gradle-metrics-cfcd8f7f7-zqds9 1/1 Running 0 83m
gradle-test-distribution-broker-6fd84c6988-x6jvw 1/1 Running 0 83m
gradle-build-cache-node-57b9bdd46d-2txf5 1/1 Running 0 84m
gradle-keycloak-0 1/1 Running 0 83m
Cleanup
Once Gradle Enterprise has been installed using Helm, all files used during installation can be removed. This includes the license file, certificates, and values files. These files are not required by Gradle Enterprise after installation.
It is however often useful to keep a copy of any values yaml files, to simplify reinstallation after a system failure or creation of other instances. This may include storage in a version control or provision management system.
Post-installation setup
A number of settings should be reviewed after installation. Please refer to the administration manual.
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:
-
Run
helm upgrade
instead ofhelm install
. -
Use the same Helm release name (
ge
in the example above). -
When running a
helm upgrade
, Helm will reuse values and files that were previously used. This means that you can run:helm upgrade --namespace gradle-enterprise ge-standalone gradle/gradle-enterprise-standalone
or for airgap installations:
helm upgrade --namespace gradle-enterprise ge-standalone gradle-enterprise-standalone-2022.2.0.tgz
and not need to specify any values. If you do specify some changed values (for example, to use a new license file), you will need to either specify all values again, or run
helm upgrade
with--reuse-values
. -
Alternatively, to force
helm upgrade
to use only the values that you set at upgrade time, run with--reset-values
. -
For major version upgrades (e.g. 2021.2.4 to 2021.3 or later), if data is stored in a user-managed database and superuser credentials are not supplied, the database setup script must be run prior to the upgrade. Contact Gradle support to get the correct script for the major version to which the system is being upgraded.
Changing configuration values
To change configuration values, follow the same procedure as for upgrading, but specify the current version to ensure that a later version does not accidentally get installed.
For example, to replace a soon-to-expire Gradle Enterprise license file in a Helm-managed installation, run something like:
helm upgrade \
--namespace gradle-enterprise \
ge-standalone gradle/gradle-enterprise-standalone \
--version 2022.2.0 \(1)
--reuse-values \(2)
--set-file global.license.file=/path/to/new/gradle-enterprise.license(3)
1 | Set the current version to ensure that it won’t change. |
2 | Reuse previous values by default. |
3 | Set the new license file to use. |
Or to upgrade, only using values supplied from a current values.yaml, run:
helm repo update gradle
helm upgrade \
--namespace gradle-enterprise \
ge-standalone gradle/gradle-enterprise-standalone \
--reset-values \
--values values.yaml \
--set-file global.license.file=/path/to/gradle-enterprise.license
For airgap installations, helm repo commands are not necessary, and replace gradle/gradle-enterprise-standalone in the examples above with your airgap chart .tgz file, e.g. gradle-enterprise-standalone-2022.2.0.tgz . |
Uninstalling
For Helm-managed installations, Gradle Enterprise can be uninstalled by running helm uninstall <your-release-name>
:
Example:
helm uninstall --namespace gradle-enterprise ge-standalone
Troubleshooting
Support
If you are experiencing issues with Gradle Enterprise, please see the Administration Manual for information about how to submit a support ticket.
Appendix A: Upgrade notes
For migration from a previous, non-Helm-based installation, please see the migration guide. It is recommended to upgrade to the latest available Gradle Enterprise prior to migrating to the Helm-based installation - please see the upgrade notes in the relevant Appliance or Kubernetes manual.
Runtime network connectivity requirements
Starting with 2022.2, Gradle Enterprise instances installed with Helm validate their licenses with Gradle over the internet. Once running, Gradle Enterprise will periodically check for license updates. Before upgrading a Helm-based installation to Gradle Enterprise 2022.2 or later, ensure that harbor.gradle.com is reachable from the Gradle Enterprise host.
Airgap installations of Gradle Enterprise do not validate the license on startup and do not check for new license updates. Airgap installation requires a specific entitlement on your license. If you need an airgap-enabled license, please contact your customer success representative . |
See Network connectivity requirements and Verifying network connectivity for more information.
Temporarily degraded performance due to data reindexing
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.
Appendix B: Verifying the airgap bundle
You can verify the downloaded file by downloading a SHA256 checksum and using the sha256sum
utility to verify the bundle file:
curl -LOJd @gradle-enterprise.license https://registry.gradle.com/airgap/gradle-enterprise-standalone-2022.2-bundle.tar.gz.sha256
sha256sum -c gradle-enterprise-standalone-2022.2-bundle.tar.gz.sha256
Appendix C: Verifying network connectivity
During installation and upgrades, the installation host requires internet connectivity to https://helm.gradle.com
.
Online installations require runtime internet connectivity https://registry.gradle.com
and https://harbor.gradle.com
.
Connectivity to these can be tested by running the following commands on your installation host:
curl -sw \\n --fail-with-body --show-error https://helm.gradle.com/ping
curl -sw \\n --fail-with-body --show-error https://registry.gradle.com/ping
curl -sw \\n --fail-with-body --show-error https://harbor.gradle.com/ping
All should return SUCCESS
.
If any errors occur, please review your network setup before installing or upgrading Gradle Enterprise.