Target Audience: TRE Operator

Connect a TRE Agent to a Submission Layer

This guide describes how to connect a TRE Agent to the Submission Layer using the TRE onboarding configuration. During onboarding, the Submission Layer automatically provisions a dedicated Keycloak service account for the TRE and generates a configuration file that the TRE Agent can import.

Prerequisites

Deploy at least one TRE Agent.
Connect the TRE Agent to TES backend.
Get TRE administrator login credentials from the Submission Layer administrator to sign in to the Submission Layer.
Get the Submission S3 API URL, Submission Keycloak URL, Submission API Address URL and Submission API Keycloak Secret from the Federation Operator.

Steps

Update the TRE Agent configuration:

Set the following configuration in the TRE Agent .env file:

Environment Variable	Description
`SubmissionS3ApiUrl`	Point to Submission Layer S3 server, used by TRE Agent. For example, `http://host-of-submission-layer:9000`.
`SUBMISSION_KEYCLOAK_URL`	The URL of the Submission Layer’s Keycloak server, for example, `http://keycloak:8080` (for default local Keycloak server) or `https://submission-keycloak.example.com` (for a production Submission Layer Keycloak server).
`SubmissionAPIAddressURL`	The Submission API address URL. For example, `http://host-of-submission-layer:5034`.
`SubmissionAPIKeyCloakSecret`	The OpenID secret for the Submission API Keycloak client `Dare-Control-API`.

Once a TES submission has finished executing and the outputs have been approved by an Output checker, the TRE Agent uses access keys with scoped privileges (only read/write access to the target bucket) to connect to the Submission S3 and copy over the outputs for the Researcher to access.

Download the TRE Onboarding Configuration

Sign in to the Submission Layer as the assigned TRE administrator.
Open the TRE tab and navigate to your TRE.
Download the Agent Onboarding Configuration JSON file by clicking the top right corner button Download Config.

The downloaded configuration contains:

One-time onboarding JWT
Submission API URL
Submission Keycloak realm metadata URL
TRE ID
TRE Name

Upload the Onboarding Configuration

Sign in to the TRE Agent UI.
Navigate to Deployment Admin tab.
Upload the onboarding JSON downloaded from the Submission Layer.

The TRE Agent will automatically:

Store the onboarding configuration in Vault.
Retrieve the TRE service account credentials using the one-time JWT.
Store the service account credentials securely in Vault.
Begin synchronising with the Submission Layer.

Verify the Connection

Once onboarding has completed successfully:

The TRE Agent will begin synchronising automatically.
Button in the top-right corner of the Deployment Admin page will display Sync Active
The TRE will appear Online in the Submission Layer.
From now on it will use the generated service account credentials to sync.

If the button in the top-right corner of the Deployment Admin page displays Enable Sync, the TRE Agent is not currently synchronising with the Submission Layer. First, verify that all health checks show Connected. If they do, select Enable Sync to manually start synchronisation.

The Submission Credentials page is still available as an alternative onboarding method. When credentials are entered manually, the TRE Agent authenticates using a Keycloak username and password instead of a generated service account. JSON-based onboarding is the recommended approach for new deployments.

Synchronisation

The TRE Agent synchronises with the Submission Layer every at a regular interval.

To change the synchronisation interval, a TRE Operator can update the syncSchedule setting in the TRE Agent configuration.

Health Checks

The TRE Agent performs health checks at a regular interval to verify that its connection to the Submission Layer and supporting services remains healthy. To change the health check interval, a TRE Operator can update the healthCheckSchedule setting in the TRE Agent configuration. The health check logs are kept by default for 30 days, a TRE Operator can adjust the duration by updating the daysBeforeHealthLogDeletion setting in the TRE Agent configuration.

During each health check, the TRE Agent verifies that:

The Submission Layer endpoint is valid and reachable.
The Data Egress endpoint is valid and reachable.
The TES endpoint is valid and reachable.
The RabbitMQ broker is valid and reachable.

If any of these checks fail, the TRE Agent automatically stops the Sync and Scan jobs to prevent synchronisation attempts with an invalid configuration.

Troubleshooting

The current health status is displayed in the Deployment Admin page under the Health Check Status tab, where each check indicates whether it is healthy and, if not, provides the reason for the failure.

Common failure messages include:

Health check message	Action
URL for Submission API is missing.	Configure the Submission API URL in the TRE Agent configuration.
Invalid URL for Submission API.	Check that the configured URL is correct and reachable.
Failed to reach Submission API.	Check that the Submission Layer is running and accessible by the TRE Agent.
TES API URL is missing.	Configure the TES API URL in the TRE Agent configuration.
Failed to reach TES API.	Check that the TES endpoint is running and accessible by the TRE Agent.
Not connected to RabbitMQ broker.	Check that RabbitMQ is running and that the configured host, port, and virtual host are correct.
Failed to reach RabbitMQ broker.	Check the error details displayed after the message. This may indicate incorrect RabbitMQ credentials, an incorrect virtual host, or that the broker cannot be reached.
Missing Egress Credentials.	Configure the Egress username and password in the TRE Agent configuration.
Invalid Egress Credentials.	Check that the configured Egress credentials are correct and that the Egress Keycloak service is available.

Once any configuration or connectivity issues have been resolved, the Synchronisation can be restarted from the Deployment Admin page by selecting Enable Sync.