This manual covers the installation of Develocity into an existing Kubernetes cluster.

Develocity is a Kubernetes-based application, distributed as a Helm Chart. The Kubernetes installation of Develocity described in this manual covers the installation of Develocity into an existing Kubernetes cluster, using the Helm Kubernetes package manager. Helm manages all Develocity components.

For instructions on installing Develocity on a host without public network connectivity, see Airgap Installation.

Prerequisites

1. A Develocity License

If you have purchased Develocity or started a trial, you should already have a license file called develocity.license. Otherwise, you might request a Develocity trial license.

Host Requirements

This section outlines the host requirements for the installation.

1. Kubernetes Versions

Compatibility between versions of Kubernetes, Helm and Develocity can be found on the overview page.

When installing Develocity, if the versions of Kubernetes or Helm you’re using are lower than the supported versions, the installation process will fail. If you choose to proceed with older versions of Kubernetes or Helm that aren’t officially supported, you must override them in the values file.

Be aware that using these unsupported versions is at your own risk.
Example of overwriting versions

This example of overwrites the versions of Helm and Kubernetes with your own versions. This will suppress any validation errors.

values.yaml
...
global:
  helmVersionOverride: "3.5"
  kubernetesVersionOverride: "1.21.0"
...

2. Kubernetes Platforms

Develocity doesn’t use any platform-specific features and is expected to work on all platforms.

3. Helm Requirements

Please check the Helm Version Support Policy to ensure compatibility with your Kubernetes version.

4. Resource Requirements

Node Group Specification

If you are planning to provision a dedicated cluster for your Develocity installation, our recommended node group specification for that cluster is 3 nodes, each with 4 CPU units and 16 GiB memory.

Resource Requests and Limits

If you are planning to install Develocity in an existing cluster, we recommend ensuring access to at least 8 CPU units and 24 GiB memory.

The Develocity Helm Chart’s total resource requests and limits are:

  • Resource requests (the minimal resources required by the application to start): 7.6 CPU units, 18.11 GiB memory.

  • Resource limits (the maximum resources that might be used by the application if available): 15.55 CPU units, 32.28 GiB memory.

5. Database

By default, Develocity stores its data in a PostgreSQL database that runs as part of the application itself, with data being stored in a persistent volume. This is referred to as the embedded database.

It’s also possible to store Build Scans, build cache node, and test distribution data in a user-managed database. A user-managed database can be any PostgreSQL 12, 13, or 14 compatible database.

6. Storage

Develocity uses persistent volume claims for storing data, logs and backups. If your cluster is configured with a default StorageClass, this StorageClass will be used.

In case that there is no default StorageClass configured or that you want to use different StorageClasses, you will need to provide the name of the StorageClass to be used for provisioning persistent volumes.

Different StorageClasses can be specified for the different types of storage used.

It’s recommended to use faster StorageClasses for data and a separate slower, cost-efficient one for backups.

Some Pods are associated with multiple persistent volumes and for Kubernetes platforms with multiple availability zones, the Pods and their persistent volumes must be located in the same zone. In this case it’s recommended to use a StorageClass with a volumeBindingMode of WaitForFirstConsumer to ensure that all persistent volumes are provisioned in the same zone that the pod was scheduled in.

It’s strongly recommended to use StorageClasses that allow persistent volume claim expansion if available. This makes expanding storage used as usage of Develocity increases straightforward.

Capacity

The recommended minimum capacities for the persistent volumes are:

Description Size in GB

Build Scans

250

Build Scans backups

250

Build Cache

10

Test Distribution

10

Logs and Monitoring

22

Embedded Object Storage

10

If you are producing many Build Scans in a day (> 1GB) or intend to retain Build Scans for long periods of time (30 days+) you might want to consider provisioning more storage. If your storage class doesn’t allow expanding volumes, you should also consider preparing for future data growth by adding additional disk capacity upfront.

Performance

For production workloads, the data storage class should exhibit SSD-class disk performance of at least 3000 IOPS (input/output operations per second). The storage classes used for logs and backup volumes might be slower.

Disk performance has a significant impact on Develocity performance. Develocity isn’t compatible with network-based storage solutions due to limitations of latency and data consistency.

Object Storage

Develocity administrators can store Build Scan® data in an object storage service, such as Amazon S3, Google Cloud Platform, and Microsoft Azure. This can help performance in high-traffic installations by reducing the load on the database. Object storage services offer performance and cost advantages compared to database storage. If you deploy Develocity to a cloud provider or have an available internal S3-compatible object store, Gradle recommends using object-based storage for your installation. See Build Scan object storage in the Develocity Administration Manual for a description of the benefits and limitations.

Develocity isn’t compatible with network-based storage solutions due to limitations of latency and data consistency.

7. Networking

By default, Develocity requires a cluster whose nodes can pull images from the internet. It also requires network connectivity for periodic license validation.

An installation of Develocity won’t start if it can’t connect to both registry.gradle.com and harbor.gradle.com.

For clusters with limited or no internet connectivity, follow the Airgap installation steps.

The next sections highlight networking options for your Develocity installation which must be considered for the subsequent Helm Configuration section.

Verifying Connectivity

Internet connectivity to https://helm.gradle.com is required on the host where you run Helm.

For Airgap installations, a connection to the internet on a machine is required to download Develocity installation bundles. You must ensure that you can transfer the files to the host (with limited internet connectivity) at installation time.

Connectivity can be tested by running the following command:

$ curl -sw \\n --fail-with-body --show-error https://helm.gradle.com/ping
$ kubectl run gradle-registry-test -q --rm --attach --restart=Never \
    --image=curlimages/curl -- -sw \\n --fail-with-body --show-error \
    https://registry.gradle.com/ping
$ kubectl run gradle-harbor-test -q --rm --attach --restart=Never \
    --image=curlimages/curl -- -sw \\n --fail-with-body --show-error \
    https://harbor.gradle.com/ping

All three of these commands should return SUCCESS.

HTTP / HTTPS

Connecting to the application over HTTPS with a trusted certificate is strongly recommended.

When using the Develocity supplied Ingress, HTTPS is enabled by default with a self-signed certificate.

SSL certificates, trusted or untrusted, must be provided by your organization to Helm.

In many setups, a reverse proxy or load balancer will perform SSL termination. In these cases SSL certificates must be configured with that infrastructure.

Ports

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

Make sure any additional ports such as K3s or user-managed database ports are reachable if necessary.

Proxy

In case your organization requires all outbound HTTP traffic to go through an HTTP proxy, this must be addressed during Helm Configuration.

Hostname

When installing Develocity, a hostname such as dv.example.com is required.

Make sure to configure the DNS records accordingly.

Add an A record for the hostname that points to the public IP address of your host.

ge.example.com A 12.34.56.78

Verify that your DNS record works correctly before installing Develocity by running dig dv.example.com or ping dv.example.com within the terminal.

If running Develocity behind a cloud load balancer, use /ping for the load balancer’s health check. It will respond as healthy when Develocity is capable of handling requests, even if limited to the interactive starting page while the instance is starting. Using the load balancer to manage fail-over may be undesirable for highly available installations.

If you are installing Develocity in a highly available setup, we recommend submitting a ticket at support.gradle.com for assistance.

8. Kubernetes Permissions

The user running Helm or applying its output should have permission to create Kubernetes resources in the designated namespace.

If your Kubernetes environment has fine-grained permissions such that your Kubernetes account may not be able to create certain types of resources, it’s recommended to inspect the resources that Develocity creates by running helm template and viewing the output.

Helm Configuration

Installation options for Develocity are depicted in a Helm values file.

Follow the instructions in the Kubernetes Helm Chart Configuration Guide and return to this document with a complete values.yaml file.

Installation

In this section you will install Develocity on your host.

To install Develocity, commands will need to be executed on a host with connectivity to your Kubernetes cluster.

For those installing Develocity on a host without public network connectivity, follow the Airgap installation instructions.

1. Install Helm

Develocity requires Helm version 3.5.x (or later) to install.

It is recommended to use the latest version available as this will have all known security vulnerabilities addressed. This document describes the maximum version skew supported between Helm and Kubernetes.

For more information on installing Helm (including alternate installation approaches), see Installing Helm.

Install Helm by running the command:

$ curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

2. Install the Helm Chart

Develocity is distributed from the Develocity Helm repository.

Add the Develocity Helm repository to your Helm installation and fetch its contents into the local cache:

$ helm repo add gradle https://helm.gradle.com/
$ helm repo update gradle

Verify that the Develocity chart is accessible:

$ helm search repo gradle-enterprise

This will report the latest versions available for the two Develocity charts:

Output
NAME                               	CHART VERSION	APP VERSION	DESCRIPTION
gradle/gradle-enterprise           	2024.2.4        2024.2.4    Official Develocity chart for Kubernetes cluster installations
gradle/gradle-enterprise-standalone	2024.2.4        2024.2.4    Official Develocity chart for standalone installations
This guide covers installation of the gradle-enterprise chart. Installation of the gradle-enterprise-standalone chart is covered in the Self-Hosted Standalone Installation Guide.

3. Install Develocity

The recommended way to install Develocity is letting Helm manage the installation. For alternatives, see Advanced Installation.

Install Develocity:

$ helm install \
    --create-namespace --namespace {productFilename} \(1)
    ge \(2)
    gradle/gradle-enterprise \(3)
    --values values.yaml \(4)
    --set-file global.license.file=./{productFilename}.license (5)
1 This example uses {productFilename} as the namespace, but it can be a custom name. If you use a custom name, update all other example commands accordingly. Running with --create-namespace will create the namespace if it does not already exist.
The namespace option may not be required for OpenShift if oc login has been run and the active project for the current context is set.
2 This is the Helm release name. It is used by Helm to identify the Develocity installation.
3 The Develocity chart to install, in this case, gradle/gradle-enterprise.
To install a specific version, use --version 2024.2.4.
4 The Helm values file with configuration values, including items such as the hostname.
5 The Develocity license file (if not already included in your values file).

4. Start Develocity

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

$ helm --namespace develocity list
Output
NAME	NAMESPACE        	REVISION	UPDATED                               	    STATUS  	CHART                     	                            APP VERSION
ge  	develocity      	1       	2024-10-22 04:59:38.62408043 +0000 UTC	deployed	gradle-enterprise-2024.2.4  	2024.2.4

You can inspect the status of the Develocity Pods:

$ kubectl --namespace develocity get pods
Output
NAME                                               READY   STATUS    RESTARTS   AGE
gradle-monitoring-798959c44d-x6pkh                 1/1     Running   0          8h
gradle-embedded-object-storage-6b986f78f6-mxmfn    1/1     Running   0          8h
gradle-enterprise-operator-6d64cccdfb-4b9qz        1/1     Running   0          8h
gradle-proxy-54bb65946c-wx4rx                      3/3     Running   0          8h
gradle-database-767b865484-5q6sz                   3/3     Running   0          8h
gradle-metrics-5457b68cc-d4z72                     2/2     Running   0          8h
gradle-keycloak-54589bdb85-z5fdx                   2/2     Running   0          8h
gradle-enterprise-app-686cd78997-8c4jx             1/1     Running   0          8h
gradle-test-distribution-broker-85d7944dc6-hsck9   1/1     Running   0          8h
gradle-build-cache-node-57c675ccf4-drqfv           1/1     Running   0          8h

Develocity has a /ping endpoint, which can be used to verify network connectivity with Develocity.

Connectivity to Develocity installation can be tested by running the following command on hosts / computers that need to connect to Develocity:

$ curl -sw \\n --fail-with-body --show-error https://«develocity-host»/ping

It should return SUCCESS.

Once all Pods have a status of Running and the system is up and connected, you can interact with Develocity by visiting its URL in a web browser (i.e. the hostname).

gradle enterprise

Congratulations Develocity is installed and running.

Head over to the Next Steps section to learn more about Develocity.

Airgap Installation

Airgap installations require a Docker or compatible registry available on an internal network that’s accessible from the cluster to which Develocity images can be pushed.

Airgap installations require a specific entitlement on your license. If you need an Airgap-enabled license, please contact your customer success representative.

For Airgap installations:

  • The installation files must be downloaded on a host with access to the internet

  • The images must be uploaded to the internal container registry on a host with network access to the internal container registry (no internet access required)

  • Helm must be run on a host with network access to the Kubernetes cluster (no internet access required)

  • There must be some mechanism for transferring the downloaded installation files to where they will be used

1. Overview

Airgap installations require a Docker or compatible registry available on an internal network that is accessible from the cluster to which Develocity images can be pushed.

Airgap installations require a specific entitlement on your license. Please contact Gradle if you need an Airgap-enabled license.

For Airgap installations:

  • The installation files must be downloaded on a host with access to the internet

  • The images must be uploaded to the internal container registry on a host with network access to the internal container registry (no internet access required)

  • Helm must be run on a host with network access to the Kubernetes cluster (no internet access required)

  • There must be some mechanism for transferring the downloaded installation files to where they will be used

When installing Develocity, follow the installation manual for that version as the steps may have changed. See Develocity releases for information about the available versions.

We recommend you save all the files into a single transfer directory so that it is easy to transfer to other hosts. For example:

$ mkdir {productFilename}-installation-files && cd {productFilename}-installation-files

2. Download Helm

Use the compatibility matrix to identify the latest version of Helm supported by your version of Develocity.

Download the Helm binary:

$ curl -L -o helm-linux-amd64.tar.gz https://get.helm.sh/helm-v«helm-version»-linux-amd64.tar.gz
You can see all available Helm releases on the Helm releases page.

3. Download Bundle

Save your Develocity license to the transfer directory as {productFilename}.license.

Download and verify the airgap bundle:

$ curl -LOJd @{productFilename}.license \
    https://registry.gradle.com/airgap/{chartName}-2024.2.4-bundle.tar.gz
$ curl -LOJd @{productFilename}.license \
    https://registry.gradle.com/airgap/{chartName}-2024.2.4-bundle.tar.gz.sha256
$ sha256sum -c {chartName}-2024.2.4-bundle.tar.gz.sha256

If the checksum verification fails, check the contents of the downloaded files for error messages.
If the error message indicates that your license is invalid/expired/not airgap enabled, you will need to request an updated license file by contacting your customer success representative.

Instead of running the above curl commands, you can download the airgap bundle by navigating to https://registry.gradle.com/airgap in your browser and following the instructions on the page.

4. Download Helm Values File

Download and verify the example Helm values file:

$ curl -L -o example.values.yaml \
    https://docs.gradle.com/enterprise/helm-kubernetes-installation/values-{version}/gradle-enterprise-values-{version}.yaml
$ curl -L -o example.values.yaml.sha256 \
    https://docs.gradle.com/enterprise/helm-kubernetes-installation/values-{version}/gradle-enterprise-values-{version}.yaml.sha256
$ echo "$(cat example.values.yaml.sha256)  example.values.yaml" | sha256sum -c

5. Configure Helm Values File

Before installing Develocity and its prerequisites, make sure your Helm values file from the Helm Configuration section is available on your local workstation.

You can use the example values.yaml file from the earlier section to check for any missing configuration.

6. Transfer Files

Check that the transfer directory has the following files (additional files are fine):

  • helm-linux-amd64.tar.gz

  • {productFilename}.license

  • values.yaml

  • {chartName}-2024.2.4-bundle.tar.gz

  • Optional: SSL certificates

Once you’ve verified that you have the required files, transfer them to the host where you are installing Develocity.

7. Upload Images

Follow these instructions on the host with connectivity to the internal container registry with your transferred files present in the current directory.

You must be logged in to the registry before running these commands.

Expand the bundle and upload the images to the internal container registry:

$ tar zxvf {chartName}-{versionWithPatch}-bundle.tar.gz
$ ./upload-images.sh --registry=registry.example.com/gradle-enterprise

8. Install Helm

Follow these instructions on the host with connectivity to the Kubernetes cluster with your transferred files present in the current directory.

To install Helm:

$ tar -zxvf helm-linux-amd64.tar.gz && sudo mv linux-amd64/helm /usr/local/bin/helm

9. Install Develocity

The recommended way to install Develocity is letting Helm manage the installation. For alternatives, see Advanced installation.

Follow these instructions on the host with connectivity to the Kubernetes cluster with your transferred files present in the current directory.

Expand the bundle (may have already been expanded if you uploaded the images on this host):

$ tar zxvf gradle-enterprise-2024.2.4-bundle.tar.gz

Install Develocity:

$ helm install \
    --create-namespace --namespace {productFilename} \(1)
    ge \(2)
    ./gradle-enterprise-2024.2.4.tgz \(3)
    --values values.yaml \(4)
    --set-file global.license.file=./{productFilename}.license (5)
1 This example uses {productFilename} as the namespace, but it can be a custom name. If you use a custom name, update all other example commands accordingly. Running with --create-namespace will create the namespace if it does not already exist.
The namespace option may not be required for OpenShift if oc login has been run and the active project for the current context is set.
2 This is the Helm release name. It is used by Helm to identify the Develocity installation.
3 The Develocity chart to install. This is the .tgz file included in the airgap bundle.
4 The Helm values file with configuration values, including items such as the hostname.
5 The Develocity license file (if not already included in values file).

10. Start Develocity

You can see the status of Develocity starting up by examining its Pods.

$ kubectl --namespace develocity get pods
Output
NAME                                              READY   STATUS              RESTARTS   AGE
gradle-enterprise-operator-7fcdc764fd-mzps6        1/1     Running             0             27s
gradle-enterprise-app-55dc98956f-4h9cq             0/1     Init:0/4            0             27s
gradle-proxy-579d84cc77-xhpl8                      3/3     Running             0             27s
gradle-keycloak-68496f49fd-7b7f4                   0/2     Init:Error          1 (22s ago)   27s
gradle-build-cache-node-6bb59b9df9-gdkxm           0/1     Init:0/1            0             26s
gradle-embedded-object-storage-58b869fc7d-4v6w9    1/1     Running             0             27s
gradle-metrics-7fc9d88bdf-56s79                    1/2     Running             0             27s
gradle-test-distribution-broker-65655fdd6f-24pbk   0/1     Init:0/1            0             27s
gradle-monitoring-5597fc5ffc-qwthh                 0/1     ContainerCreating   0             26s
gradle-database-7c8b4c55dd-fmrqr                   0/3     Pending             0             26s

Eventually the Pods should all report as Running:

$ kubectl --namespace develocity get pods
Output
NAME                                               READY   STATUS    RESTARTS   AGE
gradle-enterprise-operator-7fcdc764fd-mzps6        1/1     Running   0          2m21s
gradle-proxy-579d84cc77-xhpl8                      3/3     Running   0          2m21s
gradle-embedded-object-storage-58b869fc7d-4v6w9    1/1     Running   0          2m21s
gradle-monitoring-5597fc5ffc-qwthh                 1/1     Running   0          2m20s
gradle-metrics-7fc9d88bdf-56s79                    2/2     Running   0          2m21s
gradle-database-7c8b4c55dd-fmrqr                   3/3     Running   0          2m20s
gradle-keycloak-68496f49fd-7b7f4                   2/2     Running   0          2m21s
gradle-enterprise-app-55dc98956f-4h9cq             1/1     Running   0          2m21s
gradle-build-cache-node-6bb59b9df9-gdkxm           1/1     Running   0          2m20s
gradle-test-distribution-broker-65655fdd6f-24pbk   1/1     Running   0          2m21s

Once all Pods have a status of Running and the system is up and connected, you can interact with it by visiting its URL in a web browser (i.e. the hostname).

11. Cleanup

It’s recommended to remove the following files after installation:

  • helm-linux-amd64.tar.gz

  • gradle-enterprise-2024.2.4-bundle.tar.gz

  • gradle-enterprise-2024.2.4.tgz

  • gradle-enterprise-2024.2.4-images.tar

Once Develocity has been installed, files used during installation aren’t required at runtime and can be removed if needed. However, the following files may be useful to preserve, as they may aid in future upgrades or maintenance:

  • Helm values files

  • SSL certificates

  • Develocity license

Care should be applied when handling these files as they may be considered sensitive.

Congratulations Develocity is installed and running.

Next Steps

Kubernetes Helm Chart Configuration Guide - Develocity Helm chart options.
Develocity Administration Manual - Learn how to configure and administer Develocity.
Getting Started with Develocity - Instructions on how to start using Develocity in your builds.
DPE University - A free, self-paced training portal to get the most out of Develocity.

Appendix

Appendix A: Upgrade Notes

Removed Support of Test Distribution Gradle Plugin

The functionality of the Develocity Test Distribution Gradle plugin was merged into the Develocity Gradle plugin as of version 3.11 as part of the Develocity 2022.3 release. Starting with the version 2024.2, Develocity no longer supports using Test Distribution via the standalone Develocity Test Distribution Gradle plugin.

Please check your builds and update them as necessary.

Removed Support of Test Distribution Agent Versions Earlier Than 3.0

Using Test Distribution agents earlier than version 3.0 are no longer supported. These versions of the Test Distribution agent use a deprecated mechanism to register with Develocity by using API keys. Starting with 2024.2, Develocity requires Test Distribution agents to connect using pool-specific registration keys.

Please check your agents and update them as necessary.

Appendix B: Advanced Installation

Chart Download and Selection Options

When asking Helm to install or process a chart, it’s possible to pick several sources:

  • A chart from a repository directly.

  • A downloaded chart archive.

  • An expanded chart directory.

Which of these to use depends somewhat on network and policy requirements.

Direct Selection

This involves simply running helm commands using the above gradle/gradle-enterprise chart name. Helm will download the chart if necessary during execution, so this option requires internet connectivity on the host that Helm is executed on.

Examples:

$ helm install ge gradle/gradle-enterprise «options»
$ helm template gradle/gradle-enterprise «options»

In the absence of reasons not to, Gradle recommends installing Develocity charts in this manner, and this method is used in the main installation section above.

Downloaded Archive

Helm can download a chart archive, and can execute using the downloaded archive. This is most useful when the host with internet connectivity doesn’t have access to the Kubernetes cluster.

Example:

$ helm pull gradle/gradle-enterprise

Downloads the latest version to an archive in the current directory e.g. gradle-enterprise-2024.2.4.tgz.

Then later, possibly on a different host:

$ helm install ge gradle-enterprise-2024.2.4.tgz «options»

This is also the installation method used for airgap installations.

Expanded Chart Directory

It is common for users of Helm to download a chart, edit the included Helm values file, and then commit the result to source control. It is recommended to keep configuration in a separate values file, and install a pristine Develocity chart with configuration provided alongside. However, if your organization’s processes expect Helm Charts to be edited inline, it is possible using this method.

Example:

$ helm pull gradle/gradle-enterprise --untar

Downloads the latest version, and expands it into a gradle-enterprise directory in the current directory.

Or for airgap customers, simply extract the chart .tgz file included in the bundle:

$ mkdir -p gradle-enterprise && \
    tar zxvf path/to/gradle-enterprise-2024.2.4.tgz -C gradle-enterprise

At this point gradle-enterprise/values.yaml can be edited, and the directory committed to source control.

Later:

$ helm install ge ./gradle-enterprise «options»

Installs Develocity from a directory with the expanded chart.

Helm Post-processing

Many organizations require the ability to customise Kubernetes manifests prior to applying them to their cluster. Kustomize is one commonly used tool to do this. It is possible to alter the Helm-generated Kubernetes manifests prior to Helm applying them to the cluster, using Helm Post Rendering via the --post-renderer flag. In this way, manifests can be customised while still allowing Helm to manage what is applied to the cluster.

$ helm install \
    --create-namespace --namespace develocity \
    ge gradle/gradle-enterprise \
    --values values.yaml \
    --set-file global.license.file=./develocity.license \
    --post-renderer path/to/post-renderer.sh

The --post-renderer option specifies an executable script that’s given the Helm-rendered manifests as input (from stdin), and produces manifests with further customizations as output (to stdout).

An example of a Helm post-renderer that uses Kustomize is provided below:

#!/usr/bin/env bash
set -eo pipefail
cat <&0 > /absolute/path/to/kustomizations/develocity.yaml
kustomize build /absolute/path/to/kustomizations

In this example, the develocity.yaml file contains the output of the Helm rendering step. This file should then be used by the kustomization.yaml as an input, as shown below:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - develocity.yaml

# Rest of kustomization

User-Managed Installation

An alternative to running helm install directly on your cluster is to have Helm generate Kubernetes manifests that can then be applied via kubectl or other Kubernetes tooling. In this mode, Helm does not keep track of previously installed versions - the resources in the cluster aren’t tracked and Helm cannot report on the currently installed version.

The most common reasons to do a user-managed installation are:

  • Requirements that the final applied manifests are committed to source control.

  • Need to modify the manifests before applying them to the cluster in a way that’s not supported by Helm post-processing.

  • Preference or policy to have manifests applied and managed by other tools.

  • Need to run Helm on a host separated from the cluster.

There are some other downsides:

  • Some manual cleanup of resources is required after upgrades or uninstallation.

Running helm template

By default, Helm will generate a combined Kubernetes manifest and write it to standard output.

$ helm template \
    gradle/gradle-enterprise \(1)
    --values values.yaml \(2)
    --set-file global.license.file=./develocity.license \(3)
    > develocity.yaml (4)
1 The Develocity chart to install - gradle/gradle-enterprise.
To install a specific version, pass this as additional parameters, e.g. --version 2024.2.4.
2 The Helm values file with configuration values, including items such as the hostname.
3 The Develocity license file.
4 Save all the rendered manifests to a single YAML file.

You may want to pass other files using --set-file, such as certificates for HTTPS.

Configuration values can be provided to Helm in a variety of ways. This includes:

  • Providing a Helm values file (which can contain inline files) with --values

  • Providing files (such as the Develocity license or certificates) with --set-file

  • Setting individual values with --set

Choose a combination that works for your own configuration management processes.

The generated manifest can be committed to version control, copied or processed at this point.

Manifests can also be generated as a set of files in a directory, broken up into logical groupings, by calling Helm with the --output-dir argument:

$ helm template \
    gradle/gradle-enterprise \
    --values values.yaml \
    --set-file global.license.file=./develocity.license \
    --output-dir ./my-develocity-manifests

The above will create files under the specified directory. This may be a preferred form for customization, including using tools such as Kustomize.

Invariant Output

By default, the Develocity Helm Chart randomly generates several secrets during rendering. For example, the embedded database user credentials. This means that by default, repeated invocations of helm template will result in non-identical manifests, because the randomly generated secrets will be different each time, as a security precaution. This can cause unnecessary restarts in Develocity installations, where automated tooling uses changes in rendering output to trigger redeployment.

It is possible to configure Helm such that the output of helm template is invariant. This can be done by setting secret values directly or by specifying a user-managed secret. You also can combine the two solutions if appropriate for your installation, by specifying some secret values directly, and some using user-managed secrets.

The secrets which you’ll need to specify to get invariant output, are shown in the table below.

Helm value Secret data key(s) Usage

For these Helm value keys, you can set either 'value' or 'secretName' under them, to either directly set the secret’s value, or to instead use a user-managed secret, respectively.

When creating user-managed secrets, the secret should have the verbatim data key(s) given in this column. Dots (.) should not be interpreted as nesting or indentation. For example, a secret data key such as 'abc.def' should appear in your created secret like this:

apiVersion: v1
kind: Secret
metadata:
  name: gradle-abc-def-secret
data:
  abc.def: "a-secret-value"

database.credentials.app

username, password

The credentials used by the app to connect to the database

username must be set to ge_app

database.credentials.migrator

username, password

The credentials used when running database migrations

username must be set to ge_migrator

enterprise.session.key

client.side.session.key

The symmetric encryption key used for client-side session data

enterprise.session.token

client.side.session.token

The token used for signing the data associated with client sessions

buildCacheNode.buildCacheBuiltin

build.cache.builtin.secret

The shared secret value used by the app to register the built-in build cache node

authenticationBroker.clientSecret

keycloak.client.secret

The client secret used by the app when connecting to Keycloak

authenticationBroker.adminPassword

keycloak.admin.password

The password for the keycloak admin user

unattended.configuration.systemPassword

None. Must be provided via unattended configuration.

The hash of the system user password. If not specified, then gradle-default-system-password-secret is generated.

Below shows an example Helm values YAML you can use to get invariant output by specifying user-managed secrets.

database:
  credentials:
   app:
     secretName: <user-managed kubernetes secret resource name>
   migrator:
     secretName: <user-managed kubernetes secret resource name>

enterprise:
  session:
   key:
     secretName: <user-managed kubernetes secret resource name>
   token:
     secretName: <user-managed kubernetes secret resource name>

authenticationBroker:
  clientSecret:
   secretName: <user-managed kubernetes secret resource name>
  adminPassword:
   secretName: <user-managed kubernetes secret resource name>

unattended:
  configuration:
    version: 6
    systemPassword: ...

To get invariant output by specifying secret values directly in your Helm values.yaml:

database:
  credentials:
    app:
      password: <secret value>
    migrator:
      password: <secret value>

enterprise:
  session:
    key:
      value: <secret value>
    token:
      value: <secret value>

authenticationBroker:
  clientSecret:
    value: <secret value>
  adminPassword:
    value: <secret value>

unattended:
  configuration:
    version: 6
    systemPassword: ...

As with other values, it’s also possible to set these by passing --set or --set-file when Helm is invoked.

To create a user-managed secret value, you can use kubectl. Below is an example of using kubectl to create embedded database credential secrets, named db-app-user-credentials and db-migrator-user-credentials:

# Add this to your `helm install` command: `--set database.credentials.app.secretName=db-app-user-credentials`
kubectl -n develocity create secret generic db-app-user-credentials --from-literal=username=ge_app --from-literal=password=<your password here>

# Add this to your `helm install` command: `--set database.credentials.migrator.secretName=db-migrator-user-credentials`
kubectl -n develocity create secret generic db-migrator-user-credentials --from-literal=username=ge_migrator --from-literal=password=<your password here>
When you create a secret and reference it by name in your Develocity installation (e.g. using a secretName value), Helm is not managing this secret. If you change the secret value (e.g. when periodically cycling a password), then Develocity may need to be restarted manually into order for the changes to be reflected. To do this, restart all the Pods in the Develocity Helm installation.

Mirroring the Helm Charts

An internal Helm Chart repository can be used to mirror the Develocity Helm Charts.

Using helm pull to fetch the charts is the recommended approach since the Develocity Helm repository index uses relative URLs.

$ helm search repo gradle-enterprise --versions --output json | jq -r '"helm pull " + .[].name + " --version " + .[].version' | sort | uniq | bash