Deploying Serverless Golang APIs With The AWS CDK
After our last piece looking into Go Servers with Fiber, we are going to continue and take this to the next step: deploying a serverless API on AWS.
There is something important at this point that I need to mention: we are not going to use the Fiber library that we looked at in the last article. In fact, we are going to use Gin.
Why? There is support from AWS Labs that enables us to deploy Gin. Simple as that! Luckily, we will be taking one simple example from the Gin framework to get things up and running!
This tutorial expects that you have Golang installed and the AWS CDK for TypeScript.
Setting up the project
Inside of the terminal, we are going to set up a monorepo that contains a
infra folder for our AWS CDK infrastructure and a
functions folder to hold our Lambda functions:
Writing our Go lambda server
Let's jump into the
functions folder and make a folder for the Gin server that we will work in for the Lambda function!
Once we create the folder, we will add a simple
Inside of the Go file, let's add the following:
Let's go through this part-by-part!
- Import the required packages, including the dependencies required
- Declare a variable
- Write a
initfunction which handles the running of the Gin server
Handlerfunction that will deal with Gin when running with Lambda
mainentry function that starts the
init function is special function that is run prior to main during package initialization. Read more about init in this great article.
If you have not yet, be sure to
go get <package> for the non-standard library packages we are installed from GitHub.
Starting a Gin server is nice and straightforward too:
Here we are simple starting a server with only one GET route
/ping which simply returns some basic JSON.
This API is super, super simple, but the main focus is to get it up and running!
For us to be able to deploy this, we need to build the Go binary and follow some guidelines on how it needs to be built.
The guideline link above will show requirements for different systems, but in the case of Mac, you need to run
go build with the following environment variables:
Inline those environment variables means that they will be environment variables only while executing that line in the terminal.
Once you have run this, our
main binary output (from the
-o flag) will be what we need to reference when deploying via the AWS CDK.
Deploying our Go Lambda function using the CDK
Change back into our
infra folder from the root of the project and initialize a new Node project.
This will generate the
package.json file. If you want a reference, you can follow the layout I have in my
If you've have copied the above in, make sure you install the dependencies running
You'll also want to create a
infra/tsconfig.json file and add the following:
Finally, add a
infra/cdk.json file and add this:
These are all required config for transpiling the TypeScript and running the CDK.
Writing the infrastructure code
Now, inside of
infra/index.ts we will add our simple stack:
Important to note: above I have two
@ts-ignore comments. The first argument was throwing type errors which I didn't read too deep into... so I used
ts-ignore to silence them during build.
Here, we do the following:
- Import the required packages
- Export a class that the CDK app will synthesize
- Create a new
cdkpackage to pass to the class constructor
- Synthesize the app
The magic itself happens in the class we declare
GoAPILambdaStack. Inside of here, we need to accomplish three things:
- Zip up and store the assets in an S3 bucket that will be called at runtime
- Create the lambda function
- Add the lambda function to API Gateway to add an endpoint for us to access
I'm not going to dive too deep into number one and three. The important information that may seemingly come out of no where is in the Lambda constructor:
So let's explain the third options argument pass to the
- code: We are telling this value to get the code to execute from the lambda asset we created above. This will be the zip of our Golang function folder
- timeout: a simple max duration of 300s
- runtime: Here we tell the CDK we want to use the Go runtime supported in lambda
- handler: Here we define the binary output we generated that we want to call
With this simple code stack, we are ready to deploy!
Note: As this is a simple stack, I have opted just to keep it all in the one file. For best practices, I recommend checking out the open CDK repo if you want to define more structure.
Deploying the code
If you are using my
package.json example I provided above, there will be some scripts we can use to help run:
First, we can run
npm run build to compile our
index.ts file to
Once that is done, we can run
cdk synth followed by
cdk deploy to start running our deployment!
If successful, the CDK will give you a URL back in the terminal that we can now use to run our simple cURL. Grab it run it with the
/ping for our GET route and you can get back our expected
As a bonus, the lambda function will also send our logs to AWS CloudWatch. If you jump onto your AWS console and click through to the CloudWatch logs, you will end up with something similar to the following:
Congratulations! You have just deployed an incredibly useless serverless Go API! Now you can go forth and start adding your own routes and endpoints and make this simple Ping Pong API do some incredible things.
Today's post is a bit of a whirlwind into deploying a Go binary to AWS using the CDK to run a serverless API.
While brief, we have covered a lot of ground.
As always, these small projects kickstart the bigger applications, so I hope you are inspired to start running some neat Go lambda functions!
Resources and Further Reading
Image credit: Jr Korpa
1,200+ PEOPLE ALREADY JOINED ❤️️
Get fresh posts + news direct to your inbox.
No spam. We only send you relevant content.