Actually there’s an official Hello World document. But I’m not satisfied with the explanations provided for the AWS terms in it. So I wrote this, to bring the Hello World further, with more basic explanations (in the simplest words) to AWS services.

In this post, we will create a Lambda that echos the IP of the client.

Before getting started, let’s first look at what resources we have.

As a new user on AWS, one recieves 12 months free and always free products. For details, see here.

In order to build our Hello World App and make it publicly accessible through internet, we will need Lambda and API Gateway. First 1 million calls to Lambda per month are always free, but API Gateway calls will be charged after the first 12 months.


What is Lambda

Lambda is a packge of code. Lambda runs when called.


What is API Gateway

API Gateway connects user-side apps and the APIs somewhere else. API Gateway is able to receive, authenticate, pre-process, transform, and proxy user-side requests to the APIs. Then it do the almost same things to the return values from the APIs, and send them back to the user.


Start Building the Hello World

Note: use the official document as reference.

Firstly we choose the microservice-http-endpoint-python3 (this is not the Hello World blueprint used by the official document).

Then in the official document, we are asked to ‘do the following’, but there’s not enough explanations. So we need to have some more information on that here.

What is a Role (a.k.a IAM Role/Execution Role)
(IAM: AWS Identity and Access Management)

A role is carried by a user. A role is a set of permissions. When associating Lambda with a role, the permissions of the role is passed to the Lambda.

When we choose ‘Create new role from template(s)’ (as instructed in the document), we are actually: putting together one (or several) set(s) of permissions, storing them all in a newly created role, and then giving the role to the Lambda.

What are APIs, Resources, and Methods in API Gateway

API is, as its name suggests, API. An API contains a set of Resources. A Resource contains a set of Methods. A Resource can contain Child Resource(s). A Resource has a path, which constructs the invocation URL to the Resource. Then inside a Resource, each Method (HTTP GET/POST/etc.) maps user-side calls of the specific HTTP method, to the underlying API (the Lambda in our case).

When choosing security configuration during our Hello World Lambda creation, remember to choose ‘Open’, because we want it to be publicly accessible.

After creation, we don’t want to go through the manual test process in the document. We want to make it available for real use. So we modify the Lambda code to:

def respond(res):
    return {
        'statusCode': '200',
        'body': res,
        'headers': {
            'Content-Type': 'text/plain',
        },
    }


def lambda_handler(event, context):
    return respond(event['requestContext']['identity']['sourceIp'])

The official Hello World document did not tell us what event and context are. We also don’t know what we should return. In fact, the documentation for event and return value is here. And for context, see here.

Scrolling down the page containing your code, you may want to adjust the basic settings (memory, etc.) for your lambda. When done, save your modifications.

Now let’s try it! You can retrieve the invocation URL in the Triggers tab in your newly created Lambda; just click the little triangle in the API Gateway Trigger. Or otherwise, you can also see it from API Gateway page > Stages. Then do curl https://your-invoke-url, and you will see your IP returned!

You may also want to adjust settings in API Gateway. Just remember to do Actions > Deploy API after adjustments.

Our journey of Hello World ends here!


Some Extra Fun: Access with Custom Domain Name

We will introduce two ways for this here. The first is to use some service to make a 301/302 redirection to the API invoke URL, and the second is to do it with API Gateway.

Drawbacks for each method: the first method may be slower; the second does not support HTTP (only HTTPS is supported, if I didn’t miss anything).

For the second method, we need: a domain, an ACM (AWS Certificate Manager) certificate, and some configuration.

First go to ACM (just search for it in AWS console), and make sure the correct region is selected. If you are going to use edge optimized custom domain configuration, select N. Virginia; otherwise make it consistent with your API Gateway page. To change region, refer to the region configuration in the upper right corner of the page.

Then click request a certificate, and go through the process. After that, go back to API Gateway > Custom Domain Names. Create a custom domain name, and add a base path mapping (optional). For example, we can map https://ip.tld/ directly to the Lambda invoke URL https://some-aws-server.com/prod/SomeLambda. Finally, save, and we are all done.

P.S. If the ACM page says

The AWS Access Key Id needs a subscription for the service (Service: AmazonRoute53; Status Code: 403; Error Code: OptInRequired; Request ID: <HIDDEN>)

then most of the time just refresh the page for some times and this will be gone. Alternatively, opt in through the instructions sent to you via email.

P.S.2. If the pages says ‘unknown error’ when you create custom domain configuration, try switching to Regional config instead of Edge Optimized.