4 min.

How to access local resources within an API Gateway run on AWS SAM

This article clarifies how AWS SAM API Gateways access local resources and how local resources, isolated within AWS SAM API, communicate back to the origin

I encountered an issue with local resource communication when trying to access a local frontend application from the API Gateway using Puppeteer on AWS SAM. The plan was to navigate to a specific page on my local website using Puppeteer and then send a callback to the API Gateway to retrieve the necessary data for generating a PDF.


When I initially used the default frontend app and AWS SAM API Gateway addresses, respectively localhost:3001 and, the issues with communication were visible in the console:









failed: timeout 30000ms exceeded



However, in the production environment on the AWS cloud, where domain addresses were used, everything worked as expected. Because AWS SAM is intended to work and test locally, I decided to write an article that aims to help anyone seeking correct addressing also in a local environment.



Accessing local resources with AWS SAM API Gateway 


By external I refer to the API Gateway accessing my local website through the proxy of Puppeteer. It's considered external because the local API Gateway operates within Docker, necessitating a different approach to access local HOST resources. To connect to frontend website, which runs on the default address localhost:3001, you need to use a different address than the default, due to the encapsulated Docker environment.



How to find the correct address to access localhost services on the host machine from within a Docker container?


The address used to access localhost services from within a Docker container can vary depending on the Operating System. Typically, for Linux, it might be, while for Mac and Windows, it is usually host.docker.internal. Instead of guessing, you can easily verify this using the Docker CLI. Just execute the following command:


ip addr show docker0



Then, use the address displayed after the "inet" prefix.

Therefore, to access my frontend website from Puppeteer running on a Lambda function, facilitated by the local API Gateway, I would use:



await page.goto('', {waitUntil: 'networkidle0'});



To summarize, replace `localhost:3001` (or ``) with `` or whichever address is designated for accessing localhost services from Docker containers on your host machine.


Changing the address on the backend is not enough though. You will have to run your frontend website using the address; the implementation depends on the framework. For example, for Nuxt3, it suffices to add the following code in nuxt.config.ts:



export default defineNuxtConfig({
    devServer: {
        host: '',
        port: 3001



So, calling on port 3001 from a Dockerized Lambda will target on the host, hence communication will be successful.



Accessing AWS SAM API Gateway Using isolated Local Resources


Puppeteer can now correctly access my frontend website within a Docker encapsulation. However, a new problem arises: the page wants to access the same or another API Gateway to fetch some data required to generate a PDF. If you use the default address that AWS SAM runs the API Gateway on (usually localhost:3000), you will encounter a net::ERR_CONNECTION_REFUSED or 404 error - NOT FOUND. 


This issue occurs because Puppeteer, running within Lambda, once again doesn't have access to your API running on localhost. To make your API Gateway accessible to Docker, you will have to change the way it's run. This means adding the host interface and hosting the entire API on the same open address. Use the following command to start the API:



sam local start-api  --container-host-interface '' --host ''



Next, in the frontend website, change the address invoking data fetching from the original API Gateway (localhost:3000) to the one displayed after starting the API, usually or similar.


From now on, your Lambda, specifically, can access local resources, as well as local resources encapsulated in Lambda, can access Lambda.