- Target Audience
- TRE Operator
- Time to read
- 15 min
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 admin credentials and server URLs](link to the specific configuration section) from the Federation Operator.
Connect TRE Agent to Submission S3 storage:
Set the following configuration values in the TRE .env file :
| Environment Variable | Description |
|---|---|
SubmissionS3RootUser | The root user for the Submission Layer S3 server. |
SubmissionS3RootPass | The root password for the Submission Layer S3 server. |
SubmissionS3ApiUrl | Point to Submission Layer S3 server, used by TRE Agent. For example,
|
SubmissionS3ConsoleUrl | The URL for the Submission Layer’s S3 admin console. For example,
|
Once a TES submission has finished executing and the outputs have been approved by an Output checker the TRE Agent uses these configuration details to connect to the Submission S3 and copy over the outputs for the Researcher to access.
Connect TRE Agent to Submission
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 from the top right corner.
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.
During each health check, the TRE Agent verifies that:
- The Submission Layer endpoint is reachable.
- The Egress endpoint is valid and reachable.
- The configured TES endpoint 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.
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.
Once any configuration or connectivity issues have been resolved, the Synchronisation can be restarted from the Deployment Admin page by selecting Enable Sync.