Introduction

I have been building GraphQL APIs in a Serverless environment for over 3 years now. I can't even imagine working with RESTful APIs anymore. Combine the power of GraphQL with the scalability of AWS Lambda, and you have a server that can handle infinite amounts of traffic.

In this tutorial, we will build and deploy a GraphQL server to AWS Lambda and access it via an API Gateway endpoint. We will use CloudFormation and the AWS CLI to deploy all our AWS Resources and application code.

What we'll cover

1. Build a GraphQL Server using Apollo
2. Deploy that GraphQL Server to Lambda
3. Use API Gateway to proxy requests to Lambda
4. Use CloudFormation to deploy application stack to AWS
5. Set up Lambda for local development.

TL;DR – You can get the full source code for the application from Github.

What is GraphQL?

GraphQL is a query language for describing APIs using a strongly typed schema system. A GraphQL server fulfills those queries using existing data. Following are a few of the main advantages of using GraphQL.

Query only what your application needs

Unlike REST APIs, GraphQL enables clients to query precisely and only what they need. The server fulfills the client’s request by returning only what the client is asking for.

GraphQL uses a strongly typed system

The strongly typed system of GraphQL enables users to introspect the entire schema. And the GraphQL API serves as clear documentation about the capabilities of the server and notifies you about errors during development.

You can compose your queries in a single request

With GraphQL, you can query multiple resources and get combined responses with a single request. With fewer requests, apps using GraphQL perform much faster.

What is AWS Lambda?

AWS Lambda is a compute service offered by AWS that lets you run your application code without having to manage any servers. AWS manages all the overhead like infrastructure, security, resources, operating system, and patches so developers can focus on just building the application.

Let’s get started…

Setting up the project

Let’s start by creating a project folder. Then, change into the directory and initialise a Node project. I am using node 10.x in the examples. You can install the Node version of your choice using asdf.

mkdir apollo-server-lambda-nodejs 
cd apollo-server-lambda-nodejs 
yarn init

Next, create a folder that houses all our source code.

mkdir src

Finally, create an index file inside the src directory that serves as the lambda handler.

cd src
touch index.js

Initialize node project

Populate the index file with the following code.

exports.handler = async () => {  
    return { 
        body: 'Hello from Lambda' 
    };
};

The above code is a very simple Lambda handler which will return Hello from Lambda when invoked. Let's first deploy our code to AWS Lambda.

Package the application code

Before we can deploy our code to Lambda, we need to create a zip of our application and upload it to an S3 bucket. We are using AWS CLI to create the bucket. Set up AWS CLI now by following this guide if you have not already done so.

Create an S3 bucket to use for deploying our code to Lambda. Pick a unique name for your S3 bucket. The bucket names are unique globally across all AWS Regions.

aws s3 mb s3://lambda-deploy-asln

Create an archive of the application using the zip command and verify the files inside the zip.

zip -rq dist-latest.zip src package.json 
zipinfo dist-latest.zip

Copy the zip file to S3 using the AWS CLI command.

aws s3 cp dist-latest.zip s3://lambda-deploy-asln/dist-latest.zip

Finally, use the following command to verify that the file exists in S3.

aws s3 ls s3://lambda-deploy-asln

Copy application package to S3

Now that we have deployed the packaged application to S3, next we need to set up our Lambda and API Gateway in AWS. In the next section, we'll use CloudFormation to set up all necessary AWS Resources.

Set up AWS lambda with API gateway proxy integration

CloudFormation is an AWS service that helps us to write infrastructure as code. CloudFormation makes it very simple to create and manage our application resources. Let’s use CloudFormation to define our stack.

Create a file named cloudformation.yml at the root of the project.

touch cloudformation.yml

Add the following code to the cloudformation.yml

---
Description: GraphQL server on AWS lambda

Parameters:
  Version:
    Description: Application version number
    Type: String

  BucketName:
    Description: S3 bucket name where the source code lives
    Type: String

Resources:
  LambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      Code:
        S3Bucket: !Ref BucketName
        S3Key: !Sub dist-${Version}.zip
      Handler: src/index.handler
      Description: GraphQL Apollo Server
      Role: !GetAtt LambdaExecutionRole.Arn
      Runtime: nodejs10.x
      Timeout: 10

  LambdaExecutionRole:
    Type: "AWS::IAM::Role"
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: "Allow"
            Principal:
              Service:
                - "lambda.amazonaws.com"
            Action:
              - "sts:AssumeRole"
      Policies:
        - PolicyName: "LambdaFunctionPolicy"
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
            - Effect: Allow
              Action:
              - logs:CreateLogGroup
              - logs:CreateLogStream
              - logs:PutLogEvents
              Resource: "*"

  GraphQLApi:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Name: apollo-graphql-api

  GraphQLApiResource:
    Type: 'AWS::ApiGateway::Resource'
    Properties:
      ParentId: !GetAtt GraphQLApi.RootResourceId
      RestApiId: !Ref GraphQLApi
      PathPart: 'graphql'

  GraphQLApiMethod:
    Type: 'AWS::ApiGateway::Method'
    Properties:
      RestApiId: !Ref GraphQLApi
      ResourceId: !Ref GraphQLApiResource
      AuthorizationType: None
      HttpMethod: POST
      Integration:
        Type: AWS_PROXY
        IntegrationHttpMethod: POST
        Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${LambdaFunction.Arn}/invocations

  GraphQLApiDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    Properties:
      RestApiId: !Ref GraphQLApi
      StageName: v1
    DependsOn:
      - GraphQLApiResource
      - GraphQLApiMethod

  GraphQLApiPermission:
    Type: 'AWS::Lambda::Permission'
    Properties:
      Action: lambda:invokeFunction
      FunctionName: !GetAtt LambdaFunction.Arn
      Principal: apigateway.amazonaws.com
      SourceArn: !Sub arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${GraphQLApi}/*

Outputs:
  ApiUrl:
    Description: Invoke url of API Gateway endpoint
    Value: !Sub https://${GraphQLApi}.execute-api.${AWS::Region}.amazonaws.com/v1/graphql

I know a lot is happening in this template. Let’s examine the code step by step.

Template Parameters

Firstly, we define some parameters that we use in the template. We can pass those variables as parameter overrides when deploying the CloudFormation Stack.

Description: GraphQL server on AWS lambda

Parameters:
  Version:
    Description: Application version number
    Type: String

  BucketName:
    Description: S3 bucket name where the source code lives
    Type: String

Lambda Function

We define our lambda function specifying the path from where it should pull the application code. This bucket is the same one we created earlier.

LambdaFunction:
    Type: AWS::Lambda::Function
    Properties:
      Code:
        S3Bucket: !Ref BucketName
        S3Key: !Sub dist-${Version}.zip
      Handler: src/index.handler
      Description: GraphQL Apollo Server
      Role: !GetAtt LambdaExecutionRole.Arn
      Runtime: nodejs10.x
      Timeout: 10

We want our Lambda function to be able to send application logs to AWS CloudWatch. Lambda requires special permissions to be able to write logs to CloudWatch. So we create a role that enables writing to CloudWatch and assign it to the Lambda function.

LambdaExecutionRole:
    Type: "AWS::IAM::Role"
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: "Allow"
            Principal:
              Service:
                - "lambda.amazonaws.com"
            Action:
              - "sts:AssumeRole"
      Policies:
        - PolicyName: "LambdaFunctionPolicy"
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
            - Effect: Allow
              Action:
              - logs:CreateLogGroup
              - logs:CreateLogStream
              - logs:PutLogEvents
              Resource: "*"

API Gateway

We also want an HTTP endpoint to invoke the lambda function. API Gateway can be used to create an HTTP endpoint. We can then configure API Gateway to proxy all incoming requests from the client to the Lambda function and send the response from Lambda back to the client.

Firstly, we create an API Gateway RestApi.

GraphQLApi:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      Name: apollo-graphql-api

Then, we create an API Gateway Resource, which accepts requests at /graphql.

GraphQLApiResource:
    Type: 'AWS::ApiGateway::Resource'
    Properties:
      ParentId: !GetAtt GraphQLApi.RootResourceId
      RestApiId: !Ref GraphQLApi
      PathPart: 'graphql'

Next, we configure the Resource to accept POST requests by creating an API Gateway Method and then we integrate it with Lambda.

GraphQLApiMethod:
    Type: 'AWS::ApiGateway::Method'
    Properties:
      RestApiId: !Ref GraphQLApi
      ResourceId: !Ref GraphQLApiResource
      AuthorizationType: None
      HttpMethod: POST
      Integration:
        Type: AWS_PROXY
        IntegrationHttpMethod: POST
        Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${LambdaFunction.Arn}/invocations

Finally, we create an API Gateway Deployment which deploys the API to the specified stage.

GraphQLApiDeployment:
    Type: 'AWS::ApiGateway::Deployment'
    Properties:
      RestApiId: !Ref GraphQLApi
      StageName: v1
    DependsOn:
      - GraphQLApiResource
      - GraphQLApiMethod

Lambda / API Gateway permission

At this point, we have both the Lambda function and API gateway configured correctly. However, API Gateway needs special permission to invoke a Lambda function. We permit API Gateway to invoke Lambda by creating a Lambda Permission resource.

GraphQLApiPermission:
    Type: 'AWS::Lambda::Permission'
    Properties:
      Action: lambda:invokeFunction
      FunctionName: !GetAtt LambdaFunction.Arn
      Principal: apigateway.amazonaws.com
      SourceArn: !Sub arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${GraphQLApi}/*

Finally, we export the API URL at the end of the template. We can use this URL to invoke calls to the Lambda.

Outputs:
  ApiUrl:
    Description: Invoke url of API Gateway endpoint
    Value: !Sub https://${GraphQLApi}.execute-api.${AWS::Region}.amazonaws.com/v1/graphql

Deploy CloudFormation stack to AWS

Now that we have the CloudFormation template ready let’s use the AWS CLI command to deploy it to AWS.

Run the following command in your console. Make sure to update the BucketName to whatever the name of the bucket you created earlier is.

aws cloudformation deploy \
  --template-file ./cloudformation.yml \
  --stack-name apollo-server-lambda-nodejs \
  --parameter-overrides BucketName=lambda-deploy-asln Version=latest \
  --capabilities CAPABILITY_IAM

Deploy CloudFormation stack to AWS

It might take some time to deploy the stack. Lambda function should be ready to start taking requests when the deployment finishes.

Verify API Gateway and Lambda are working as expected

Now that we have deployed our CloudFormation Stack let us verify if everything is working as expected. We need the API Gateway URL to send a request to our Lambda Function. The API URL we exported in the CloudFormation template comes in handy here.

Run the following command to print the API URL in the command line.

aws cloudformation describe-stacks \
--stack-name=apollo-server-lambda-nodejs \
--query "Stacks[0].Outputs[?OutputKey=='ApiUrl'].OutputValue" \
--output text

Describe CloudFormation Stack

Now, use the curl command to invoke the API URL. You should get "Hello from Lambda" back from the server.

curl -d '{}' https://o55ybz0sc5.execute-api.us-east-1.amazonaws.com/v1/graphql

Invoke AWS Lambda

Add deploy script for easier deployment

You might have noticed that we ran a whole bunch of commands to package and deploy our application. It would be very tedious to have to run those commands every time we deploy the application. Let’s add a bash script to simplify this workflow.

Create a directory called bin at the root of the application and add a file named deploy.

mkdir bin 
touch bin/deploy

Before we can execute the script, we need to set correct file permissions. Let’s do that by running the following command.

chmod +x bin/deploy

Create deploy script

At this point, our directory structure should look like in the screenshot below.

Current directory structure

Add the following code to the file.

#!/bin/bash

set -euo pipefail

OUTPUT_DIR=dist
CURRENT_DIR=$(pwd)
ROOT_DIR="$( dirname "${BASH_SOURCE[0]}" )"/..
APP_VERSION=$(date +%s)
STACK_NAME=apollo-server-lambda-nodejs

cd $ROOT_DIR

echo "cleaning up old build.."
[ -d $OUTPUT_DIR ] && rm -rf $OUTPUT_DIR

mkdir dist

echo "zipping source code.."
zip -rq $OUTPUT_DIR/dist-$APP_VERSION.zip src node_modules package.json

echo "uploading source code to s3.."
aws s3 cp $OUTPUT_DIR/dist-$APP_VERSION.zip s3://$S3_BUCKET/dist-$APP_VERSION.zip

echo "deploying application.."
aws cloudformation deploy \
  --template-file $ROOT_DIR/cloudformation.yml \
  --stack-name $STACK_NAME \
  --parameter-overrides Version=$APP_VERSION BucketName=$S3_BUCKET \
  --capabilities CAPABILITY_IAM

# Get the api url from output of cloudformation stack
API_URL=$(
  aws cloudformation describe-stacks \
  --stack-name=$STACK_NAME \
  --query "Stacks[0].Outputs[?OutputKey=='ApiUrl'].OutputValue" \
  --output text
)

echo -e "\n$API_URL"

cd $CURRENT_DIR

OK, let’s break down what’s going on in this script.

We start by defining some variables. We generate the archive file inside the dist directory. We set the app version to the current timestamp at which the script runs. Using the timestamp, we can make sure that the version number is always unique and incremental.

#!/bin/bash

set -euo pipefail

OUTPUT_DIR=dist
CURRENT_DIR=$(pwd)
ROOT_DIR="$( dirname "${BASH_SOURCE[0]}" )"/..
APP_VERSION=$(date +%s)
STACK_NAME=apollo-server-lambda-nodejs

We then clean up any old builds and create a new dist directory.

echo "cleaning up old build.."
[ -d $OUTPUT_DIR ] && rm -rf $OUTPUT_DIR

mkdir dist

Then we run the zip command to archive the source code and its dependencies.

echo "zipping source code.."
zip -rq $OUTPUT_DIR/dist-$APP_VERSION.zip src node_modules package.json

Next, we copy the zip file to the S3 bucket.

echo "uploading source code to s3.."
aws s3 cp $OUTPUT_DIR/dist-$APP_VERSION.zip s3://$S3_BUCKET/dist-$APP_VERSION.zip

Then we deploy the CloudFormation stack.

echo "deploying application.."
aws cloudformation deploy \
  --template-file $ROOT_DIR/cloudformation.yml \
  --stack-name $STACK_NAME \
  --parameter-overrides Version=$APP_VERSION BucketName=$S3_BUCKET \
  --capabilities CAPABILITY_IAM

Finally, we query the CloudFormation Stack to get the API URL from the CloudFormation Outputs and print it in the console.

# Get the api url from output of cloudformation stack
API_URL=$(
  aws cloudformation describe-stacks \
  --stack-name=$STACK_NAME \
  --query "Stacks[0].Outputs[?OutputKey=='ApiUrl'].OutputValue" \
  --output text
)

echo -e "\n$API_URL"

Deploy to AWS using the deploy script

Let’s try out the deployment using the deploy script. The script expects the S3_Bucket variable to be present in the environment. Run the following command to run the deployment. When the deployment is successful, the script will output the API URL that we can use to invoke the lambda.

S3_BUCKET=lambda-deploy-asln ./bin/deploy

Run the deploy script

To simplify this even further, let’s invoke it using yarn. Add the following in your package.json.

"scripts": {
  "deploy": "S3_BUCKET=lambda-deploy-asln ./bin/deploy"
}

Hereafter we can simply run yarn deploy to initiate deployments.

Improve workflow with local Lambda and API Gateway

We frequently modified the application code while working on our application. Right now, deploying to AWS us-east-1 region takes me around 10 seconds. I am on a 40Mb/s upload speed internet connection.

Time to deploy becomes more significant as the size of the application grows. Having to wait 10 seconds or more to realize I have made a syntax error is not productive at all.

Let’s fix this by setting up the lambda function locally and invoke it using a local API Endpoint. AWS SAM CLI enables us to do just that. Follow the instruction on this page to install it.

Once done, from the root of the project, run the following command.

sam local start-api --template-file cloudformation.yml

Start local development server

The local endpoint is now available at http://localhost:3000. We can use this endpoint to send requests to our local Lambda.

Open another terminal and run the following command to send a request. You should see the response from our local Lambda function.

curl -d '{}' http://localhost:3000/graphql

Invoke local lambda function

Finally, add the following lines in the scripts section of the package.json.

"dev": "sam local start-api --template-file cloudformation.yml"

Hereafter we can run the yarn dev command to start the dev server.

Set up the GraphQL server in Lambda

Without further talking, let’s jump right into the code and build the GraphQL server.

Start by installing the dependencies. We are using Apollo Server to build our GraphQL server. Apollo Server is an open-source implementation of GraphQL Server.

yarn add apollo-server-lambda graphql

Replace the content of src/index.js with the following code.

const { ApolloServer, gql } = require('apollo-server-lambda');

const typeDefs = gql`
  type Query {
    user: User
  }

  type User {
    id: ID
    name: String
  }
`;

const resolvers = {
  Query: {
    user: () => ({ id: 123, name: 'John Doe' })
  }
};

const server = new ApolloServer({ typeDefs, resolvers });

exports.handler = server.createHandler();

Here, we define a schema which consists of a type User and a user query. We then define a resolver for the user query. For the sake of simplicity, the resolver returns a hardcoded user. Finally, we create a GraphQL handler and export it.

To perform queries to our GraphQL server, we need a GraphQL client. Insomnia is my favourite client. However, any other GraphQL client should be just fine.

Now, let’s run a query to ensure our server is working as expected.

Create a new GraphQL request in Insomnia.

Create new GraphQL request

Configure GraphQL request

Add the following query in the body and submit the query to http://localhost:3000. Assuming your dev server is still running, you should see the following response from the GraphQL server.

Perform GraphQL request to Local Server

Now that we've verified everything is working fine in the local server let’s run the following command to deploy the GraphQL server to AWS.

yarn deploy

Deploy server to AWS

The API URL is outputted in the console once the deployment is complete. Replace the URL in Insomnia with the one from API Gateway. Rerun the query to see it resolve.

Perform GraphQL request to AWS Lambda

Summary

Congratulations, you have successfully deployed a GraphQL Server in AWS Lambda purely using CloudFormation. The server can receive GraphQL requests from the client and return the response accordingly.

We also set up the development environment for local development without adding many dependencies.

If you liked this tutorial, please share it with your network.

So let me offer you some quick "getting started" help based on part of the content in my latest Pluralsight course.

First of all, if you're planning to manage your CloudFormation stacks through the AWS CLI rather than the Management Console, I discuss the basics in this article. Once that's all taken care of, you'll be ready for anything.

Start simple:

$ aws s3 ls
2019-11-03 13:16:59 athena5905
2019-02-03 18:01:42 book-3939
2014-07-01 18:52:32 elasticbeanstalk-ap-northeast-1-426397493112
2014-08-28 16:57:49 elasticbeanstalk-us-east-1-426497493912
2019-05-04 22:17:50 ltest236
2018-07-15 15:52:30 mybucket99688223
2017-07-25 17:06:43 nextcloud3239027

"aws" in that example tells your shell that you want what comes next to be handled by the AWS CLI. The "s3" I type next tells the CLI that I'll be using the S3 service - that's Amazon's Simple Storage Service. Finally, "ls" or "list" is the command I'd like to run against that service.

The CLI, using the account authentication variables that the configure tool added to my environment, will now hurry off and access my account, in this case retrieving the names of all of my buckets.

Predictably, you tell AWS that you're looking to work with CloudFormation using "cloudformation." If I just run that without specifying a command, I'll get an error message:

aws cloudformation
usage: aws [options] <command> <subcommand> [<subcommand> ...] [parameters]
To see help text, you can run:

  aws help
  aws <command> help
  aws <command> <subcommand> help
aws: error: the following arguments are required: operation

But it's an important message, as it tells us how to access the inline documentation. Context-sensitive help is available at each layer.

See what happens if you add "help" after "cloudformation". You'll get a brief description and then a list of all the available subcommands.

$ aws cloudformation help

CLOUDFORMATION()                                              CLOUDFORMATION()
NAME
       cloudformation -
DESCRIPTION
AWS  CloudFormation  allows you to create and manage AWS infrastructure deployments predictably and repeatedly. You can use AWS  CloudFormation to  leverage AWS products, such as Amazon Elastic Compute Cloud, Amazon Elastic Block Store, Amazon Simple Notification Service,  Elastic  Load Balancing,  and Auto Scaling to build highly-reliable, highly scalable, cost-effective applications without creating or configuring the  underlying AWS infrastructure.
With  AWS  CloudFormation, you declare all of your resources and dependencies in a template  file.  The  template  defines  a  collection  of resources  as  a single unit called a stack. AWS CloudFormation creates and deletes all member resources of the stack together and manages  all dependencies between the resources for you.
For  more information about AWS CloudFormation, see the AWS CloudFormation Product Page.
Amazon CloudFormation makes use of other  AWS  products.  If  you  need additional  technical information about a specific AWS product, you can find the product's technical documentation at docs.aws.amazon.com.

AVAILABLE COMMANDS
       o cancel-update-stack
       o continue-update-rollback
       o create-change-set
       o create-stack
       o create-stack-set
       o delete-change-set
       o delete-stack
       o delete-stack-instances
       o delete-stack-set
       o deploy
       o describe-account-limits
       o describe-change-set
       o describe-stack-events
       o describe-stack-instance
       o describe-stack-resource
       o describe-stack-resources
       o describe-stack-set
       o describe-stack-set-operation
       o describe-stacks
       o estimate-template-cost
       o execute-change-set
       o get-stack-policy
[...]

Now run the "describe-stacks" command. There are probably no live stacks in your account right now so you won't see any output.

But do that again, this time adding "help". This one will show you some options that'll let you filter or manipulate the data you get back. You could, for instance, point the CLI to one specific stack by using "--stack-name" followed by the name of an existing stack.

$ aws cloudformation describe-stacks
$ aws cloudformation describe-stacks help
NAME
       describe-stacks -
DESCRIPTION
       Returns  the  description for the specified stack; if no stack name was specified, then it returns the description for all the stacks created.
       NOTE:
          If the stack does not  exist,  an  AmazonCloudFormationException  is returned.
       See also: AWS API Documentation
       See 'aws help' for descriptions of global parameters.
       describe-stacks  is  a  paginated  operation. Multiple API calls may be issued in order to retrieve the entire data set  of  results.  You  can disable pagination by providing the --no-paginate argument.  When using --output text and the --query argument on  a  paginated  response,  the --query  argument  must  extract data from the results of the following query expressions: Stacks

SYNOPSIS
            describe-stacks
          [--stack-name <value>]
          [--cli-input-json <value>]
          [--starting-token <value>]
          [--max-items <value>]
          [--generate-cli-skeleton <value>]

OPTIONS
       --stack-name (string)
          The name or the unique stack ID that is associated with  the  stack,
          which are not always interchangeable:
[...]

$ aws cloudformation describe-stacks --stack-name myname

Those are tools that'll help you no matter what AWS service you're using. But looking specifically at CloudFormation, there are some valuable official collections of sample templates you should know about. JSON or YAML syntax being what they are, you probably won't want to start from an empty document.

Amazon itself has done a great job creating templates for us to work with. Your first stop should be the AWS CloudFormation Templates page. Here you'll find links to snippets and specific application frameworks and some more cutting edge content.

But right now I'd like to draw your attention to one of the "sample templates" organized by AWS service (this code comes from one of the Amazon EC2 examples).

The template begins with a free form description that helpfully tells us what kind of stack this will generate. We're also told that we could customize the template by using an existing Elastic IP address instead of one that's automatically generated.

{
  "AWSTemplateFormatVersion" : "2010-09-09",

  "Description" : "AWS CloudFormation Sample Template EC2InstanceWithSecurityGroupSample: Create an Amazon EC2 instance running the Amazon Linux AMI. The AMI is chosen based on the region in which the stack is run. This example creates an EC2 security group for the instance to give you SSH access. **WARNING** This template creates an Amazon EC2 instance. You will be billed for the AWS resources used if you create a stack from this template.",

You'll need to pass in the name of an existing KeyPair from the current region in your AWS account so you'll be able to open remote SSH into the Linux instance that will be launched. You can alternatively pass along that value from the command line.

The Parameters section is also where you define the EC2 instance type. The default is t2.small, but we'd be allowed to either swap that value out for any of the other AllowedValues in this document, or override it from the command line.

  "Parameters" : {
    "KeyName": {
      "Description" : "Name of an existing EC2 KeyPair to enable SSH access to the instance",
      "Type": "AWS::EC2::KeyPair::KeyName",
      "ConstraintDescription" : "must be the name of an existing EC2 KeyPair."
    },

    "InstanceType" : {
      "Description" : "WebServer EC2 instance type",
      "Type" : "String",
      "Default" : "t2.small",

If you scroll down through the Mappings section, we can see long lists of available hardware architectures and Amazon Machine Image identifiers for each region.

This is an optional section where you can insert your own non-standard values so, say, an image type would be launched based on a particular set of parameters - perhaps even a private AMI image. Such data is organized into key/value pairs.

  "Mappings" : {
    "AWSInstanceType2Arch" : {
      "t1.micro"    : { "Arch" : "HVM64"  },
      "t2.nano"     : { "Arch" : "HVM64"  },
      "t2.micro"    : { "Arch" : "HVM64"  },

The Resources section in this case defines your instance environment. The SecurityGroup, for instance, is configured to open the SSH port 22 but nothing else. The instance's public IP address is also associated with the new Elastic IP address that will be allocated.

    "InstanceSecurityGroup" : {
      "Type" : "AWS::EC2::SecurityGroup",
      "Properties" : {
        "GroupDescription" : "Enable SSH access via port 22",
        "SecurityGroupIngress" : [ {
          "IpProtocol" : "tcp",
          "FromPort" : "22",
          "ToPort" : "22",
          "CidrIp" : { "Ref" : "SSHLocation"}
        } ]
      }
    }
  },

One more important Amazon resource: Quick Starts. Strictly speaking the pre-built infrastructure stacks that are provided here to help you create more complex cloud deployments aren't directly related to CloudFormation. They were provided by third-party companies to simplify the process of building their infrastructure in within the AWS platform.

But the fact is that each one starts with its own unique CloudFormation template. Clicking through to look at actual examples will often lead you to the stack source code templates within a GitHub repo. This example shows us the tools you'd need to fire up a HashiCorp Console:

Either way, feel free to use these templates as learning tools - or browse through the selection to see if there's a stack there that happens to fit your needs.

There's much more administration goodness in the form of books, courses, and articles available at my bootstrap-it.com.

Installing the AWS CLI is actually quite simple. The best way to get it done is to head over to the AWS installation guide and follow instructions for your OS.

Right now they're pushing us towards version 2 of the CLI and I haven't seen any reason not to go along. I'm working with Linux so that's where I'd head next.

To get it done, I'll paste the curl command from the Amazon page into my Linux shell that'll download the package and write it to a local zip file, which I'll then unzip. That'll create a new directory called aws that'll contain a install script, which I can run using sudo to get admin privileges. I'll run aws --version to confirm everything worked as it was supposed to.

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
ls aws
sudo ./aws/install
aws --version

The next step will require one quick trip to the management console. You see, to authenticate the CLI to your account you'll need a valid access key. Now, the CLI has a "create-access-key" command that'll generate a new key, but that's only possible once I've authenticated. I'm sure you understand the problem with that.

You access the security credentials page from the drop-down account menu at the top of any page on the console. With your credentials in hand, you can run "aws configure." You'll be prompted to enter your access key ID and the secret key itself. If you like you can then choose a default AWS region and output format. The format won't be an issue so I'll leave it as default.

aws configure

That's it. Just to confirm it all worked, I'll list all the S3 buckets in my account. With that, we'll all set to get down to work in the next clip.

aws s3 ls

You may already know that Amazon's CloudFormation service exists to let you manage your application infrastructure by organising it into stacks of your AWS account resources.

The CloudFormation templates that define those stacks can be shared, edited, and launched anywhere, giving you predictable and reliable cloud application environments wherever and whenever you need them.

You may also know that you can mange your CloudFormation stacks both through the AWS Management Console and, as I discuss in my new Pluralsight course, Create and Manage Stacks with AWS CloudFormation Using the Command Line Interface, using the AWS CLI.

If you do choose to go with the AWS CLI – something I highly recommend – you'll need a way to gather key information about other account resources. But how you're expected to get that information through the CLI might, at first, not appear so obvious.

To show you what I mean, let's experiment with a more complex stack using a template that comes from the AWS documentation samples.

The Application Frameworks template set includes a template for auto scaled Linux servers that will come pre-provisioned with the Apache web server and the PHP scripting language, and a connection to a Multi-AZ RDS database instance running the MySQL database engine.

You can click View from that AWS documentation page and take a look at the template itself. There you'll see Parameters sections defining the VPC and subnets into which your instance will launch and the MySQL database name, user, and password.

It's critical that all the right services know those details because, otherwise, they won't be able to talk to each other. We'll have to figure out a way to add those values. To get things going, you can simply click to view the template (which you can see here), and copy the contents, pasting it into a new JSON file on your local machine.

You use the CLI to fire up a Cloudformation stack using the create-stack command. The command, however, takes a few arguments to pass important information. This minimal example shows you how to point CloudFormation to your JSON template file, a name to assign to your stack, and a valid SSH key so I'll be able to log into the instance it creates.

aws cloudformation create-stack \
  --template-body file://lamp-as.json \
  --stack-name lamp \
  --parameters \
  ParameterKey=KeyName,ParameterValue=mykey

The problem is that, if you were to run that command against the template in your JSON document, it would fail. That's because, as you'll no doubt remember from looking through the template, there are some extra parameters that need satisfying. Specifically, we'll need references to a VPC and to two subnets - and because this is a multi-availability-zone deployment, they'll need to be in different zones.

How will that work? It's the AWS CLI to the rescue. Need a VPC ID? Keeping in mind that VPCs are EC2 objects, you can run aws ec2 describe-vpcs and all the data you'll need - including the VPC ID - will magically appear. And subnets? Well more of the same, obviously. Just copy subnet IDs for any two of the subnets that will appear and you're in business.

aws ec2 describe-vpcs
aws ec2 describe-subnets

Now let's put all that information together into our new version of the create-stack command. You'll need to be careful with this as there are some nasty gotchas in the syntax.

aws cloudformation create-stack \
  --template-body file://lamp-as.json \
  --stack-name lamp-as \
  --parameters \
  ParameterKey=KeyName,ParameterValue=mykey \
  ParameterKey=VpcId,ParameterValue=vpc-1ffbc964 \
  ParameterKey=Subnets,ParameterValue=\'subnet-0e170b31,subnet-52d6117c\' \
  ParameterKey=DBUser,ParameterValue=myadmin \
  ParameterKey=DBPassword,ParameterValue=mypass23

The first new parameter is VPC-ID. But make sure you get the case right: using an uppercase D in Id will cause the whole thing to fail. I don't know why they make things so difficult to live with, but that's what we've got.

The next one is even more delicate. Since we need two subnets, we'll need to enter them on a single line separated by a comma - but no space. However, we'll also need to enclose the string within single apostrophes. But the CLI can't read apostrophes just like that, so we'll need to escape them using backslashes. Got that?

I'll also add those two database parameters: DBUser and my ultra secret, super cryptic DBPassword. Will it work? You betcha. But don't tell anyone how many times I had to try this without you watching before I got it right. Remember: failure is your friend.

When our stack is good and launched (which could take as long as half an hour), running describe-stacks will give us our website URL.

aws cloudformation describe-stacks

But that's not the whole story. I'm going to use another aws ec2 command - describe-instances this time - to get some information about the EC2 instances that were launched as part of this stack. This one will filter results, restricting output to only those instances that are currently running.

aws ec2 describe-instances \
  --filters Name=instance-state-name,Values=running \
  --query 'Reservations[*].Instances[*].{Instance:InstanceId,PublicIPAddress:PublicIpAddress}'

I happen to have no other instances running in this region, so only the CloudFormation instances will show up. Now I use --query to further filter the output to give me only the Instance IDs and public IP addresses of those instances. There are, as you would expect, exactly two running.

Just a taste - and most of it related specifically to CloudFormation - but I think you get the idea of how information gathering works using the AWS CLI.

There's much more administration goodness in the form of books, courses, and articles available at my bootstrap-it.com.