Latest version: 1.3.1 (2022-05-19)

The Gradle Enterprise Admin CLI tool is a command line program that can perform tasks related to your Gradle Enterprise instance. Some of these tasks require it to connect to your instance.

The Gradle Enterprise Admin CLI cannot be used to connect to a Gradle Enterprise instance installed as a Replicated Appliance. See the administration manual for equivalent tasks.

Running the Gradle Enterprise Admin CLI tool

This tool in distributed in two ways:

  • As an executable Java JAR file

  • As a Docker image

The recommended configuration for standalone installations is to install the JAR option on the Gradle Enterprise host and run it there.

Running the Admin CLI JAR file

Prerequisites

To run the Admin CLI JAR, you will need:

  • A Java 11+ runtime available locally on the machine that you wish to execute the JAR on. For standalone installs this should be the Gradle Enterprise host.

  • To download the JAR.

Executing the JAR

Run the JAR using the java command:

java -jar gradle-enterprise-admin-cli.jar [arguments]

Run without any arguments to see a list of available commands.

Running the Admin CLI Docker image

Prerequisites

To run the Admin CLI docker image in a container, you will need:

Executing the Docker image

Run the docker run command:

  docker run --rm -it \
    -v "${HOME}/.kube/config:/kube-config:ro" \(1)
    gradle/gradle-enterprise-admin-cli \(2)
    [arguments]
1 This makes your local Kubernetes client configuration available to the Docker container.
2 A specific version of the tool can be selected by appending a tag. E.g. gradle/gradle-enterprise-admin-cli:1.2.

Run without any arguments to see a list of available commands.

Working with files when using the Docker image

A docker container by default cannot access your local filesystem. Instead, it is possible to mount a local directory to a path inside the container as a volume.

Some commands need to read or write files from the local filesystem. It is necessary to mount files or directories into the container in these cases.

The tool executes in the /home directory inside the container. Thus, mounting a directory to /home makes files in that directory available to the tool, and it will write files inside that directory by default.

Mounting a directory is achieved by adding a -v host-path:container-path option to the docker command.

Example, downloading a support bundle:

  docker run --rm -it \
    -v "${HOME}/.kube/config:/kube-config:ro" \
    -v ./bundles:/home \
    gradle/gradle-enterprise-admin-cli \
    support-bundle

This will create a file in the bundles directory.

Many commands have options to accept input from standard input or to produce their output to standard output. Please see the help text for a command by running it with --help to see if this is available for a given command.

Connecting the Admin CLI to your Gradle Enterprise instance

To connect to the Kubernetes cluster into which Gradle Enterprise has been installed, the tool needs to discover or be provided with connection details.

Using the default context from the environment

Kubernetes client configuration is usually stored in the ${HOME}/.kube/config file. If a default context is configured there, the tool will detect this and attempt to connect to that cluster.

To check which contexts are available, and which is the default, run this command:

kubectl config get-contexts

It is possible to set the default context:

kubectl config use-context my-example-context-name

Specifying the context by name

If there is no default set, or if you would like to select the context to use without altering the local environment, it can be speficied as an option:

--kube-ctx=my-example-context-name

Specifying the Kubernetes cluster by URL and token

If running on a machine without a local Kubernetes client configuration set up, it is possible to instead connect to a cluster by providing its URL and an authentication token:

--kube-url=https://kube-cluster.example.com:1234 --kube-token=ABCD1234

Specifying the namespace

If using a locally configured context, a default namespace may be configured. If so, the tool will look for a Gradle Enterprise instance in that namespace.

To check if your current context has a default namesace set, run this command:

kubectl config view -o jsonpath='{..namespace}'

The namespace can be set as the default for the current context by running this command:

kubectl config set-context --current --namespace=my-example-namespace

If there is no current context, or if there is but there is no default namespace, or if Gradle Enterprise is on a different namespace to the default, you can specify the namespace to use as an argument to the tool:

--kube-ns=my-example-namespace

Shell aliases

It is possible to set up a shell alias to run the admin tool with the arguments required to connect to the Gradle Enterprise instance. This then makes running the tool more convenient.

Examples:

alias gradle-enterprise-admin="java -jar /path/to/gradle-enterprise-admin-cli.jar --kube-url=https://my-k8s-cluster.example.com --kube-token=ABCD1234 --kube-ns=gradle-enterprise"

alias gradle-enterprise-admin="docker run --rm -it -v ${HOME}/.kube/java:/kube-config:ro gradle/gradle-enterprise-admin-cli --kube-ctx=my-k8s-cluster --kube-ns=gradle-enterprise"

The alias can then be run as a normal command:

# List commands
gradle-enterprise-admin

# Generate a support bundle
gradle-enterprise-admin support-bundle

Available commands

To see a list of available commands, run the tool with no arguments.

Appendix A: Release history

1.3.1

19th May 2022
  • Mitigate RCE related to CVE-2022-30586

  • Update JDK Docker base image to JDK 11.0.15 to mitigate ECDSA vulnerability

1.3

19th April 2022
  • Remove get-installation-key command

1.2.1

25th March 2022
  • Handle file permissions correctly when run in a docker container

  • Treat absolute paths correctly during support bundle generation

1.2

3rd March 2022
  • Support for the Gradle Enterprise Helm-based deployment platform, including the system, backup, support-bundle, license and database top-level commands

1.1

15th March 2021
  • Support for generating and validating the Gradle Enterprise 2021.1 configuration model

1.0

28th October 2020
  • Support for generating and validating the Gradle Enterprise 2020.4 configuration model via the config-file command

Appendix B: Compatibility with Gradle Enterprise

Compatibility between versions of Gradle Enterprise and the Gradle Enterprise Admin CLI can be found here.

Appendix C: Gradle Enterprise Admin CLI JAR downloads