Develocity Edge User Manual | Develocity Documentation

Introduction

Develocity Edge makes it easier to deploy Develocity services closer to where builds are run, increasing build performance and build acceleration reliability

This manual covers setting up an Edge, by creating an Edge in Develocity, installing one or more Edge nodes and connecting the node(s) to Develocity. Also covered by this manual are the steps to enable "Edge discovery" for compatible Develocity plugins and extensions to leverage the Edge network.

Requirements

Develocity configuration

To use Develocity Edge, it is necessary to have Develocity installed.

Verify object storage settings

All Edge nodes are replication-enabled, replicating data stored to and from other nodes in the Edge network, which always includes the Develocity server. This eases replication configuration, particularly when deploying a set of load-balanced nodes at an Edge location.

It is important to review your Develocity object storage configuration ahead of Edge rollout. Check that Develocity is connected to a cloud-based object storage service like AWS S3 or, if using embedded object storage, that it is appropriately sized. As a rule of thumb, the embedded object store volume should have at least three times as much storage allocated to it as the storage allocated to the largest Edge in the network.

Please see the Build Cache storage section of the Develocity Administration Manual to learn more about reserving space on object storage for storing build cache data.

Administering Edges

Establishing Edges requires configuration to be applied to Develocity, either via the Develocity Administration page or imported as unattended configuration.

Please refer to the Edge administration using Develocity section to learn more before proceeding to install an Edge node.

Edge node application

To establish an Edge at least one Edge node must be installed (and connected to Develocity). An Edge node is a server application responsible for processing requests from builds that apply Develocity build agents and for replicating data across the Develocity Edge network.

Use of Gradle’s Edge node software is subject to the Gradle Terms of Use.

The Edge node application is distributed as a Docker image via Docker Hub, and as a executable JAR. Both distributions offer the same functionality.

Older versions of the JAR can be found in the appendix below.

Refer also to the Kubernetes section for information on deploying an Edge node cluster.

Data directory disk usage

Edge nodes require a single directory, referred to as the “data directory”, to store data and other files.

By default, Edge nodes use all the storage provided by the attached host volume. However, a custom storage usage can be specified using the option --target-size (or the EDGE_NODE_TARGET_SIZE environment variable) to request the application to limit usage. It is recommended to set an explicit target storage size if the Edge node shares a storage volume with other applications, runs in Kubernetes or will regularly store large build artifacts.

The Kubernetes quantity format should be used to express large values (e.g. '400M' = 400 megabytes, '2T' = 2 terabytes) for the target size. The value must express a whole number greater than 0 and less than 2^63-1.

Note that the Edge node can inadvertently use more than the configured "target" storage size for log files, config files and other operational files.

CPU & memory

By default, an Edge node uses up to about 2 GiB of memory.

Edge nodes do not require significant CPU resources. Performance is generally constrained by network access to the Edge node.

Java runtime

Edge node and Java version overview
Edge node	Java version
Version 0.1 and later	Java 21

Network

Edges communicate with Develocity over HTTP/1.

Build agents communicate with Edges over HTTP/1, unless the build agent is using Bazel, in which case it communicates over gRPC HTTP/2.

Default network ports bound by Edge node instances
Port	Description
5071	HTTP and gRPC build tool interface
5072	Reserved for application internal use
9090	Application monitoring

Edge administration using Develocity

Edges can be managed using the Develocity Administration page or by applying unattended configuration.

Creating a new Edge for the first time is a multistep process that involves:

Generating a registration key by which Edge nodes can authenticate with Develocity to become associated with Edges.
Describing an Edge by specifying a stable Edge identifier, public address URL and descriptive location name.

Administration page

Edge configuration is located on the "Edges" tab of the Develocity Administration page.

The default page shows a list of all Edges, the Edge nodes connected from that Edge location and a summary of statistics for data transferred for each node in the past 24 hours.

Edge nodes that were connected, but have not recently communicated with Develocity, are listed with a status of "Inactive".

Managing registration keys

Edge registration keys allow Edge nodes to authenticate with Develocity and establish a session. Develocity stores a one-way hashed representation of the registration key string.

A single registration key can be used across all Edges (multiple Edge nodes). However, if required, multiple registration keys can be created for simplifying security and administration workflows.

Registration key management is available in the "Configuration" tab of the "Administration > Edges" page.

Adding an Edge registration key

A new registration key can be generated by following these steps:

Log in to a Develocity instance as a user with "Administer Develocity" permissions.
Navigate to "Administration > Edges".
Click into the Configuration tab.
Click Generate registration key.
Input a value for the Title field on the "Generate a new registration key" page. The Title is a meaningful alias by which the key can be referred to.
Copy the generated registration key and store it securely. This string will be used to authenticate Edge nodes with Develocity.

Revoking an Edge registration key

To revoke an existing Edge registration key click Revoke next to the key in the table of registration keys.

A dialog box will appear asking for confirmation that the key should be revoked and permanently deleted.

Creating an Edge

A new Edge can be created by following these steps:

Log in to a Develocity instance as a user with "Administer Develocity" permissions.
Navigate to "Administration > Edges".
Click Create Edge.
Describe the Edge by providing an identifier, public address and the location name.
Click Save to finalize creation.

Editing an Edge

An existing Edge can be edited by clicking on it from the Edges Administration page.

Only the location name and public address fields can be modified.

For the "Built-in" Develocity server Edge, only the location name can be modified.

Deleting an Edge

From the "Edit Edge" page the Delete button can be used to permanently delete the Edge.

Setting the Develocity server location name

Develocity server is itself considered an Edge (as it provides Develocity services) and has a location name associated with it. By default, the location name is not meaningful and should be changed by a user with "Administer Develocity" permissions.

The default name can be changed by clicking on the "Develocity" Edge entry listed on the "Administration > Edges" page and editing the "Location name" field.

Purging build data from Edges

Build data can be purged from across all Edges by clicking into the Data Management tab on the "Administration > Edges" page.

To request that a build data artifact be purged, the fingerprint of the build data - for example, the fingerprint of a build cache entry - should be input and the project to which it belongs selected.

Only users with the "Administer Develocity" AND "Configure projects" permission can purge build data associated with a project. Users with only "Administer Develocity" permission can only purge build data associated with no project (i.e., "Anonymous").

Unattended configuration

Unattended configuration can also be used to manage registration keys and describe one or more Edges.

It is advised to first review the Edge administration using the Administration page section of the user manual to learn the concepts and terminology used by Develocity for administering Edges.

Managing Edge registration keys

Adding an Edge registration key

To add a new Edge registration key:

Download the latest release of the develocityctl.
Execute the Develocity CLI with the config-file hash option.
When prompted, provide a securely random string value as the input. This is considered the registration key. Store the input string securely as it will be passed as an argument when starting Edge nodes to authenticate with Develocity (see Setting the Edge registration key).
The output from the config-file hash command should be pasted in the list of registration keys, to the hashedKey field.
As keyPrefix provide the first few characters of the securely random string input to develocityctl in Step 3. This can help to identify the registration key when reviewing Edge node configuration.
In the title field specify a meaningful alias which the key will be referred to by Develocity administrators and operators.

For example, given the random string PTfCgyUFIkB8EOm7McnnZhEX7rVHAOv, the edge unattended configuration file would look like the following:

edge:
  registrationKeys:
    - title: My new registration key
      keyPrefix: PTfCgyU
      hashedKey: 2yHwf1ijC+XEBm3FYno3UHDlQHtV7UWeKxWhsCBzeXc=:TJu44NcOb9nlkqlRQmXw+/DY0lNngiGVda5fuBKHEE78RxrGW+Pujl1Rtk5fe2fg5Xphx3YOsRyPxKbJQFmKKw==

Multiple registration keys can be added to the registrationKeys list as follows:

registrationKeys:
  - title: APAC
    keyPrefix: PTfCgyUFIkB8EOm7
    hashedKey: 2yHwf1ijC+XEBm3FYno3UHDlQHtV7UWeKxWhsCBzeXc=:TJu44NcOb9nlkqlRQmXw+/DY0lNngiGVda5fuBKHEE78RxrGW+Pujl1Rtk5fe2fg5Xphx3YOsRyPxKbJQFmKKw==
  - title: EMEA
    keyPrefix: 3xP2tt3FpCYwPDgu
    hashedKey: A0oEl6IayV7XAQuLDeUjIsB58pIy7Mgk3T4eXe5JRbs=:aMWh4YeMVYgiAgw9CTBPNeO600oE+pruc6lwf8LXhwyk+gvjP2FKt5jLT+pT5tNKEdpxMh7bkTTk6L/npOjNFg==

Revoking an Edge registration key

To revoke an existing Edge registration key:

Remove the key being revoked from the list of registration keys (registrationKeys) in the unattended configuration file.
Import the configuration file to Develocity server.
Apply the change, restarting Develocity if necessary.

Setting the Develocity server location name

A custom location name can be set for the Develocity server location by setting a value for develocityLocationName.

edge:
  develocityLocationName: Tokyo, Japan

This location name will represent Develocity in the "Preferred location" dropdown for Develocity users in the "Location" tab of the "My Settings" page.

Creating Edges

One or more Edges can be created using the unattended configuration file by providing an identifier, location name and public address for each Edge.

Changing the identifier for an existing Edge does not update it, instead overwriting the existing one. Edge nodes that previously connected using the old identifier will fail to register for the Edge at that location.

edge:
  edges:
  - identifier: croatia-1
    locationName: Zagreb, Croatia
    publicAddress: https://edge-croatia-1.example.com
  - identifier: poland-1
    locationName: Warsaw, Poland
    publicAddress: https://edge-poland-1.example.com

Removing Edges

To remove an Edge, remove the Edge from the list of Edges in the unattended configuration file.

For example, the state of configuration having deleted the Edge with identifier croatia-1 from the example in Creating Edges:

edge:
  edges:
  - identifier: poland-1
    locationName: Warsaw, Poland
    publicAddress: https://edge-poland-1.example.com

Installing Edge nodes

Setting the Edge registration key

Edge nodes authenticate with Develocity server using an Edge registration key.

The registration key must be provided to the Edge node application at startup by setting the EDGE_REGISTRATION_KEY environment variable.

Registration keys can be generated using the Develocity Administration page. Please refer to the Adding an Edge registration key section of the user manual for a step-by-step guide.

To do so safely when opting to install an Edge node via Docker or run a node using a JAR file, it is advisable to create a .env file declaring via environment variables the Edge registration key and other start-up parameters.

Example .env file: edge-node.env

EDGE_DEVELOCITY_SERVER=https://develocity.example.com
EDGE_IDENTIFIER=valid-edge-id
EDGE_REGISTRATION_KEY=A1b2C3d4...
EDGE_NODE_TARGET_SIZE=25Gi

This file can then be sourced at the time of executing the Edge node application.

Docker

Specify the path to the .env file using the --env-file option.

docker run --detach \
    --volume /opt/edge-node:/data \
    --publish 5071:5071 \
    --env-file /path/to/edge-node.env \
    gradle/edge-node:1.2 \
    start

JAR

1. Create a start-up script that loads the environment variables before running the Edge node. The example script below is for Bash shell.

edge-node-start.sh

#!/bin/bash

EDGE_NODE_ENV_FILE_PATH="$1"

if [ -f .env ]; then
    set -a
    source $EDGE_NODE_ENV_FILE_PATH
    set +a
fi

java -jar edge-node-1.2.jar start

2. Change permissions of the script to make it executable and run the script.

chmod +x ./edge-node.sh
./edge-node.sh "/path/to/edge-node.env"

Kubernetes

Kubernetes users should refer to the Kubernetes section to learn how to apply the Edge registration key as a secret.

Docker

Installation

With Docker installed, an Edge node can be started as follows:

docker run --detach \
    --volume /opt/edge-node:/data \
    --publish 5071:5071 \
    --env-file /path/to/edge-node.env \
    gradle/edge-node:latest \
    start

It is assumed that the mandatory start-up parameters are provided in the .env file. Refer to the Setting the Edge registration key section to learn more.

This will download the latest version of the Edge node container image, create a new container from it, then run it with the UID of the current user. The Edge node will use /opt/edge-node on the host to store its files and serve on ports 5071.

Once connected to Develocity server at https://develocity.example.com, the node will be associated with the Edge identified by valid-edge-id.

More information about changing these settings can be found in the following sections.

Airgapped installation

In order to install the Docker Edge node on a host that is not connected to the Internet (i.e. airgapped), you will need to first obtain the image on an Internet connected host, then transfer it to the airgapped destination.

On the non-airgapped system, pull down the latest docker image for the node
```
docker pull gradle/edge-node:1.2
```

Export the image to a file

docker save gradle/edge-node:1.2 --output edge-node.tar

Copy this file across to the airgapped host, and then import the image into docker
```
docker load --input edge-node.tar
```

The node can then be started and configured on the airgapped host in the same manner as a non-airgapped install.

Versioning

The docker latest tag always refers to the most recently released version of the Edge node, however we recommend using an absolute version when using Docker, as latest may give unexpected results when upgrading due to Docker idiosyncrasies.

Binding the data directory

The Edge node container uses /data inside the container as the application data directory. When starting the container, the --volume (or -v) switch should be used to specify which directory on the host to mount to this directory in the container.

If the container is started without a mount for /data, Docker will create a directory on the host in a location of its choosing to use. The anonymous volume won’t be reused between container runs, losing any persisted Edge node data.

Each Edge node must have its own data directory. Sharing a data directory across nodes is not supported.

When choosing where to store the data (i.e. which host directory to mount to /data within the container), be sure to choose a disk volume that has adequate storage capacity to accommodate the desired storage size.

For more information on managing data volumes with Docker, please see this tutorial.

Run-as user

The Edge node docker image specifies a default user.

If you wish to use a different user ID known to the host, you can pass the argument --user $UID with the required user ID.

The command below demonstrates using a user id of 5000:

docker run --detach \
    --user 5000 \
    --volume /opt/edge-node:/data \
    --publish 5071:5071 \
    --env-file /path/to/edge-node.env \
    gradle/edge-node:1.2 \
    start

The Edge node application will read from and write to the file system as this user. The /data directory mount must be readable and writable by this user.

Port mapping

The Edge node container must expose the port 5071 for build tool connectivity (see also Network) These ports need to be mapped to a port on the host in order to expose it.

The following example exposes the HTTP and gRPC build tool interfaces (Gradle, Maven, sbt and Bazel) via port 8443 on the host:

docker run --detach \
    --volume /opt/edge-node:/data \
    --publish 8443:5071 \
    --env-file /path/to/edge-node.env \
    gradle/edge-node:1.2 \
    start

Auto start

The Edge node container can be automatically restarted on system boot by leveraging Docker’s restart policies. Starting a node container with --restart always will ensure that it is always running unless explicitly stopped.

docker run --detach \
    --volume /opt/edge-node:/data \
    --publish 5071:5071 \
    --restart always \
    --env-file /path/to/edge-node.env \
    gradle/edge-node:1.2 \
    start

Kubernetes

Below is a sample Kubernetes manifest for deploying Edge nodes to a Kubernetes cluster.

An ephemeral volume is mounted to bind the data directory to, and the requested storage should be sized appropriately for the target storage size. You may also need to adjust the allocated CPU and memory resources based on demand and the resources of your cluster.

This Kubernetes manifest also enables peering between Edge nodes in the cluster by default.

apiVersion: v1
kind: Service
metadata:
  name: edge-node
spec:
  selector:
    app.kubernetes.io/part-of: develocity
    app.kubernetes.io/component: edge-node
  ports:
  - name: http
    port: 5071
---
apiVersion: v1
kind: Service
metadata:
  name: edge-node-headless
spec:
  clusterIP: None
  selector:
    app.kubernetes.io/part-of: develocity
    app.kubernetes.io/component: edge-node
  ports:
  - name: http
    port: 5071
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: edge-node
  labels:
    app.kubernetes.io/part-of: develocity
    app.kubernetes.io/component: edge-node
spec:
  replicas: 3 # Change this to the desired number of replicas
  selector:
    matchLabels:
      app.kubernetes.io/part-of: develocity
      app.kubernetes.io/component: edge-node
  strategy:
    type: RollingUpdate
    rollingUpdate: # Change the strategy to adapt to the count of replicas
      maxUnavailable: 25%
      maxSurge: 25%
  template:
    metadata:
      labels:
        app.kubernetes.io/part-of: develocity
        app.kubernetes.io/component: edge-node
    spec:
      securityContext:
        runAsUser: 65532
        runAsGroup: 65532
        fsGroup: 65532
        fsGroupChangePolicy: OnRootMismatch
        runAsNonRoot: true
      terminationGracePeriodSeconds: 600
      containers:
      - name: edge-node
        image: edge-node:local
        args: [ "start" ]
        ports:
        - name: http
          containerPort: 5071
        resources:
          requests:
            memory: 2Gi
            cpu: "2"
          limits:
            memory: 4Gi
            cpu: "2"
        env:
        - name: EDGE_DEVELOCITY_SERVER
          value: http://develocity-app:6011 # Change this to your Develocity server URL
        - name: EDGE_IDENTIFIER
          value: my-edge-1 # Change this identifier to an Edge created in your Develocity installation
        - name: EDGE_REGISTRATION_KEY
          valueFrom:
            secretKeyRef:
              name: develocity-edge-registration-secret
              key: registration-secret
        # This enables the Edge node to peer with other Edge nodes.
        # Assumes there will be more than one Edge nodes in the cluster.
        - name: EDGE_PEERING_ENABLED
          value: "true"
        # Change to "true" for peering over a secure channel,
        # if the Edge node is configured to import certificates
        # and serve data over HTTPS.
        - name: EDGE_PEERING_TLS
          value: "false"
        volumeMounts:
        - mountPath: /data
          name: edge-node-ephemeral-volume
      volumes:
      - name: edge-node-ephemeral-volume
        ephemeral:
          volumeClaimTemplate:
            spec:
              accessModes: [ "ReadWriteOnce" ]
              resources:
                requests:
                  storage: 25Gi # The Edge node uses as much storage as requested to store data

Adding the registration key as a secret

Use the following kubectl command to create the secret named develocity-edge-registration-secret within the desired namespace. Replace <develocity-edge-namespace> with the actual namespace:

kubectl -n <develocity-edge-namespace> apply -f ./edge-registration-secret.yaml

edge-registration-secret.yaml

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: develocity-edge-registration-secret
  namespace: <develocity-edge-namespace>
stringData:
  registration-secret: "dmVyc2lvbjogNQpyZWdpc3RyYXRp...." # Change to actual registration key from Develocity

Exposing Edge nodes outside your cluster

The sample Kubernetes manifest includes a service for the Edge node named edge-node exposing port 5071. This service uses a ClusterIP for communication meaning it is not accessible outside of the Kubernetes cluster by default. To access the Edge node outside your cluster you will need to create some kind of entry-point to this service into the cluster.

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

Below is a sample Ingress definition:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: edge-ingress
spec:
  tls:
  - hosts:
    - {your-domain-name}
    secretName: {tls-secret-for-your-domain-name}
  rules:
  - host: {your-domain-name}
    http:
      paths:
      - path: /
        pathType: ImplementationSpecific
        backend:
          service:
            name: edge-node
            port:
              name: http

JAR

Running an Edge node

Once you have downloaded the JAR file, refer to the Setting the Edge registration key section to learn how to set the Edge registration key used to authenticate with Develocity.

The Edge node application can be run with the java command and the start subcommand, for example:

java -jar edge-node-1.2.jar start --develocity-server=https://develocity.example.com --edge-identifier=valid-edge-id --target-size=25Gi

This will start an Edge node that is:

Connected to the Develocity server at https://develocity.example.com.
Associated with the Edge named $valid-edge-id.
Storing operation data to a directory inside the $TEMP location
Requested to use at most 25 GiB of storage.

Specifying a custom data directory

It is strongly recommended to specify an explicit data directory location with the --data-dir option:

java -jar edge-node-1.2.jar start --data-dir /opt/edge-node

Each Edge node must have its own data directory. Sharing a data directory between Edge node instances is not supported.

To use the current directory as the data directory, use --data-dir .

Specifying the ports

The default listening ports are 5071 and 5072 (the latter is reserved for application internal usage).

With regard to the former, to use a different port you can use the --port option:

java -jar edge-node-1.2.jar start --port 443 --data-dir /opt/edge-node start

Most systems require superuser privileges to bind to a port lower than 1024.

In the absence of a --port option, the PORT environment variable is also respected.

java -jar edge-node-1.2.jar start --config grpcServer.port=6012 --port 443 --data-dir /opt/edge-node start

Optimized HTTPS

Edge nodes serve HTTPS traffic more efficiently on some platforms. If HTTPS is configured but optimized HTTPS support could not be loaded, the application will emit a warning to the console of:

WARNING: Unable to use optimized HTTPS support as OpenSSL was not found.

Currently, optimized HTTPS support is available on the following platforms:

Linux (aarch_64/x86_64)
macOS (aarch_64/x86_64)
Windows (x86_64)

Auto start

The Edge node JAR provides no built-in mechanism for auto starting on system restart. This must be implemented with your operating system’s process manager or similar.

The following demonstrates how to use systemd, a popular process manager for Linux systems, to achieve this.

1. Create a file, edge-node.sh as root and make it executable, with the following contents:

#!/bin/bash
# Launches Develocity Edge node with correct arguments
# Should be run with CAP_NET_BIND_SERVICE rather than as the superuser
EDGE_DEVELOCITY_SERVER=https://develocity.example.com
EDGE_IDENTIFIER=valid-edge-id
DEVELOCITY_EDGE_REGISTRATION_KEY=A1b2C3d4...
EDGE_NODE_TARGET_SIZE=25Gi

java -jar /absolute/path/to/edge-node-1.2.jar start

2. Create a file, /etc/systemd/system/develocity-edge.service as root, with the following contents:

[Unit]
Description=Develocity Edge
After=network.target
StartLimitIntervalSec=0

[Service]
# To improve security you should create a separate user to run the Edge node
#User=gradle
#Group=gradle
# Allow using ports below 1024, required if not run as the superuser
AmbientCapabilities=CAP_NET_BIND_SERVICE
Restart=always
RestartSec=1
ExecStart=/absolute/path/to/edge-node.sh

[Install]
WantedBy=multi-user.target

3. Run the following to start the Edge node for the first time:

systemctl start develocity-edge

4. Run the following to have systemd start the Edge node on system boot:

systemctl enable develocity-edge

Post-installation setup

Verify connectivity

The Edge node has a /ping HTTP endpoint to test connectivity, which can be used to test if it is reachable for users in general. For example, if you are running an Edge node locally, without SSL, and are using the default listening port, then you can access this endpoint at http://localhost:5071/ping.

Connectivity to an Edge node can be tested by running the following command on hosts/computers which need to connect:

curl -sw \\n --fail-with-body --show-error https://<edge-node-host>/ping

It should return SUCCESS.

Optimizing replication with signed URLs

A prerequisite for configuring Develocity to use signed URLs is that Develocity is connected to either AWS S3 or Google Cloud Storage.

By configuring Develocity to use signed URLs, Develocity server does not need to act as a proxy for Edges to transfer build data into object storage, reducing load on the server. Signed URLs - also known as pre-signed URLs or Shared Access Signatures - are time-bound, pre-authorized URLs that grant temporary access to an object in storage.

An advanced parameter presignedUrl.enabled must be added to the objectStorage Helm values. Refer to the examples below for each of the supported object storage types.

AWS S3

values.yaml

objectStorage:
  type: s3
  s3:
    advancedParams:
      presignedUrl.enabled: true

Google Cloud Storage

values.yaml

objectStorage:
  type: googleCloudStorage
  googleCloudStorage:
    advancedParams:
      presignedUrl.enabled: true

Configuring peering between nodes at an Edge

Develocity Edge nodes in proximity can optionally establish direct communication ("peering") to replicate data between themselves.

When enabled, a set of peered Edge nodes can request and serve artifacts from one another without needing to fetch the same data repeatedly from the central Develocity server or object storage. Peering can help to:

Decrease egress bandwidth consumption by reducing the need to replicate data from the Develocity server to each Edge node individually.
Minimize latency when accessing data for the first time if it’s not already stored locally on an Edge node.
Allow new nodes to bootstrap quickly from local peers in ephemeral or autoscaled node environments.

Peering is most effective when Edge nodes are deployed within the same low-latency network boundary (e.g., same availability zone or region) to minimize inter-node communication overhead.

Enabling peering

Peering between Edge nodes can be initiated by applying CLI options or setting environment variables when starting Edge nodes.

To activate Edge node peering, you must for each Edge node participating in a peering group:

Pass the --peering flag or set the EDGE_PEERING_ENABLED environment variable to true.
Specify the address that peers can use to connect to the Edge node using the --advertised-address option.

By default, peers are discovered using Develocity server. However, it’s possible to use DNS-based discovery instead, which could be preferable in some environments (mainly Kubernetes). To enable DNS-based discovery instead, you must set the --discovery-strategy option to DNS. The --advertised-address is optional in case of DNS-based discovery with Kubernetes.

If using environment variables to configure an Edge node, the advertised address and discovery strategy can be set using EDGE_ADVERTISED_ADDRESS and EDGE_DISCOVERY_STRATEGY respectively.

Peering strategies

The peering strategy can be selecting using the --peering-strategy option.

STATEFUL (default): This is the preferred option and involves actively streaming catalog changes (deltas) between connected peers. When a lookup for build data occurs, the Edge node checks the local representation of the catalogs of all its peers, and if the data is found, it is retrieved directly from that peer.
STATELESS: This strategy is more situational, such as in case of smaller clusters (a few Edge nodes in the cluster) or when the network might be unstable between nodes. When requested build data is missing locally, the Edge node simultaneously queries all available peers and reads the fastest successful response. There is no streaming of catalog deltas between peers.

The peering strategy can be customised by setting the EDGE_PEERING_STRATEGY environment variable.

Securing communication between peers

If peers are not in the same trusted network, it is important to secure communication between them using TLS.

To do so, you must provide the --peering-tls option (or set EDGE_PEERING_TLS environment variable to true) when starting the Edge node. Additionally, follow the Using HTTPS section to configure each Edge node in the peering group to serve HTTP traffic over TLS.

Increasing memory limits

By default, the Edge node uses 2 GiB of heap memory and 500MiB of off heap memory. If you need to allocate more memory, the application can be configured as follows:

Docker

The value for heap and off heap memory is set using an environment variable called JAVA_OPTS in the docker run instruction.

docker run --detach \
    --volume /opt/edge-node:/data \
    --publish 5071:5071 \
    --env JAVA_OPTS="-Xms3g -Xmx3g -XX:MaxDirectMemorySize=1g" \
    gradle/edge-node:1.2 \
    start

Kubernetes

The value for heap and off heap memory is set using an environment variable called JAVA_OPTS for the container in the Kubernetes manifest. It is important that the container resources are also adjusted accordingly.

containers:
- name: edge-node
  args: [ "start" ]
  env:
  - name: JAVA_OPTS
    value: "-Xms3g -Xmx3g -XX:MaxDirectMemorySize=1g"
  resources:
    requests:
      memory: 3Gi
    limits:
      memory: 6Gi

JAR

The value for heap and off heap memory is set using the standard JDK parameters when running the JAR.

java -jar edge-node-1.2.jar -Xms3g -Xmx3g -XX:MaxDirectMemorySize=1g

Logging

The logs for an Edge node are located in the «data-dir»/logs directory. Logs are automatically rotated. The latest log file is named node.log (the latest log file is always «data-dir»/logs/node.log).

Monitoring

Edge node exposes the following endpoints on the monitoring port (9090):

Endpoint Description

Endpoint	Description
`/actuator/live`	Liveness probe. Always returns `200 OK` response status.
`/actuator/ready`	Readiness probe. Returns `200 OK` when the Edge node is ready to accept traffic, and `503 SERVICE UNAVAILABLE` when it is disconnected from Develocity.
`/actuator/metrics`	Application metrics in Prometheus format.

/actuator/live

Liveness probe. Always returns 200 OK response status.

/actuator/ready

Readiness probe. Returns 200 OK when the Edge node is ready to accept traffic, and 503 SERVICE UNAVAILABLE when it is disconnected from Develocity.

/actuator/metrics

Application metrics in Prometheus format.

Metrics

Prometheus metrics exposed by an Edge node.

Note: DistributionSummary is a combination of Summary and a Gauge that tracks the maximum value (with a _max metric name suffix).

Metric Name Type Description

Metric Name	Type	Description
`service_active_requests`	Gauge	Active requests currently handled by the service.
`service_request_duration_seconds`	DistributionSummary	Duration of request (in seconds)
`service_request_length`	DistributionSummary	Length of the request content (in bytes).
`service_requests_total`	Counter	Number of handled requests.
`service_response_duration_seconds`	DistributionSummary	Duration of response (in seconds)
`service_response_length`	DistributionSummary	Length of the response content (in bytes).
`service_timeouts_total`	Counter	Handled service timeouts.
`service_total_duration_seconds`	DistributionSummary	Service duration (since request processing started until response processing ended).
`jvm_*`	-	JVM Metrics metrics provided by Micrometer
`process_*`	-	System metrics provided by Micrometer.

service_active_requests

Gauge

Active requests currently handled by the service.

service_request_duration_seconds

DistributionSummary

Duration of request (in seconds)

service_request_length

DistributionSummary

Length of the request content (in bytes).

service_requests_total

Counter

Number of handled requests.

service_response_duration_seconds

DistributionSummary

Duration of response (in seconds)

service_response_length

DistributionSummary

Length of the response content (in bytes).

service_timeouts_total

Counter

Handled service timeouts.

service_total_duration_seconds

DistributionSummary

Service duration (since request processing started until response processing ended).

jvm_*

-

JVM Metrics metrics provided by Micrometer

process_*

-

System metrics provided by Micrometer.

Dashboard

You can visualize Edge node metrics with Edge Node Grafana dashboard.

The dashboard displays the build tool interface metrics:

Throughput, Latency and Errors (The RED Method metrics)
Service responses grouped by outcome (success/failure) and HTTP response code

JSON file of the dashboard can be found in the appendix below.

Leveraging Edges in builds

Enabling Edge discovery

The Develocity Gradle and sbt plugins, along with the Develocity Maven extension, provide an opt-in “Edge discovery” option, which uses the user’s location setting in Develocity to automatically assign an Edge to use as a remote build cache.

Using Edge discovery removes the need for extra local build configuration and allows Edge locations (and their address) to be updated dynamically as the Develocity server manages all configuration.

Develocity users can set their location in the "My Settings - Location" page of the Develocity user-interface.

This feature can be used only when access key authentication is used by the build.

Gradle usage

(Develocity Gradle plugin 3.19+)

Kotlin

develocity {
    server = uri("https://develocity.example.com")
    edgeDiscovery = true
}

The Gradle build must also apply the Develocity Gradle plugin Build Cache connector for the discovered Edge to be used for remote build caching.

Apache Maven™ usage

(Develocity Maven extension 1.23+)

develocity.xml

<develocity>
  <server>
    <url>https://develocity.example.com</url>
    <edgeDiscovery>true</edgeDiscovery>
  </server>
</develocity>

sbt usage

(sbt plugin 1.3+)

build.sbt

ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://{develocityHostname"))
        .withEdgeDiscovery(true)
    )
}

Edge failover

A Develocity installation that includes multiple Edge locations can benefit from increased build acceleration continuity through Edge failover.

Normally, if a build encountered a build cache error, remote caching would be disabled for the remainder of the build. With Edge discovery enabled, if an error occurs while interacting with an Edge’s Build Cache service, the build agent will automatically attempt to fail over to another available Edge. This gives the build a chance to continue taking advantage of remote caching and realize further build time savings.

The Develocity server itself is considered an Edge and can be used as a failover target by builds.

When a failover is necessary, the build agent will choose a new Edge from the list of available Edges discovered at the start of a build. The selection prioritizes the Edge to which the build agent has the lowest latency (and below a certain threshold) at time of failover.

Build Scan integration

Whether the Edge discovery option was enabled for a build is visible under the “Performance → Build Cache” tab of Build Scan.

When Edge discovery is enabled, the location of the Edge used by a build for remote build caching will be visible here too.

This information is available starting from Develocity 2025.1 only if the build was run with either the Develocity Gradle plugin 4.0+, Develocity Maven extension 2.0+ or sbt plugin 1.3+.

build scan performance build cache edge fields

Using HTTPS

By default, Edge nodes serve over HTTP. Using HTTPS requires extra configuration.

Using your own certificate

To use your own certificate, specify the path to an X.509 certificate (including intermediates) using the cert-file option and the path to your PKCS#1 or PKCS#8 private key using the key-file option. Both files must be in PEM format.

java -jar edge-node-1.2.jar start --cert-file ./ssl.crt --key-file ./ssl.key

Or when using the Docker image:

docker run --detach \
    --volume /opt/edge-node:/data \
    --publish 5071:5071 \
    gradle/edge-node:1.2 \
    start
    --cert-file /data/ssl.crt --key-file /data/ssl.key

Using a generated certificate

You can have the server generate its own self-signed certificate to use. To do this, specify the --generate-self-signed-cert argument to the node application.

java -jar edge-node-1.2.jar start --generate-self-signed-cert

Or when using the Docker image:

docker run --detach \
    --volume /opt/edge-node:/data \
    --publish 5071:5071 \
    gradle/edge-node:1.2 \
    start
    --generate-self-signed-cert

This certificate will not be trusted by clients, and will require extra configuration by clients.

Please consult the Gradle user manual or Develocity Maven Extension User Manual for how to configure Gradle or Maven builds to accept an untrusted SSL connection.

Allowing untrusted SSL connections

By default, the Edge node will not allow connections to Develocity if the Develocity serves over HTTPS and present untrusted certificates (e.g. self-signed). In order to allow such connections, the Edge node must be started with the --allow-untrusted-ssl argument, as follows:

Docker

docker run --detach \
    --volume /opt/edge-node:/data \
    --publish 5071:5071 \
    gradle/edge-node:1.2 \
    start --allow-untrusted-ssl

Kubernetes

containers:
- name: edge-node
  args:
  - start
  - "--allow-untrusted-ssl"

JAR

java -jar edge-node-1.2.jar start --allow-untrusted-ssl

Appendix A: Release history

1.2

21st August 2025

[FIX] Forward proxy connectivity to Develocity server

1.1

7th August 2025

[FIX] Edge peering doesn’t handle namespaced cache entries
[FIX] Certain cache events aren’t persisted for Bazel clients

1.0

15th July 2025

[NEW] Enable artifact sharing between Edge nodes via peering
[NEW] Edge node now exposes Prometheus-compatible metrics

0.6

6th June 2025

[NEW] Update JDK Docker base image to JDK 21.0.7

0.5

27th May 2025

[FIX] Storing a cache entry can fail if an earlier eviction of that entry encountered an error

0.4

24th April 2025

[FIX] Connections to Develocity for data replication do not respect HTTP/2 preference
[FIX] Verbose log messages for normal connection lifecycle events
[FIX] Delay is too long between retries of some calls to Develocity

0.3

8th April 2025

[NEW] Support replication using signed URLs when Develocity is connected to AWS S3 or Google Cloud Storage
[NEW] Option to connect to Develocity using HTTP/2
[NEW] Improved performance from Develocity server connections for replication
[FIX] Replication of data to Develocity can fail silently
[FIX] Edge node name is not updated when changed using command line argument
[FIX] Sanitize potentially sensitive information from log messages

0.2

18th February 2025

[FIX] Build agent authentication results are incorrectly cached
[FIX] Maven and sbt entitlements are not updated from Develocity

0.1

12th December 2024

[NEW] First release of Develocity Edge node providing build caching services.

Appendix B: JAR downloads

Appendix C: Dashboard downloads

edge-node-dashboard-1.0.json Download (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)

Appendix D: Verifying the signature of the Edge node artifacts

The Edge node JAR and schema are published to docs.gradle.com alongside its signatures. The public key is published to https://pool.sks-keyservers.net and https://keys.openpgp.org. You can verify the signature of the JAR as follows:

$ curl -OL https://docs.gradle.com/edge-node/jar/edge-node-1.2.jar && \
  curl -OL https://docs.gradle.com/edge-node/jar/edge-node-1.2.jar.asc && \
  gpg --keyserver keys.openpgp.org --recv-key 7B79ADD11F8A779FE90FD3D0893A028475557671 && \
  gpg --verify edge-node-1.2.jar.asc edge-node-1.2.jar

The output of the last command should look similar to the following:

gpg: Signature made Thu Sep 28 16:17:46 2023 CEST
gpg:                using RSA key 893A028475557671
gpg: Good signature from "Gradle Inc. <info@gradle.com>" [unknown]
gpg:                 aka "Gradle Inc. <maven-publishing@gradle.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7B79 ADD1 1F8A 779F E90F  D3D0 893A 0284 7555 7671

This verifies that the artifact was signed with the private key that corresponds to the imported public key. The warning is emitted because you haven’t explicitly trusted the imported key (hence [unknown]). One way of establishing trust is to verify the fingerprint over a secure channel. Please contact technical support should you wish to do so.

Appendix E: Migrating to Develocity Edge from an existing Build Cache node installation

When moving from an existing Build Cache node installation to Develocity Edge there are additional actions that should be considered before setting up Edges.

Configuring object storage for Develocity

Refer to the Verify object storage settings section of this manual.

Preserving existing build cache data

Edge nodes use a different data indexing subsystem. The path to the existing Build Cache node’s data directory should not be specified on Edge node start-up to the --data-dir option and a new directory specified instead.

If preserving existing build cache data is desirable, it is recommended to confirm that existing Build Cache nodes in the network do not have the Legacy replication mode enabled.

appendix migrate bcn edge replication settings

By disabling Legacy replication, Build Cache nodes will begin replicating to the Develocity server newly stored build cache entries, which in turn immediately become available to nodes in the Edge network. It is therefore possible to perform a phased migration towards the adoption of Develocity Edge, without incurring a temporary degradation in build cache hit rates.

Storage management configuration

Edge nodes have a simplified storage management configuration model compared with Build Cache nodes. By default, Edge nodes use all the storage provided by the attached host volume (with a free space buffer). This is equivalent to the “Maximum available” setting provided by the Build Cache node app. However, it is recommended to set an explicit target storage size if the Edge node shares a storage volume with other applications, runs in Kubernetes or will regularly store large build artifacts.

Prior to installation, please review the existing Build Cache node storage management configuration. The existing configuration can be viewed either via the Develocity Build Cache administration page or by inspecting the configuration file passed to the Build Cache node using the --config-dir option on start up. Refer to the Build Cache node user manual for details of how the target storage size configuration appears in the file.

appendix develocity bcn storage management

Username-password Build Cache access control discontinued

In Develocity version 2024.3 support for username-password Build Cache access control was discontinued.

Please see the accompanying discontinuation notice in the 2024.3 release notes for instructions on how to migrate to Develocity account-based access control.