The emulator uses signed requests over HTTPS. After readiness succeeds, the plugin configures each opted-in process with the current endpoint, region, credential paths, and TLS trust settings. JVM consumers additionally receive a combined trust store.

What The Plugin Supplies

Setting Supplied value

Endpoint

HTTPS on 127.0.0.1 at the selected port, or the configured external endpoint, through the SDK environment and JVM settings

Region

The configured awsEmulator.region

Credentials

The generated emulator_credentials file, or the supplied external credentialsFile

AWS config

A separate host-config file with host-side paths

TLS trust

The generated ca.pem or external certificateFile, and a consumer PKCS12 trust store combining default, custom, and emulator certificates

Metadata/discovery

EC2 metadata lookup and endpoint discovery disabled

Kinesis wire format

JSON through aws.cborEnabled=false and CBOR_ENABLED=false in opted-in JVMs

The plugin removes inherited AWS credential, profile, and service-endpoint environment overrides, along with corresponding configured JVM credential/endpoint properties. It does not change the Gradle daemon’s credentials or global trust settings.

Connection material is read or generated at execution time; credential values are not serialized into the configuration cache. Authentication remains enabled. Readiness checks validate the certificate and endpoint hostname. See existing emulators for using supplied files without Docker.

With Docker tunnel transport, the plugin copies generated connection files from the container to a private local directory and forwards HTTPS to a loopback endpoint in the Gradle runner. The same credential and TLS checks apply, including certificate and hostname verification.

Use Compatible SDK Clients

Use an SDK that supports external endpoint configuration. The runnable example verifies AWS SDK for Java v2 2.39.6. An SDK client that hardcodes an endpoint will keep using it.

For operations that use host prefixes, Java clients also need SdkAdvancedClientOption.DISABLE_HOST_PREFIX_INJECTION in their client override configuration:

import software.amazon.awssdk.core.client.config.SdkAdvancedClientOption;
import software.amazon.awssdk.services.sts.StsClient;

try (var sts = StsClient.builder()
        .overrideConfiguration(config -> config.putAdvancedOption(
            SdkAdvancedClientOption.DISABLE_HOST_PREFIX_INJECTION, true))
        .build()) {
    var identity = sts.getCallerIdentity();
}

The environment setting alone does not control host-prefix injection in Java. Owned runtimes use 127.0.0.1 to support S3 path-style routing. For external DNS endpoints, configure S3 clients with path-style access, such as forcePathStyle(true).

Explicit SDK credentials/endpoints and application-created SSL contexts can override the plugin’s values. Use normal SDK providers as shown in the example application.

Trusting Other HTTPS Services

Each opted-in Test or JavaExec task, including the companion’s local Spring Boot tasks, receives a combined trust store. It contains:

  • The selected Java launcher’s default certificates from lib/security/jssecacerts, if present, otherwise lib/security/cacerts.

  • Certificates from the consuming task’s custom trust store, when configured.

  • The current emulator’s CA certificate.

Custom certificates are added to the default roots. Configure a JKS or PKCS12 source store using standard JVM properties on the consuming task:

tasks.named<Test>("integrationTest") {
    systemProperty("javax.net.ssl.trustStore", layout.projectDirectory.file("tls/company.jks").asFile.absolutePath)
    systemProperty("javax.net.ssl.trustStoreType", "JKS")
    systemProperty("javax.net.ssl.trustStorePassword", providers.environmentVariable("COMPANY_TRUST_STORE_PASSWORD").get())
}

For Spring Boot, configure these properties on bootRunLocal and bootRunLocalDebug, or supply -Djavax.net.ssl…​ options through awsEmulator.springBoot.jvmArgs. The basic example also accepts -PexampleTrustStore=/path/to/store and EXAMPLE_TRUST_STORE_PASSWORD.

Trust properties supplied through jvmArgs, JVM argument providers, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, and _JAVA_OPTIONS are resolved immediately before launch. Command-line options take precedence over JAVA_TOOL_OPTIONS and JDK_JAVA_OPTIONS; _JAVA_OPTIONS takes precedence over them. Other environment options are retained. Relative trust-store paths resolve against the consuming task’s working directory. trustStoreType and trustStoreProvider are honored when supplied; providers must be available in the Gradle JVM to load the source store. A provider-backed store can use trustStore=NONE.

Unreadable stores, incorrect passwords, and unavailable providers fail before the application starts. The plugin does not modify source stores, disable certificate or hostname verification, or copy private keys. Applications configuring their own SSL context must supply their own appropriate trust managers.

The combined certificate-only PKCS12 files use a fixed integrity password supplied to the child JVM; they contain no source-store passwords or private keys. Files are generated under consumer-truststores/ in the runtime directory and are removed when that runtime stops. Distinct certificate sets have distinct file names, preventing consumers from overwriting each other’s trust. The source certificates are read again on every execution, including configuration-cache reuse.

The plugin’s own provisioning tasks use per-client trust and explicit emulator connections. Their TLS settings are separate from the consuming application’s JVM trust store.

Development Connection Files

For a development instance on port 9297, host-side files live under:

.aws-emulator/development/.aws/emulator/9297/
  emulator_credentials
  ca.pem
  truststore.p12
  host-config

Lifecycle tasks report the actual directory and endpoint. The emulator’s own config contains container paths, so host consumers should use the generated host-config instead. Starting a development instance alone does not configure JVM tasks; useWith selects the separate managed runtime.

Shell, PowerShell, And IDE Exports

Run exportAwsEmulatorConnection to start or reuse the persistent development instance and write two connection scripts. Default POSIX-shell usage:

./gradlew exportAwsEmulatorConnection
. .aws-emulator/development/connection.sh
aws --endpoint-url "$AWS_ENDPOINT_URL" sts get-caller-identity --no-cli-pager

PowerShell:

./gradlew exportAwsEmulatorConnection
. ./.aws-emulator/development/connection.ps1
aws --endpoint-url "$env:AWS_ENDPOINT_URL" sts get-caller-identity --no-cli-pager

The task prints the actual paths for custom working directories and shared runtime owners. Script paths and values are quoted for spaces, apostrophes, dollar signs, and other shell metacharacters. They contain connection settings and file paths, never credential values. Source them in a dedicated development shell: conflicting AWS credentials, profiles, web-identity/container-credential settings, and service endpoints are cleared from the shell at source time. They do not modify your AWS config files. Close the shell to discard its environment.

Exports and Exec consumers set AWS_ENDPOINT_URL, AWS_REGION, AWS_DEFAULT_REGION, AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE, AWS_CA_BUNDLE, and AWS_SDK_LOAD_CONFIG, together with the metadata/discovery controls above. Boto3 and AWS CLI use the AWS CA bundle; Node receives the emulator PEM through NODE_EXTRA_CA_CERTS, which adds it to Node’s default roots at process startup. This replaces any inherited NODE_EXTRA_CA_CERTS path. The plugin does not disable certificate or hostname validation. Libraries that ignore these settings need explicit per-client configuration; for example Python’s standard urllib accepts an SSL context created with cafile=os.environ["AWS_CA_BUNDLE"].

Launch the application or a fresh IDE process from the configured shell to inherit these values. Alternatively, copy the exported values into the IDE’s run environment and remove the same conflicting AWS overrides. Already-running IDE processes may retain their original environment. Java applications launched outside Gradle still need appropriate JVM trust-store configuration; Test and JavaExec automate the combined trust store described above.

Exports select development for owned runtimes because managed connection files are removed at the end of their Gradle consumers. Stop removes the development scripts and connection files; restart changes the credentials and may select another port. Regenerate and source exports after restart, then relaunch consumers. With useSharedRuntime, export and stop refer to the selected owner’s development instance. The repository’s examples/processes build demonstrates this workflow with Python, Node, and AWS CLI.

For an external connection, exports use the supplied endpoint and files and are written under workingDirectory/external/<connection-id>/. They do not start or stop anything. The supplied files and generated local exports remain after the build.

Upstream References