Transparent Endpoint Injection

Introduction

LocalStack provides Transparent Endpoint Injection, which enables seamless connectivity to LocalStack without modifying your application code targeting AWS. The DNS Server resolves AWS domains such as *.amazonaws.com including subdomains to the LocalStack container. Therefore, your application seamlessly accesses the LocalStack APIs instead of the real AWS APIs. For local testing, you might need to disable SSL validation as explained under Self-signed certificates.

Motivation

Previously, your application code targeting AWS needs to be modified to target LocalStack. For example, the AWS SDK client for Python called boto3 needs to be configured using the environment variable AWS_ENDPOINT_URL, which is available within Lambda functions in LocalStack:

client = boto3.client("lambda", endpoint_url=os.environ['AWS_ENDPOINT_URL'])

For supported AWS SDKs (including boto3 since 1.28.0), this configuration happens automatically without any custom code changes.

Currently, no application code changes are required to let your application connect to local cloud APIs because Transparent Endpoint Injection uses the integrated DNS Server to resolve AWS API calls to target LocalStack.

Configuration

This section explains the most important configuration options summarized under Configuration.

Disable transparent endpoint injection

If you do not wish to use Transparent Endpoint Injection in LocalStack Pro, opt out using:

DISABLE_TRANSPARENT_ENDPOINT_INJECTION=1

This option disables DNS resolution of AWS domains to the LocalStack container and prevents Lambda from disabling SSL validation. If Transparent Endpoint Injection is not used, the AWS SDK within Lambda functions might connect to the real AWS API. Transparent Endpoint Injection is only available in LocalStack Pro.

Alternatively, specific AWS endpoints can be resolved to AWS while continuing to use Transparent Endpoint Injection. Refer to the DNS server configuration for skipping selected domain name patterns.

Self-signed certificates

In LocalStack Pro and Lambda, Transparent Endpoint Injection automatically disables SSL certificate validation of the AWS SDK for the most common Lambda runtimes including Python, Node.js, and Java (SDK v1). For other services and unsupported Lambda runtimes, you may have to configure your AWS clients to accept self-signed certificates because we are repointing AWS domain names (e.g., *.amazonaws.com) to localhost.localstack.cloud. For example, the following command fails with an SSL error:

$ aws kinesis list-streams
SSL validation failed for https://kinesis.us-east-1.amazonaws.com/ [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate (_ssl.c:1076)

whereas the following command works:

$ PYTHONWARNINGS=ignore aws --no-verify-ssl kinesis list-streams
{
"StreamNames": []
}

Disabling SSL validation depends on the programming language and version of the AWS SDK used. For example, the boto3 AWS SDK for Python provides a parameter verify=False to disable SSL verification. Similar parameters are available for most other AWS SDKs.

For Node.js, you can set this environment variable in your application, to allow the AWS SDK to talk to the local APIs via SSL:

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"

If you are using the Java AWS SDK v2 in Lambda, LocalStack will per default use bytecode instrumentation to disable certificate validation, so the endpoint injection can work. You can opt out of this behavior by setting LAMBDA_DISABLE_JAVA_SDK_V2_CERTIFICATE_VALIDATION=0. Opting out will lead to certificate errors when using the AWS SDK without manually overriding the endpoint url to point to LocalStack.

Current Limitations

• The mechanism to disable certificate validation for these requests is not currently functional with Go Lambdas. To work around this issue, you’ll need to manually set your endpoint when creating your AWS SDK client, as detailed in our documentation on the Go AWS SDK.