How To Host A Dynamic Web Page With PowerShell On AWS Lambda and API Gateway

AWS Lambda and API Gateway play a crucial role in Amazon’s serverless compute offerings. In this tutorial we will create a Lambda PowerShell Function and associate it with Amazon’s API Gateway to demonstrate how these services work together to create a dynamic web page. In continuation of the last article I wrote How To Create An AWS Lambda PowerShell Function the Easy Way — Using Docker we will be utilizing the Docker container I created as it has all the dependencies required to publish PowerShell code to AWS Lambda.

What is PowerShell?

PowerShell is a cross-platform object oriented scripting language released in 2006 by Microsoft and is used for scripting and automating tasks. AWS began support for PowerShell in September of 2018.

What is AWS Lambda?

Lambda is a serverless compute offering from Amazon which allows us to run code without having to worry about the underlying infrastructure. It is highly scalable and cost effective.

What is API Gateway?

API Gateway is an Amazon service that manages custom APIs. In this tutorial we will use it as an SSL Endpoint for our dynamic web page.

Prerequisites

  • AWS Access Key Id and Secret Access Key
  • Access to Docker or Docker Desktop

Deploying the PowerShell Code To AWS Lambda

Open a shell and start the Docker container.

docker run -dit --name powershell-builder rickjacobo/lambda-powershell-project-builder

Enter the powershell-builder’s shell.

docker exec -it powershell-builder pwsh

Create a new project and follow the prompts to setup the environment.

./create-project.ps1

Follow the prompts to setup the project.

Enter Project Name: powershell-lambda-apigateway-dynamic-web-page
Enter AWS Region: us-east-1
Enter Desired Memory Allocation ie, 198: 1024
AWS Access Key ID [None]: xxxxxxx
AWS Secret Access Key [None]: xxxxxxxx
Default region name [None]:us-east-1
Default output format [None]:json

You will then be redirected to the project directory. Launch the edit script and add your code to the project.

./edit-powershell-lambda-apigateway-dynamic-web-page.ps1

If you followed along to this point you should be editing your script with vim. If you need some help with VIM check out the resource section below for a link to the VIM Cheat Sheet.

Paste the following code into the PowerShell script and save the file.

$Name = ($LambdaInput.queryStringParameters | ConvertTo-Json | ConvertFrom-Json).name
$Name = "$Name" + "!"
$HTML = @"
<html>
<head>
    <title>Hello, World!</title>
</head>
<body>
    <center><h1>Hello, $Name</h1></center>
</body>
</html>
"@
$HTML = @{
    'statusCode' = 200;
    'body' = $HTML;
    'headers' = @{'Content-Type' = 'text/html'}
}
$HTML

We are now ready to push our code to AWS using the ./publish-powershell-lambda-apigateway-dynamic-web-page.ps1 script

./publish-powershell-lambda-apigateway-dynamic-web-page.ps1

When prompted to enter an IAM role for the Lambda function select 1 to create a new IAM role.

1) *** Create new IAM Role ***
1
Enter name of the new IAM Role:
powershell-lambda-apigateway-dynamic-web-page

When prompted to select and IAM policy select 1

Select IAM Policy to attach to the new role and grant permissions
1) AWSLambdaFullAccess (Provides full access to Lambda, S3, DynamoDB, CloudWatch Metrics and ...)
1

Setting up API Gateway

We can now configure API Gateway — Begin by searching for API Gateway in the console and selecting API Gateway.

Select “APIs” from the top left menu section, navigate to REST API, and click on “Build”

Enter the details as pictured below and click on the Create API button (not pictured).

Click on the “Actions” drop down button and select “Create a Method”

Click on the “Actions” drop down button again and select “Create Method”. Create a GET method.

You will be directed to the “Setup” section in order to finish configuring the “GET” method. Setup the GET method with Lambda Proxy integration and select the Lambda function we created earlier.

Click on “GET” and then click on the “Method Request” header.

Expand “URL Query String Parameters” and enter “name”.

Note: the name parameter will be used by the PowerShell script $Name variable as seen in the snippet of code we entered earlier.

$Name = ($LambdaInput.queryStringParameters | ConvertTo-Json | ConvertFrom-Json).name

Deploy the API

Obtain your URL from the Stages section. It will look like

https://<xxxxxxxxx>.execute-api.us-east-1.amazonaws.com/development

Navigate to your website and add a url parameter. In this example we will use “World”.

https://<xxxxxxxxx>.execute-api.us-east-1.amazonaws.com/development?name=World

If everything goes as expected our web page should return “Hello, World!”. Feel free to change the “name” parameter to something else and hit enter to see what happens.

https://<xxxxxxxxx>.execute-api.us-east-1.amazonaws.com/development?name=Rick

Thanks for reading!

Resources

How To Create An AWS Lambda PowerShell Function the Easy Way — Using Docker

Background

I’ve been working with PowerShell since its beginning and haven’t looked back since. Last year, while working on an serverless project for work, I decided to try Lambda on my own and deploy some PowerShell code to AWS to see how it works.

Fast forward to now…I started working more with AWS on my own while studying for some certs. I jumped back into Lambda and was reminded of how tedious it was to setup my environment for publishing my PowerShell code to AWS. Unfortunately, I didn’t take any notes last time and wanted to ensure I next time around I could just focus on the code. That is where Docker comes in to save the day and our story begins — I created a Docker container with all the dependencies required to publish your PowerShell code to AWS in as little as 5 minutes with a few scripts included to help streamline the process.

So, jump on in and give it a try.

See It In Action

Assumptions

  • You have an AWS Account and access to you “Access Key Id” and “Secret Access key”
  • You have access to Docker or Docker Desktop
  • You have some Docker know how

If you are lacking in either of these areas head on over to the Docker website and learn how to Get Started!

So, How Easy Is It To Publish My Code?

Really easy, check out the steps below…

Start the container

docker run -dit — name powershell-builder rickjacobo/lambda-powershell-project-builder

Access the container shell

docker exec -it powershell-builder pwsh

Create a project

./create-project.ps1

The create-project script will ask a few questions during setup to assist with

  • Setting up the PowerShell Lambda Project
  • Creating a script to edit your PowerShell code
  • Creating a script to publish your PowerShell
  • Adding your AWS credentials via the ‘aws configure’ cli

Add code to your project

./edit-<projectname>.ps1

This is the same as running

vi /<projectname>/<projectname>.ps1

If you don’t have any code readily available feel free to append the code below to <projectname>.ps1.

$Json = @"
{
"Message":"Hello, World!"
}
"@

$Json

Publish your code to AWS

./publish-<projectname>.ps1

That’s it — the container abstracts a lot of the complexity of getting started. Hopefully, you’ll give it a try.

Project Notes

  • The lambda-powershell-project-builder container has all the dependencies required to get started quickly with PowerShell on AWS Lambda
  • The create-project.ps1 script runs the Publish-AWSPowerShellLambda command with the values collected during the script execution and creates the edit and publish scripts on the fly based on your answers. Finally, it launches the ‘aws configure’ cli command for so you can enter your aws “Access Key Id” and “Secret Access key” which is required for publishing your Lambda application.
  • The publish-<project>.ps1 script run the Publish-AWSPowerShellLambda script with some sensible defaults

Project Links

Additional Links