diff --git a/content/en/user-guide/tools/transparent-endpoint-injection/_index.md b/content/en/user-guide/tools/transparent-endpoint-injection/_index.md index 9c3eae6978..e943ec583c 100644 --- a/content/en/user-guide/tools/transparent-endpoint-injection/_index.md +++ b/content/en/user-guide/tools/transparent-endpoint-injection/_index.md @@ -1,17 +1,255 @@ --- title: "Transparent Endpoint Injection" linkTitle: "Transparent Endpoint Injection" -weight: 10 +weight: 9 description: > Transparently inject local endpoints into AWS SDKs and redirect your AWS calls to LocalStack aliases: - /tools/local-endpoint-injection/ + - /tools/local-endpoint-injection/dns-server/ + - /user-guide/tools/transparent-endpoint-injection/patched-sdks/ + - /user-guide/tools/transparent-endpoint-injection/dns-server --- -In the community (open source) edition, the application code needs to configure each AWS SDK client instance with the target `endpoint URL` to point to the APIs on `localhost` or, in the case of Lambdas running in the context of LocalStack, the `endpoint URL` should point to `http://${LOCALSTACK_HOSTNAME}:${EDGE_PORT}`. +## Introduction -The Pro version provides two options for transparently making your application logic speak to the local APIs instead of real AWS (without having to change your production code): -1. integrated DNS server -2. patched AWS SDKs (**deprecated**) +LocalStack Community edition requires the application code to configure each AWS SDK client instance with the target endpoint URL. This URL should be set to point to the APIs on `localhost` or, in the case of Lambdas running in the context of LocalStack. Hence the endpoint URL should be directed to `http://${LOCALSTACK_HOSTNAME}:${EDGE_PORT}`. -More details can be found in the subsections below. +LocalStack Pro/Team version enables your application logic to seamlessly communicate with local APIs, eliminating the need to modify your production code, through an integrated DNS server. + +## DNS Server + +LocalStack's DNS server maps the domain name `localhost.localstack.cloud` to the LocalStack container. This allows easy connections from your container to LocalStack, as well as from resources like Lambda, ECS, or EC2 to LocalStack. The transparent execution mode allows your application code to automatically interact with LocalStack APIs instead of the real AWS APIs. + +Upon container startup, the log output will display the IP address of the local DNS server. If the host allows binding to port 53, the LocalStack CLI will expose port 53 from the container to the host with the IP address set to `127.0.0.1`. If binding to port 53 is not possible on the host, the port won't be exposed. + +Regardless of port binding capabilities, the DNS server within the LocalStack container is bound to the address `0.0.0.0`, making it accessible for other containers within the same Docker network to utilize the DNS server. + +For more in-depth information, refer to the [Network Troubleshooting guide]({{< ref "references/network-troubleshooting/endpoint-url#from-your-container" >}}). + +## Configuration + +If you encounter issues while running LocalStack due to problems with the DNS server, you have several options for configuration. + +### Disabling the DNS Server + +To disable the DNS server, you can set the `DNS_ADDRESS` variable to `0` using this command: + +{{< command >}} +$ DNS_ADDRESS=0 +{{< / command >}} + +{{< alert title="Warning" color="warning" >}} +This configuration is not recommended as it prevents the resolution of `localhost.localstack.cloud` to the LocalStack container. +{{< / alert >}} + +### Specifying Redirected URLs + +You can define specific URLs to be redirected to LocalStack by setting a hostname regex with the `DNS_LOCAL_NAME_PATTERNS` variable, like this: + +{{< command >}} +$ DNS_LOCAL_NAME_PATTERNS='.*(ecr|lambda).*.amazonaws.com' +{{< / command >}} + +With this setup, the LocalStack DNS server will only redirect domains related to ECR and Lambda to LocalStack, while other domains will be resolved using the `$DNS_SERVER`. This configuration is useful for hybrid setups where some API calls (e.g., ECR, Lambda) are directed to LocalStack, while others target real AWS. + +{{< alert title="Warning" color="warning">}} +We do not recommend connecting to real AWS from within LocalStack. You should avoid using real AWS credentials anywhere in your LocalStack setup. +{{< /alert >}} + +### Setting a Custom DNS Server + +You have the option to manually specify the DNS server to which queries that are not redirected should be forwarded. For instance: + +{{< command >}} +$ DNS_SERVER=1.1.1.1 +{{< / command >}} + +By default, LocalStack uses the Google DNS resolver at `8.8.8.8`. + +## Self-signed certificates + +When configuring transparent execution mode using DNS, it's important to note that you might encounter SSL certificate validation issues when working with your application's AWS SDK. This is due to a technical limitation resulting from the SSL certificate validation process, as we redirect AWS domain names (e.g., `*.amazonaws.com`) to `localhost`. For example, the following command will fail with an SSL error: + +{{< command >}} +$ 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) + +{{< / command >}} + +However, you can work around this issue using the following command: + +{{< command >}} +$ PYTHONWARNINGS=ignore aws --no-verify-ssl kinesis list-streams + +{ + "StreamNames": [] +} + +{{< / command >}} + +Disabling SSL validation depends on the programming language and version of the AWS SDK you are using. For instance, the [AWS SDK for Python (`boto3` )](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#boto3.session.Session.client) offers a `verify=False` parameter to disable SSL verification. Most other AWS SDKs also provide similar parameters for this purpose. + +For Node.js, you can allow the AWS SDK to communicate with the local APIs over SSL by setting the following environment variable in your application: + +{{< command >}} +process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0" +{{< / command >}} + +{{< alert title="Warning" color="warning">}} +Disabling SSL validation may have unintended consequences and security risks. It should only be used for local testing and never in a production environment. +{{< /alert >}} + +## System DNS configuration + +To enable transparent execution mode, your system should be set up to utilize the predefined DNS server. This configuration is essential if you intend to test code that runs directly on your system against LocalStack instead of AWS. The specific steps for configuration depend on your operating system. + +{{< alert title="Warning" color="warning">}} +Exercise caution when modifying your system's network configuration, as it may lead to unintended consequences. +{{< /alert >}} + +### macOS + +On macOS, you can configure it through the Network System Settings, while on Linux, you usually configure it by adjusting `/etc/resolv.conf` as follows: + +```text +nameserver 0.0.0.0 +``` + +The example above should be adapted to the actual IP address of the DNS server. You can also set a custom IP address by defining the `DNS_ADDRESS` environment variable (e.g., `DNS_ADDRESS=127.0.0.1`). + +If you need host access to DNS, it's important that Docker can expose port 53 from the LocalStack container to your host. This is only possible if there are no other processes listening on port 53. + +One common macOS process that listens on port 53 is `mDNSResponder`, which is a part of the [Bonjour protocol](https://developer.apple.com/bonjour/). You can check if any program is listening on a specific port using the following command: + +```bash +# sudo is required if the port is < 1024 +[sudo] lsof -P -i : | grep LISTEN +# e.g. sudo lsof -P -i :53 | grep LISTEN +``` + +If `mDNSResponder` is listening on port 53, the output will resemble the following: + +{{< command >}} +$ sudo lsof -P -i :53 | grep LISTEN + +mDNSRespo 627 _mdnsresponder 54u IPv4 0xbe20f6c354a1802d 0t0 TCP *:53 (LISTEN) +mDNSRespo 627 _mdnsresponder 55u IPv6 0xbe20f6c34d8b9d75 0t0 TCP *:53 (LISTEN) + +{{< / command >}} + +If you encounter this situation, you can disable "Internet Sharing" in system preferences, which should in turn disable Bonjour and `mDNSResponder`. + +### Linux + +Configuring LocalStack on Linux depends on your network manager/DNS configuration. You can either use the LocalStack CLI command or manually configure the DNS server. When correctly configured, only requests for the specified domain names will be routed to LocalStack, while all other queries will resolve as usual. + +#### systemd-resolved + +On many modern systemd-based distributions, such as Ubuntu, systemd-resolved is used for name resolution. LocalStack provides a CLI command to facilitate this scenario. To use systemd-resolved with LocalStack domain resolution, start LocalStack with `DNS_ADDRESS=127.0.0.1` as environment variable. This configuration allows LocalStack to bind port 53 on 127.0.0.1, while systemd-resolved binds its stub resolver to 127.0.0.53:53, avoiding conflicts. + +Once LocalStack is running, you can test the DNS server using the following commands: + +{{< command >}} +$ dig @127.0.0.1 s3.amazonaws.com +$ dig @127.0.0.53 s3.amazonaws.com +{{< / command >}} + +The first command should return an A record of `127.0.0.1`, while the second should return the actual AWS DNS result. + +To set up systemd-resolved and LocalStack, run: + +{{< command >}} +$ localstack dns systemd-resolved +{{< / command >}} + +To revert the changes, execute: + +{{< command >}} +$ localstack dns systemd-resolved --revert +{{< / command >}} + +{{< alert title="Note">}} +You need sudo privileges to execute these commands. +{{< /alert >}} + +This command configures the DNS server for the bridge interface of the Docker network where LocalStack is running, mapping it to the LocalStack container's IP address. It also sets up the DNS route to exclusively route specific DNS names (and their subdomains) to the LocalStack DNS. The configured domain names include: + +- `~amazonaws.com` +- `~aws.amazon.com` +- `~cloudfront.net` +- `~localhost.localstack.cloud` + +#### Manual configuration + +If you prefer to perform these actions manually, identify the bridge interface and container IP of your LocalStack container using `docker inspect localstack_main` for the IP address and `docker inspect network` for the interface name. + +The interface name is typically the first 12 characters of the network ID, prefixed with `br-` (e.g., `br-0ae393d3345e`) if it's not explicitly mentioned. If you're using the default bridge network, it's typically `docker0`. + +Configure the DNS resolver for the bridge network: + +{{< command >}} +$ resolvectl dns +{{< / command >}} + +Set the DNS route to route only the previously mentioned domain names (and their subdomains) to LocalStack: + +{{< command >}} +$ resolvectl domain ~amazonaws.com ~aws.amazon.com ~cloudfront.net ~localhost.localstack.cloud +{{< / command >}} + +In both cases, you can use `resolvectl query s3.amazonaws.com` or `resolvectl query example.com` to check which interface your DNS requests are routed through, ensuring that only the specified domains (and their subdomains) are directed to LocalStack. + +#### Other resolution settings + +The method for setting a DNS server can vary depending on your Linux distribution. In some systems, you can directly edit `/etc/resolv.conf`, similar to the [macOS configuration]({{< ref "#mac-os" >}}). + +If your `/etc/resolv.conf` gets overwritten by a service, you might be able to install and enable/start `resolvconf` and specify the nameserver in `/etc/resolvconf/resolv.conf.d/head` with `nameserver 127.0.0.1`. This will prepend the specified line in the resolv.conf file, even after changes. + +{{< alert title="Note">}} +Using these options, all DNS requests are forwarded to LocalStack, except for queries that don't need modification (typically, all but specific AWS domains). LocalStack does not store or share any forwarded DNS requests, except potentially in local logs in exceptional cases or in debug mode. +{{< /alert >}} + +## DNS Rebind Protection + +If you depend on your local network's DNS, your router or DNS server might restrict requests due to DNS Rebind Protection. This protective feature is typically enabled by default in routers and DNS servers like pfSense, OPNSense, OpenWRT, AVM FritzBox, and possibly others. Some vendors may permit upstream responses within the 127.0.0.0/8 range, such as OpenWRT. + +{{< alert title="Note" >}} +When using the LocalStack DNS server, DNS rebind protection should not pose any issues. +{{< / alert >}} + +You can verify the functionality of your DNS setup by resolving a subdomain of `localhost.localstack.cloud` with the following command: + +{{< command "hl_lines=16">}} +$ dig test.localhost.localstack.cloud + +; <<>> DiG 9.16.8-Ubuntu <<>> test.localhost.localstack.cloud +;; global options: +cmd +;; Got answer: +;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 45150 +;; flags: qr rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 1 + +;; OPT PSEUDOSECTION: +; EDNS: version: 0, flags:; udp: 65494 +;; QUESTION SECTION: +;test.localhost.localstack.cloud. IN A + +;; ANSWER SECTION: +test.localhost.localstack.cloud. 10786 IN CNAME localhost.localstack.cloud. +localhost.localstack.cloud. 389 IN A 127.0.0.1 + +;; Query time: 16 msec +;; SERVER: 127.0.0.53#53(127.0.0.53) +;; WHEN: Fr Jän 14 11:23:12 CET 2022 +;; MSG SIZE rcvd: 90 + +{{< /command >}} + +If the DNS resolves the subdomain to your localhost (127.0.0.1), your setup is functioning correctly. If not, please review your router or DNS configuration to confirm if Rebind Protection is active or [enable the LocalStack DNS on your system]({{< ref "#system-dns-configuration" >}}). + +## Customizing internal endpoint resolution + +The DNS name `localhost.localstack.cloud`, along with its subdomains like `mybucket.s3.localhost.localstack.cloud`, plays a crucial internal role in LocalStack for routing requests between components, such as a Lambda container and the LocalStack APIs. + +For detailed instructions on how to customize this internal DNS name, refer to the [Route53 documentation]({{< ref "route53" >}}). diff --git a/content/en/user-guide/tools/transparent-endpoint-injection/dns-server.md b/content/en/user-guide/tools/transparent-endpoint-injection/dns-server.md deleted file mode 100644 index c8d6345eff..0000000000 --- a/content/en/user-guide/tools/transparent-endpoint-injection/dns-server.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: "DNS Server" -categories: ["LocalStack Pro", "Tools", "DNS"] -weight: 6 -description: > - Use LocalStack as DNS server to redirect AWS queries to LocalStack -aliases: - - /tools/local-endpoint-injection/dns-server/ ---- - -All versions of LocalStack include a DNS server that resolves the domain name `localhost.localstack.cloud` to the LocalStack container. -This enables seamless connectivity from your container to LocalStack, or from created compute resources like Lambda, ECS or EC2 to LocalStack. -In addition, LocalStack Pro supports transparent execution mode, which means that your application code automatically accesses the LocalStack APIs as opposed to the real APIs on AWS. - -When the system starts up, the log output contains the IP address of the local DNS server. -If port 53 can be bound on the host, the LocalStack CLI will publish port 53 from the container to the host on IP address `127.0.0.1`. -Otherwise it will not publish port 53 to the host. -Regardless of whether the port can be bound or not, the DNS server is bound to address `0.0.0.0` of the LocalStack container so other containers within the same docker network can use the DNS server. -See the [Network Troubleshooting guide]({{< ref "references/network-troubleshooting/endpoint-url#from-your-container" >}}) for more details. - -## Configuration - -If you experience problems when running LocalStack and the DNS server is the issue, you can disable the DNS server using: - -```bash -DNS_ADDRESS=0 -``` - -{{< alert title="Warning" color="warning" >}} -We do not recommend this configuration since this disables resolving `localhost.localstack.cloud` to the LocalStack container. -{{< / alert >}} - -You can also specify which exact URLs should be redirected to LocalStack by defining a hostname regex like: - -```bash -DNS_LOCAL_NAME_PATTERNS='.*(ecr|lambda).*.amazonaws.com' -``` - -Using this configuration, the LocalStack DNS server only redirects ECR and Lambda domains to LocalStack, and the rest will be resolved via `$DNS_SERVER`. This can be used for hybrid setups, where certain API calls (e.g., ECR, Lambda) target LocalStack, whereas other services will target real AWS. - -{{< alert title="Warning" color="warning">}} -We generally do not recommend connecting to real AWS from within LocalStack, in fact you should avoid using real AWS credentials anywhere in your LocalStack apps. Use this configuration with caution. -{{< /alert >}} - -There is the possibility to manually set the DNS server all not-redirected queries will be forwarded to: - -```bash -DNS_SERVER=1.1.1.1 -``` - -Per default, LocalStack uses the Google DNS resolver at `8.8.8.8`. - -## Self-signed certificates - -When you configure transparent execution mode using DNS, you may still have to configure your application's AWS SDK to accept self-signed certificates. -This is a technical limitation caused by the SSL certificate validation mechanism, due to the fact that we are repointing AWS domain names (e.g., `*.amazonaws.com`) to `localhost`. For example, the following command will fail with an SSL error: - -{{< command >}} -$ 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) -{{< / command >}} - -whereas the following command works: - -{{< command >}} -$ PYTHONWARNINGS=ignore aws --no-verify-ssl kinesis list-streams -{ - "StreamNames": [] -} -{{< / command >}} - -Disabling SSL validation depends on the programming language and version of the AWS SDK used. For example, the [`boto3` AWS SDK for Python](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#boto3.session.Session.client) 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: - -```node.js -process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0" -``` - -{{< alert title="Warning" color="warning">}} -Disabling SSL validation may have undesired side effects and security implications. -Make sure to use this only for local testing, and never in production. -{{< /alert >}} - -## System DNS configuration - -In order to use transparent execution mode, the system needs to be configured to use the predefined DNS server. -This is necessary if you want to test code running directly on your system against LocalStack, instead of AWS. -The configuration depends on the operating system. - -{{< alert title="Warning" color="warning">}} -Please be careful when changing the network configuration on your system, as this may have undesired side effects. -{{< /alert >}} - - -### macOS - -In macOS it can be configured in the Network System Settings, under Linux this is usually achieved by configuring `/etc/resolv.conf` as follows: - -```text -nameserver 0.0.0.0 -``` - -The example above needs to be adjusted to the actual IP address of the DNS server. You can also configure a custom IP address by setting the `DNS_ADDRESS` environment variable (e.g., `DNS_ADDRESS=127.0.0.1`). - -If you require access to DNS from the host, `docker` must be able to publish port 53 from the LocalStack container to your host. -It can only do this if there are no other processes listening on port 53. - -A common macOS process that listens on port 53 is `mDNSResponder`, which is part of the [Bonjour protocol](https://developer.apple.com/bonjour/). -To find out if a program is listening on a port, run the following command: - -```bash -# sudo is required if the port is < 1024 -[sudo] lsof -P -i : | grep LISTEN -# e.g. sudo lsof -P -i :53 | grep LISTEN -``` - -If `mDNSResponder` is listening on port 53, the output looks like - -``` -$ sudo lsof -P -i :53 | grep LISTEN -mDNSRespo 627 _mdnsresponder 54u IPv4 0xbe20f6c354a1802d 0t0 TCP *:53 (LISTEN) -mDNSRespo 627 _mdnsresponder 55u IPv6 0xbe20f6c34d8b9d75 0t0 TCP *:53 (LISTEN) -``` - -If this is the case, you can disable "Internet Sharing" in system preferences, which should disable Bonjour and therefore `mDNSResponder`. - -{{< alert title="Note">}} -From LocalStack version 2.0.0, LocalStack does not fail to start when ports on the host cannot be bound. -This includes port 53 for DNS. -{{}} - -### Linux - -In Linux, the configuration depends on your network manager/DNS configuration. - -#### systemd-resolved - -On many modern systemd-based distributions, like Ubuntu, systemd-resolved is used for name resolution. -LocalStack provides a CLI command for exactly this scenario. -To use systemd-resolved and the LocalStack domain resolution, try the following steps. - -Start LocalStack Pro with `DNS_ADDRESS=127.0.0.1` as environment variable. -This makes LocalStack bind port 53 on 127.0.0.1, whereas systemd-resolved binds its stub resolver to 127.0.0.53:53, which prevents a conflict. -Once LocalStack is started, you can test the DNS server using `dig @127.0.0.1 s3.amazonaws.com` versus `dig @127.0.0.53 s3.amazonaws.com`, the former should return an A record `127.0.0.1`, the latter the real AWS DNS result. - -Run: -{{< command >}} -$ localstack dns systemd-resolved -{{< / command >}} - -To revert, please run: -{{< command >}} -$ localstack dns systemd-resolved --revert -{{< / command >}} - -{{< alert title="Note">}} -You need sudo privileges to execute this command. -{{< /alert >}} - -This command sets the DNS server of the bridge interface of the docker network LocalStack currently runs in to the LocalStack container's IP address. -(The command does not work with host networking or without LocalStack running for this reason.) -Also, it configures the DNS route to exclusively (and only) route the following DNS names (and its subdomains) to the LocalStack DNS: - -```text -~amazonaws.com -~aws.amazon.com -~cloudfront.net -~localhost.localstack.cloud -``` - -If you want to perform this action manually, please do the following steps: - -1. Find out the bridge interface and container IP of your LocalStack container. - Use `docker inspect localstack_main` to get the IP address and network, then `docker inspect network` to get the interface name. - If the interface name is not mentioned, it is usually the first 12 characters of the network ID prefixed with `br-`, like `br-0ae393d3345e`. - If you use the default bridge network, it is usually `docker0`. - -1. Configure the DNS resolver for the bridge network: - - {{< command >}} - # resolvectl dns - {{< / command >}} - -3. Set the DNS route to route only the above mentioned domain names (and subdomains) to LocalStack: - - {{< command >}} - # resolvectl domain ~amazonaws.com ~aws.amazon.com ~cloudfront.net ~localhost.localstack.cloud - {{< / command >}} - -In both cases, you can use `resolvectl query s3.amazonaws.com` or `resolvectl query example.com` to check which interface your DNS request is routed through, to confirm only the above mentioned domains (and its subdomains) are routed to LocalStack. - -When correctly configured, either using the LocalStack CLI command or manually, only the requests for the mentioned domain names are routed to LocalStack, all other queries will resolve as usual. - -#### Other resolution settings - -Depending on your Linux distribution, the settings to set a DNS server can be quite different. -In some systems, directly editing `/etc/resolv.conf` is possible, like described in [macOS]({{< ref "#mac-os" >}}). -If your `/etc/resolv.conf` is overwritten by some service, it might be possible to install and enable/start `resolvconf` and specify the nameserver in `/etc/resolvconf/resolv.conf.d/head` with `nameserver 127.0.0.1`. -This will prepend this line in the resolv.conf file even after changes. - -{{< alert title="Note">}} -Using these options, every DNS request is forwarded to LocalStack, which will forward queries it does not need to modify (in essence all but certain aws domains). -LocalStack will not store or share any forwarded DNS requests, except maybe in the local logs on exceptions/in debug mode. -{{< /alert >}} - -## DNS Rebind Protection - -If you rely on your local network's DNS, your router/DNS server might block requests due to the DNS Rebind Protection. -This feature is enabled by default in pfSense, OPNSense, OpenWRT, AVM FritzBox, and potentially also other devices. -Some of the vendors might allow upstream responses in the 127.0.0.0/8 range (like OpenWRT). - -{{< alert title="Note" >}} -If you are using the LocalStack DNS server, DNS rebind protection should not cause any issues. -{{< / alert >}} - -You can check if your DNS setup works correctly by resolving a subdomain of `localhost.localstack.cloud`: -{{< command "hl_lines=16">}} -$ dig test.localhost.localstack.cloud - -; <<>> DiG 9.16.8-Ubuntu <<>> test.localhost.localstack.cloud -;; global options: +cmd -;; Got answer: -;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 45150 -;; flags: qr rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 1 - -;; OPT PSEUDOSECTION: -; EDNS: version: 0, flags:; udp: 65494 -;; QUESTION SECTION: -;test.localhost.localstack.cloud. IN A - -;; ANSWER SECTION: -test.localhost.localstack.cloud. 10786 IN CNAME localhost.localstack.cloud. -localhost.localstack.cloud. 389 IN A 127.0.0.1 - -;; Query time: 16 msec -;; SERVER: 127.0.0.53#53(127.0.0.53) -;; WHEN: Fr Jän 14 11:23:12 CET 2022 -;; MSG SIZE rcvd: 90 -{{< /command >}} - -If the DNS resolves the subdomain to your localhost (127.0.0.1), your setup is working. -If not, please check the configuration of your router / DNS if the Rebind Protection is active or [enable the LocalStack DNS on your system]({{< ref "dns-server#system-dns-configuration" >}}). - -## Customizing internal endpoint resolution - -The DNS name `localhost.localstack.cloud` (and any subdomains like `mybucket.s3.localhost.localstack.cloud`) is used internally in LocalStack to route requests, e.g., between a Lambda container and the LocalStack APIs. - -Please refer to the steps in the [Route53 docs]({{< ref "route53" >}}) for more details on how the internal DNS name can be customized. diff --git a/content/en/user-guide/tools/transparent-endpoint-injection/patched-sdks.md b/content/en/user-guide/tools/transparent-endpoint-injection/patched-sdks.md deleted file mode 100644 index ac6e19804b..0000000000 --- a/content/en/user-guide/tools/transparent-endpoint-injection/patched-sdks.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Patched AWS SDKs for Lambdas (Deprecated)" -categories: ["LocalStack Pro", "Tools"] -weight: 6 -description: > - Using patched SDKs in Lambdas to transparently redirect AWS API calls to LocalStack -aliases: - - /tools/local-endpoint-injection/patched-sdks/ ---- - -{{< alert title="Warning" color="warning">}} -Patched AWS SDKs for Lambdas are **deprecated** and only used by the old lambda provider. -The new lambda provider (active since LocalStack 2.0) uses DNS-based domain resolution (except for the Ruby runtime).
-Please refer to [Lambda providers]({{< ref "user-guide/aws/lambda" >}}) for more details about the new Lambda implementation. -{{< /alert >}} - -The Lambda runtime in LocalStack uses patched AWS SDKs, which are configured to target the local APIs instead of the real AWS. -This behavior is enabled by default for most Lambda runtimes when using LocalStack Pro. - -Assuming you had a Python Lambda handler that attempts to list all S3 buckets. In the past, you had to manually configure the `endpoint_url` parameter on the boto3 client (and potentially use environment switches for dev/prod in your test code): -```python -import boto3 -def handler(event, context): - client = boto3.client("s3", endpoint_url="http://localhost:4566") - print(client.list_buckets()) -``` - -With the patched AWS SDKs, it now becomes possible to deploy your unmodified production code to LocalStack, simply creating a boto3 client with default settings. The invocations of the boto3 client will be automatically forwarded to the local APIs: -```python -import boto3 -def handler(event, context): - client = boto3.client("s3") - print(client.list_buckets()) -``` - -{{< alert title="Note">}} -This functionality only works when using the SDKs provided by the Lambda execution environment itself. -If you choose to ship your own SDKs with your Lambda or using a layer, it will fallback to the [DNS based transparent execution]({{< ref "dns-server" >}}) if enabled, since those SDK versions will not be patched. -{{< /alert >}} - -This feature works by patching the AWS SDKs in the docker images, which provide the execution environment for Lambdas within LocalStack. - -The main advantage of this mode is, that no DNS magic is involved, and SSL certificate checks do not have to be disabled. - -## Configuration - -If you want to disable this behavior, and use the DNS server to resolve the endpoints for AWS, you can disable this behavior by using: - -```bash -TRANSPARENT_LOCAL_ENDPOINTS=0 -``` - -## Supported Runtimes -Currently, LocalStack supports patching the SDKs for the following runtimes: - -* Python (using boto3) -* NodeJS -* Ruby -* Java - -Also, these patched SDKs are only available in the following Lambda execution modes: - -* docker -* docker-reuse - -This feature is currently not supported for custom Lambda container images.