Latest version: 1.8 (2023-09-13)
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.
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-<VERSION>.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:
-
A Docker runtime and CLI tools available
-
A machine with access to pull the
gradle/gradle-enterprise-admin-cli
image from DockerHub, or to have pulled it into a registry that can be accessed.
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)
--kube-ns=gradle-enterprise \(3)
[arguments]
1 | This makes your local Kubernetes client configuration available to the Docker container. Adjust if config is stored in different location. |
2 | A specific version of the tool can be selected by appending a tag. E.g. gradle/gradle-enterprise-admin-cli:1.3.1 . |
3 | The Kubernetes namespace Gradle Enterprise is deployed in. Adjust if using different namespace. |
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 "${HOME}/bundles:/home" \
gradle/gradle-enterprise-admin-cli \
--kube-ns=gradle-enterprise \
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:
# Admin CLI run as a JAR file:
alias gradle-enterprise-admin="java -jar /absolute/path/to/gradle-enterprise-admin-cli.jar --kube-url=https://my-k8s-cluster.example.com --kube-token=ABCD1234 --kube-ns=gradle-enterprise"
# Admin CLI run as a Docker container with statically mounted directory for files produced by commands:
alias gradle-enterprise-admin="docker run --rm -it -v ${HOME}/.kube/config:/kube-config:ro -v ${HOME}/admin-cli:/home gradle/gradle-enterprise-admin-cli --kube-ctx=my-k8s-cluster --kube-ns=gradle-enterprise"
# Admin CLI run as a Docker container with output directory mapping done on a command run time:
alias gradle-enterprise-admin="docker run --rm -it -v ${HOME}/.kube/config:/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.
backup Create and restore database backups backup create Create a database backup backup copy Copy a database backup to a local file backup restore Restore the database from a local backup file config-file Provides tools for authoring a Gradle Enterprise configuration file config-file hash Cryptographically hash a secret for storing in a config file config-file generate-key Create a key for symmetric encryption of secrets config-file encrypt Encrypt a secret value for storing in a config file config-file encrypt-all Encrypt all secrets of a config file config-file decrypt Decrypt an encrypted value from a config file config-file decrypt-all Decrypt all secrets of a config file config-file validate Verify that a config file is well-formed config-file schema Prints the JSON schema for Gradle Enterprise configuration files database Execute commands on the Gradle Enterprise database database check-index Check Gradle Enterprise database indexes for corruption database query Execute queries against the Gradle Enterprise database license Print license file details and convert between license file formats license convert Reads a Gradle Enterprise license in any format and writes back out it in a specified format support-bundle Create a support bundle for sending to Gradle support system System command to interact with Gradle Enterprise system disable-default-identity-provider Disable the default identity provider system get-default-system-password Get the default Gradle Enterprise system password system reset-system-password Reset Gradle Enterprise system password system stop Stop all Gradle Enterprise components system start Start Gradle Enterprise components system restart Restart Gradle Enterprise system test-notification Execute a notification test beta Commands currently in beta stage beta system System command to interact with Gradle Enterprise beta system prune-resources Prunes stale kubernetes object from previous releases
Appendix A: Release history
1.8
-
No changes
1.7.3
-
Update Alpine version to 3.18.0 in base image
1.7.2
-
Update JDK Docker base image to JDK 11.0.19
1.7.1
-
Fix Out of memory error when generating a support bundle
1.7
-
Add
system get-default-system-password
command to get the default system password
1.6.3
-
Fix database query errors not being reported
1.6.2
-
Admin CLI attempts to find a Gradle Enterprise installation if no namespace is provided
-
Admin CLI reports back if it can’t detect a GE instance when generating a support bundle
-
Update JDK Docker base image to JDK 11.0.18
1.6.1
-
Malformed license data does not prevent support bundle generation
1.6
-
Capture additional diagnostics in support bundles
-
Improve error handling when generating support bundles
-
Improve error reporting on backup upload failures
1.5.1
-
Fix
backup restore
command file transfer issue in 1.5
1.5
-
Add a
system restart
command to restart a Gradle Enterprise deployment in one command. -
Improve the speed of embedded database backup transfers
-
Update JDK Docker base image to JDK 11.0.17
1.4
-
The
database query
command fails if not exactly one of the--query
and--query-file
options are passed to it. -
If a custom shared database schema is configured, the
database query
command will use it when determining the search path for running queries. -
The
--no-output-file
option doesn’t cause a non-zero exit code when used from the Docker image. -
Backup commands fail fast when run against a user-managed database. When Gradle Enterprise is configured to connect to a user-managed database, administrators should consult their database service provider or database administrator to configure backups.
-
Admin CLI creates intermediate directories with the correct ownership.
-
backup copy
prints the local path on the installation host where backups are saved, when running in standalone-mode. -
Update JDK Docker base image to JDK 11.0.16
1.3.1
-
Mitigate RCE related to CVE-2022-30586
-
Update JDK Docker base image to JDK 11.0.15 to mitigate ECDSA vulnerability
1.3
-
Remove
get-installation-key
command
1.2.1
-
Handle file permissions correctly when run in a docker container
-
Treat absolute paths correctly during support bundle generation
1.2
-
Support for the Gradle Enterprise Helm-based deployment platform, including the
system
,backup
,support-bundle
,license
anddatabase
top-level commands
1.1
-
Support for generating and validating the Gradle Enterprise 2021.1 configuration model
1.0
-
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
-
gradle-enterprise-admin-1.8.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.7.3.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.7.2.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.7.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.7.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.6.3.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.6.2.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.6.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.6.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.5.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.5.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.4.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.3.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.3.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.2.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.2.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.1.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)
-
gradle-enterprise-admin-1.0.jar (SHA-256 checksum, PGP signature, PGP signature SHA-256 checksum)