Use awsEmulator.external when another process, Docker Compose, or a CI service owns the emulator. The plugin supplies its connection to resource tasks and opted-in consumers without starting or stopping it. Docker is not required on the Gradle machine.
Configure The Connection
Start the emulator separately and make its credentials file and PEM CA certificate bundle available on the machine running Gradle.
awsEmulator {
region.set("us-east-1")
external {
endpoint.set("https://localhost:9297")
credentialsFile.set(layout.projectDirectory.file("local-emulator/emulator_credentials"))
certificateFile.set(layout.projectDirectory.file("local-emulator/ca.pem"))
}
useWith(tasks.named<Test>("test"))
}
awsEmulator {
region.set('us-east-1')
external {
endpoint.set('https://localhost:9297')
credentialsFile.set(layout.projectDirectory.file('local-emulator/emulator_credentials'))
certificateFile.set(layout.projectDirectory.file('local-emulator/ca.pem'))
}
useWith(tasks.named('test'))
}
The external { … } block enables the connection. Set enabled.set(false) inside it to disable it conditionally. When configuring properties directly through awsEmulator.external, also set enabled to true.
| Property | Requirement |
|---|---|
|
Absolute HTTPS URL with a hostname or IP address and optional port. A trailing slash is allowed; paths, query strings, fragments, and embedded credentials are rejected. |
|
Readable AWS shared credentials file with a |
|
Readable PEM certificate bundle that trusts the endpoint. The server certificate must match the configured hostname or IP address. |
|
Defaults to |
The extension’s region, startupTimeoutSeconds, and workingDirectory still apply. Readiness waits up to startupTimeoutSeconds for HTTPS /__admin/health to return ok; it never launches the emulator. Docker settings, including image, platform, and port, are ignored. The endpoint selects the port.
Missing or invalid connection settings fail when a connection is needed. They never trigger a fallback to Docker. Applying the plugin, listing tasks, and skipping consumers do not require connection files or a reachable endpoint.
Consumers And Resource Setup
Existing useWith wiring works for Test, JavaExec, and Exec, including Spring Boot’s bootRunLocal and bootRunLocalDebug. Resource tasks, Kinesis worker processes, named resource sets, and seedAwsEmulator use the external connection too.
Both MANAGED and DEVELOPMENT select this same external instance for the configured runtime name. They do not provide separate state or automatic cleanup in external mode. Provisioning and fixture tasks still make their requested AWS resource changes; these persist after successful and failed builds. Use distinct resource names when consumers run concurrently. Resource sets selected in both modes can run once per mode against the same state.
Configure external within a named runtime to use an existing endpoint alongside independently managed runtimes in the same project. Named runtimes do not inherit the top-level external connection. Different names pointing to the same external endpoint still share its AWS state.
With useSharedRuntime, configure external on the selected owner project. The owner’s endpoint, files, region, and working directory apply to every participating project.
For SDK clients using a DNS endpoint, configure S3 path-style access, such as S3Client.builder().forcePathStyle(true), to avoid bucket-prefixed hostnames. The plugin’s own S3 tasks already use path-style access. Other SDK requirements are covered in credentials and TLS.
Lifecycle And Diagnostics
| Task | External connection behavior |
|---|---|
|
Check the supplied files and HTTPS health without Docker. |
|
Verify readiness and write shell/PowerShell connection scripts locally. |
|
Provision and seed the selected scenario without starting the emulator. |
|
Fail with an explanation that the emulator is managed externally. |
|
Fail at restart; scenario resource tasks cannot seed after that failure. |
Use the emulator’s actual owner to inspect its logs or stop/restart it.
Files And Configuration Cache
Credential values are read at execution time. The source credentials and certificate files are never copied, overwritten, or deleted. Keep them out of version control.
The plugin writes a host-side AWS configuration, certificate-only trust stores, and optional exports under workingDirectory/external/<connection-id>/. JVM consumers retain their selected JDK’s default trust and any custom trust store alongside the external certificate. Certificate and hostname verification remain enabled; Gradle daemon credentials and global TLS settings are unchanged.
Configuration-cache reuse is supported. Each new invocation reads the current source credentials and certificate again, so replacing their contents does not require reconfiguring the build. Generated local connection files remain after the build and can be deleted when no consumers are using them. Nothing is removed from the external emulator.
See the external example for a runnable build and connection properties.