Networking Migration Guide for LocalStack 3.0

Announcement
, ,
1

This guide demonstrates how to migrate your networking configuration for LocalStack 3.0.

:1st_place_medal: Try whether your scenario works with the default configuration before customizing it to your needs.

Major Changes

  1. The default container name for LocalStack is now localstack-main (previously localstack_main) to allow the use of the name in URLs.

  2. We are simplifying how to configure LocalStack by using:

    • GATEWAY_LISTEN to customize the bind address of LocalStack. It has the form <ip address>:<port>(,<ip address>:<port>)*. For example, GATEWAY_LISTEN=:4566,:5577 binds LocalStack to multiple ports. The default inside the LocalStack container is 0.0.0.0:4566 for Community users and 0.0.0.0:4566,0.0.0.0:443 for Pro users. Outside the LocalStack container (e.g., in host-mode for LocalStack developers), the default is 127.0.0.1:4566 for Community users and 127.0.0.1:4566,127.0.0.1:443 for Pro users.
    • LOCALSTACK_HOST to customize URLs returned by AWS services (e.g., SQS QueueUrl). It has the form <hostname>:<port> and one part can be optional. For example, LOCALSTACK_HOST=localstack-container returns URLs with the hostname localstack-container and LOCALSTACK_HOST=:5577 returns URLs with the port 5577. This can be useful when operating in container networks or behind enterprise proxies. The default is localhost.localstack.cloud:4566, which resolves to the LocalStack container using DNS.

  3. We are adopting the official custom endpoint configuration AWS_ENDPOINT_URL from AWS for LocalStack Integrations (e.g., awslocal) and LocalStack compute services (e.g., Lambda).

:bulb: Good to know: The DNS name localhost.localstack.cloud is the recommended way to reach to LocalStack. On your host machine, it resolves to localhost using a public DNS entry by LocalStack. In a compute container (e.g., within a Lambda function), it redirects to the LocalStack container using the LocalStack DNS.

Configure LocalStack Core

Do you configure any of these deprecated variables in your LocalStack Installation such as docker-compose.yml, LocalStack CLI, etc?

:1st_place_medal: Try whether your scenario works with the default configuration before customizing it to your needs.

  • Replace EDGE_BIND_HOST (default inside the LocalStack container: 0.0.0.0 and default outside the LocalStack container: 127.0.0.1) with GATEWAY_LISTEN. For example: EDGE_BIND_HOST=172.17.0.2 ⇒ GATEWAY_LISTEN=172.17.0.2 binds LocalStack to listen to the IP 172.17.0.2.
  • Replace EDGE_PORT (default: 4566) with GATEWAY_LISTEN. For example: EDGE_PORT=5577 ⇒ GATEWAY_LISTEN=:5577 binds LocalStack to listen to port 5577.
  • Replace EDGE_PORT_HTTP (default: 0) with GATEWAY_LISTEN. For example: EDGE_PORT_HTTP=5577 ⇒ GATEWAY_LISTEN=:5577 binds LocalStack to listen to port 5577. LocalStack 3.0 does not distinguish between HTTP and HTTPS.
  • USE_SSL (default: false) to switch between binding HTTP or HTTP is not required anymore because LocalStack does not distinguish between HTTP and HTTP since 1.0. However, USE_SSL (default: false) has been re-purposed and now determines whether LocalStack returns URLs using HTTP or HTTPS.
  • Replace HOSTNAME_EXTERNAL (default: localhost) with LOCALSTACK_HOST. For example: HOSTNAME_EXTERNAL=localstack-container ⇒ LOCALSTACK_HOST=localstack-container returns URLs returned from LocalStack (e.g., SQS QueueUrl) targeting the hostname localstack-container. Notice that LOCALSTACK_HOST supports subdomains by default. If you are in an environment that cannot resolve subdomains (e.g., sqs.localstack-container), configure the *_ENDPOINT_STRATEGY accordingly.

:point_right: Refer to our configuration overview for more details.

Configure LocalStack Integrations

Do you configure any of these deprecated variables in your LocalStack Integrations such as awslocal, cdklocal, tflocal, localstack-serverless, etc?

  • Replace LOCALSTACK_HOSTNAME (default: localhost) with AWS_ENDPOINT_URL (default: http://localhost:4566). For example: LOCALSTACK_HOSTNAME=172.17.0.2 ⇒ AWS_ENDPOINT_URL=http://172.17.0.2:4566
  • Replace EDGE_PORT (default: 4566) with AWS_ENDPOINT_URL (default: http://localhost:4566). For example: EDGE_PORT=5577 ⇒ AWS_ENDPOINT_URL=http:localhost:5577.
  • Replace USE_SSL (default: 0) with AWS_ENDPOINT_URL (default: http://localhost:4566). For example: USE_SSL=1 ⇒ AWS_ENDPOINT_URL=https:localhost:4566.

:point_right: Refer to the individual tools for more details.

Access Environment Variables in Compute Services

Do you access any of these deprecated variables in your compute services such as Lambda?

  • Replace LOCALSTACK_HOSTNAME (default: <LOCALSTACK_IP> such as 172.17.0.2) with AWS_ENDPOINT_URL (default: http://<LOCALSTACK_IP>:4566). The <LOCALSTACK_IP> depends on the networking configuration.
  • Replace EDGE_PORT (default: 4566) with AWS_ENDPOINT_URL (default: http://<LOCALSTACK_IP>:4566).

For example, manually configuring a boto3 client in Python changes from:

# Deprecated environment variables
client = boto3.client(
    "lambda",
    endpoint_url=f"http://{os.environ['LOCALSTACK_HOSTNAME']}:{os.environ['EDGE_PORT']}",
)

to the official AWS_ENDPOINT_URL:

# New official AWS_ENDPOINT_URL
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. This official configuration by AWS offers an alternative to our DNS-based transparent endpoint injection.

Alternatively, localhost.localstack.cloud reaches the LocalStack host through DNS-based routing.

Network Troubleshooting

:point_right: Refer to our network troubleshooting documentation for more details depending on your networking layout.