Guide to Deploy a Web App on AWS with Terraform and GitHub Actions

Bogdan Vlad — Wed, 22 Mar 2023 18:25:16 +0000

In this guide, I will show you how to deploy a very basic Express.js web application on AWS ECS using the Fargate launch type.

We will use Terraform to provision and manage all the resources needed, like the ECS cluster, VPC, ECR repository, IAM roles, etc. Then we'll use GitHub Actions to build the project and automatically deploy the application and infrastructure changes with the push of a new git tag.

Be aware that some AWS resources created throughout this guide are not free. The costs will depend on your region and the resources allocated. The initial costs will be lower if you qualify for the Free Tier.

Prerequisites

This guide assumes that you already have the following:

Some knowledge of Git, Terraform, AWS, and Docker
Terraform v1.4.1 (latest version at the time of writing)
AWS account
AWS credentials configured on your local machine
GitHub account and a git repository
Node.js installed on your machine.

A Brief Introduction to AWS ECS and Fargate:

ECS is a fully managed service for running and orchestrating Docker containers, so you don't have to worry about managing the underlying infrastructure. It allows you to create a cluster of EC2 instances and then run tasks on those instances where each task is a containerized application.

Fargate is a serverless compute engine for containers built on top of ECS. When you launch a task or a service on ECS with Fargate, it will provision all the necessary infrastructure to run your containers without the need to provision and manage the underlying EC2 instances.

You can read more about ECS and Fargate here and here.

Hello World! A very basic Express.js web application

In an empty git repository, create an app.js file and add the following:

const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

Next, create a Dockerfile file with the following:

FROM node:18
WORKDIR /usr/src/app
COPY package*.json app.js ./
RUN npm install
EXPOSE 3000
CMD ["node", "app.js"]

And finally, create a .gitignore file with the following:

node_modules
terraform/.terraform

Now, inside the project run npm init -y to auto generate a package.json file and then run npm install express.

That's it! You can run the app with the following command node app.js and then go to http://localhost:3000. You should see "Hello World!".

Infrastructure Provisioning with Terraform

Before starting, I must mention that some examples in this guide will use the open-source "Cloud Posse" terraform modules. These modules simplify the provisioning of AWS services and the underlying resources. They are well-maintained and have very good documentation. You can find more about the modules and what properties each module supports on their GitHub.

Ok, without further ado, let's jump to the Terraform code.

First, create a folder named terraform in your project and add the following files: backend.tf, main.tf, outputs.tf, provider.tf, variables.tf, and versions.tf.

Let's set up the backend where terraform will store its state. For this, you must first create an S3 bucket and give it any name, e.g., "tfstate-a123" (name must be globally unique). This is the only resource that we'll create without terraform.

Tip: You should enable Bucket Versioning on the S3 bucket to allow for state recovery if something goes wrong.

Add the following to the backend.tf:

# backend.tf

terraform {
  backend "s3" {
    bucket  = "tfstate-a123" # name of the s3 bucket you created
    key     = "production/terraform.tfstate"
    region  = "eu-west-1" # change to your region
    encrypt = true
  }
}

Now let's add the rest of the Terraform configuration. Add the following to the provider.tf:

# provider.tf

provider "aws" {
  region = var.region # value will be set later in variables.tf

  default_tags {
    tags = {
      ManagedBy = "Terraform"
    }
  }
}

This tells Terraform which provider to use and the region where to create the resources. Here we also set the default_tags property to automatically tag all resources that support tagging.

Next, let's set the required terraform version and the providers. Add the following to the versions.tf:

# versions.tf

terraform {
  required_version = ">= 1.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.0"
    }
  }
}

Now let's set the variables that we'll use throughout the code. Add the following to the variables.tf:

# variables.tf

variable "region" {
  type        = string
  default     = "eu-west-1"
  description = "AWS Region"
}

variable "namespace" {
  type        = string
  default     = "app"
  description = "Usually an abbreviation of your organization name, e.g. 'eg' or 'cp'"
}

variable "stage" {
  type        = string
  default     = "prod"
  description = "Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'"
}

variable "name" {
  type        = string
  default     = "myproject"
  description = "Project name"
}

variable "image_tag" {
  type        = string
  default     = "latest"
  description = "Docker image tag"
}

variable "container_port_mappings" {
  type = list(object({
    containerPort = number
    hostPort      = number
    protocol      = string
  }))
  default = [
    {
      containerPort = 3000
      hostPort      = 3000
      protocol      = "tcp"
    }
  ]
  description = "The port mappings to configure for the container. This is a list of maps. Each map should contain \"containerPort\", \"hostPort\", and \"protocol\", where \"protocol\" is one of \"tcp\" or \"udp\". If using containers in a task with the awsvpc or host network mode, the hostPort can either be left blank or set to the same value as the containerPort"
}

variable "desired_count" {
  type        = number
  description = "The number of instances of the task definition to place and keep running"
  default     = 1
}

The values for the namespace, stage and name will dictate how the resources will be named. Change them to your needs. With the default values in this example the resources will be named or prefixed with "app-prod-myproject".

And now comes the fun part, the provisioning of the services needed to run a web application. Let's start by adding the configurations for the VPC and Subnets resources first.

Add the following to the main.tf:

# main.tf

module "vpc" {
  source  = "cloudposse/vpc/aws"
  version = "2.0.0"

  namespace = var.namespace
  stage     = var.stage
  name      = var.name

  ipv4_primary_cidr_block = "10.0.0.0/16"
}

module "subnets" {
  source  = "cloudposse/dynamic-subnets/aws"
  version = "2.0.4"

  namespace = var.namespace
  stage     = var.stage
  name      = var.name

  availability_zones  = ["eu-west-1a", "eu-west-1b", "eu-west-1c"] # change to your AZs
  vpc_id              = module.vpc.vpc_id
  igw_id              = [module.vpc.igw_id]
  ipv4_cidr_block     = [module.vpc.vpc_cidr_block]
  nat_gateway_enabled = true
  max_nats            = 1
}

Here, max_nats is set to 1, to save costs at the expense of availability as NAT Gateways are fairly expensive. You can remove or comment out the max_nats property and it will create a NAT Gateway for each "Availability Zone" (number depends on your region) or you can set the nat_gateway_enabled to false if you don't want to create any NAT Gateway and then create resources under the public subnets if they need access to services outside the VPC.

From AWS documentation:

A NAT gateway is a Network Address Translation (NAT) service. You can use a NAT gateway so that instances in a private subnet can connect to services outside your VPC but external services cannot initiate a connection with those instances.

With that said, if you choose not to use a NAT Gateway, don't worry. The Security Group attached to the ECS Service will only allow incoming requests from the ALB.

Now let's add the configuration for the Application Load Balancer (ALB). This will be the entry point to the application and as the name suggest, it will automatically distribute the incoming traffic across multiple targets, meaning ECS Tasks aka docker containers.

# main.tf

module "alb" {
  source  = "cloudposse/alb/aws"
  version = "1.7.0"

  namespace = var.namespace
  stage     = var.stage
  name      = var.name

  access_logs_enabled   = false
  vpc_id                = module.vpc.vpc_id
  ip_address_type       = "ipv4"
  subnet_ids            = module.subnets.public_subnet_ids
  security_group_ids    = [module.vpc.vpc_default_security_group_id]
  # https_enabled         = true
  # certificate_arn       = aws_acm_certificate.cert.arn
  # http_redirect         = true
  health_check_interval = 60
}

The https related properties are commented as it's out of scope for this guide. There will be a follow up article on how to create an SSL certificate with AWS Certificate Manager and enable HTTPS.

Next comes the ECS configuration. This will create the ECS Cluster, ECR, CloudWatch Logs, a Container definition -- which will be used to create the ECS task definition -- and the Service that will run and manage the ECS task definition.

# main.tf

module "ecr" {
  source  = "cloudposse/ecr/aws"
  version = "0.35.0"

  namespace = var.namespace
  stage     = var.stage
  name      = var.name

  max_image_count         = 100
  protected_tags          = ["latest"]
  image_tag_mutability    = "MUTABLE"
  enable_lifecycle_policy = true

  # Whether to delete the repository even if it contains images
  force_delete = true
}

module "cloudwatch_logs" {
  source  = "cloudposse/cloudwatch-logs/aws"
  version = "0.6.6"

  namespace = var.namespace
  stage     = var.stage
  name      = var.name

  retention_in_days = 7
}

module "container_definition" {
  source  = "cloudposse/ecs-container-definition/aws"
  version = "0.58.1"

  container_name   = "${var.namespace}-${var.stage}-${var.name}"
  container_image  = "${module.ecr.repository_url}:${var.image_tag}"
  container_memory = 512 # optional for FARGATE launch type
  container_cpu    = 256 # optional for FARGATE launch type
  essential        = true
  port_mappings    = var.container_port_mappings

  # The environment variables to pass to the container.
  environment = [
    {
      name  = "ENV_NAME"
      value = "ENV_VALUE"
    },
  ]

  # Pull secrets from AWS Parameter Store.
  # "name" is the name of the env var.
  # "valueFrom" is the name of the secret in PS.
  secrets = [
    # {
    #   name      = "SECRET_ENV_NAME"
    #   valueFrom = "SECRET_ENV_NAME"
    # },
  ]

  log_configuration = {
    logDriver = "awslogs"
    options = {
      "awslogs-region"        = var.region
      "awslogs-group"         = module.cloudwatch_logs.log_group_name
      "awslogs-stream-prefix" = var.name
    }
    secretOptions = null
  }
}

module "ecs_alb_service_task" {
  source  = "cloudposse/ecs-alb-service-task/aws"
  version = "0.66.4"

  namespace = var.namespace
  stage     = var.stage
  name      = var.name

  use_alb_security_group         = true
  alb_security_group             = module.alb.security_group_id
  container_definition_json      = module.container_definition.json_map_encoded_list
  ecs_cluster_arn                = aws_ecs_cluster.ecs_cluster.arn
  launch_type                    = "FARGATE"
  vpc_id                         = module.vpc.vpc_id
  security_group_ids             = [module.vpc.vpc_default_security_group_id]
  subnet_ids                     = module.subnets.private_subnet_ids # change to "module.subnets.public_subnet_ids" if "nat_gateway_enabled" is false
  ignore_changes_task_definition = false
  network_mode                   = "awsvpc"
  assign_public_ip               = false # change to true if "nat_gateway_enabled" is false
  propagate_tags                 = "TASK_DEFINITION"
  desired_count                  = var.desired_count
  task_memory                    = 512
  task_cpu                       = 256
  force_new_deployment           = true
  container_port                 = var.container_port_mappings[0].containerPort

  ecs_load_balancers = [{
    container_name   = "${var.namespace}-${var.stage}-${var.name}"
    container_port   = var.container_port_mappings[0].containerPort
    elb_name         = ""
    target_group_arn = module.alb.default_target_group_arn
  }]
}

There are two parameters that I want to mention here, the ignore_changes_task_definition and force_new_deployment as they are related to how a new version of the app is deployed live. For the first, we want terraform to track changes to the ECS task definition, like the container_image value and to create a new ECS task definition version. For the second we tell the Service to deploy the latest version immediately.

And last we will create the assume IAM Role and the OpenID Connect (OIDC) Identity provider. This will allow GitHub Actions to request temporary security credentials for access to AWS resources.

# main.tf

resource "aws_iam_openid_connect_provider" "github_actions_oidc" {
  url = "https://token.actions.githubusercontent.com"

  client_id_list = [
    "sts.amazonaws.com",
  ]

  thumbprint_list = [
    "6938fd4d98bab03faadb97b34396831e3780aea1"
  ]

  tags = {
    Namespace = var.namespace
    Stage     = var.stage
    Name      = var.name
  }
}

resource "aws_iam_role" "github_actions_role" {
  name = "github_actions"

  assume_role_policy = jsonencode({
    Version = "2012-10-17",
    Statement = [
      {
        Effect = "Allow",
        Principal = {
          Federated = aws_iam_openid_connect_provider.github_actions_oidc.arn
        },
        Action = "sts:AssumeRoleWithWebIdentity",
        Condition = {
          StringLike = {
            "token.actions.githubusercontent.com:sub" : "repo:EXAMPLE_ORG/REPO_NAME:*"
          },
          StringEquals = {
            "token.actions.githubusercontent.com:aud" : "sts.amazonaws.com"
          }
        }
      }
    ]
  })

  managed_policy_arns = ["arn:aws:iam::aws:policy/AdministratorAccess"]

  tags = {
    Namespace = var.namespace
    Stage     = var.stage
    Name      = var.name
  }
}

The StringLike condition will match and allow any branch, pull request merge branch, or environment from the EXAMPLE_ORG/REPO_NAME to assume the github_actions IAM Role. If you want to limit to a specific branch like main, then replace the wildcard (*) with the branch name. You can read more here.

For the purpose of this guide we'll attach the AWS managed AdministratorAccess policy to the role. As the name suggests the role will have administrator permissions.

It's important to mention that the policies assigned to the role determine what the GitHub Actions user is allowed to do in AWS. As a security best practice it's highly recommended to give the least permissions to a role.

And at last add the following to the outputs.tf:

# outputs.tf

output "alb_dns_name" {
  description = "DNS name of ALB"
  value       = module.alb.alb_dns_name
}

output "github_actions_role_arn" {
  description = "The ARN of the role to be assumed by the GitHub Actions"
  value       = aws_iam_role.github_actions_role.arn
}

output "ecr_repository_name" {
  description = "The name of the ECR Repository"
  value       = module.ecr.repository_name
}

Now, inside the terraform folder, run the terraform init command and then run the terraform plan and check the output to see the resources that will be created, and lastly, you should see this:

...
Plan: 54 to add, 0 to change, 0 to destroy.

If everything looks good go on and run terraform apply. After all the resources were created, copy the alb_dns_name value from the outputs and paste it in the browser and... (drum rolls), you get a "503 Service Temporarily Unavailable" error. This is expected as the Task Definition is configured to use the docker image with the "latest" or "1.x.x" tag which does not exist in the ECR yet. That's where GitHub Actions comes into play. Before moving to the next section, copy the github_actions_role_arn value. We'll need it for the next step.

And that's it for the Infrastructure Provisioning part. Congrats for making it so far!

Automation with GitHub Actions

Now that we have the infrastructure ready, let's create the GitHub Actions workflow and automate the deployment process.

Create the following folder structure .github/workflows at the root of your project. Inside the workflows folder create a .yaml file and name it buildAndDeploy (or any name you want) and copy the following configuration.

# buildAndDeploy.yaml

name: 'Build and deploy with terraform'

on:
  push:
    tags:
      - '*'

env:
  AWS_REGION: eu-west-1 # Change to your region
  IAM_ROLE_ARN: arn:aws:iam::xxxxxxxxxxxx:role/github_actions # Change to github action role arn

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read # This is required for actions/checkout

jobs:
  build:
    name: Build Docker Image
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1-node16
        with:
          role-to-assume: ${{ env.IAM_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v1

      - name: Build, tag, and push image to Amazon ECR
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: app-prod-myproject # namespace-stage-name
        run: |
          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$GITHUB_REF_NAME -t $ECR_REGISTRY/$ECR_REPOSITORY:latest .
          docker image push -a $ECR_REGISTRY/$ECR_REPOSITORY

  terraform:
    name: Terraform Apply
    needs: build
    runs-on: ubuntu-latest
    environment: production

    defaults:
      run:
        shell: bash

    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1-node16
        with:
          role-to-assume: ${{ env.IAM_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.4.1

      - name: Terraform Init
        working-directory: ./terraform
        run: terraform init

      - name: Terraform Plan
        id: plan
        working-directory: ./terraform
        run: terraform plan -var="image_tag=$GITHUB_REF_NAME"
        continue-on-error: true

      - name: Terraform Plan Status
        if: steps.plan.outcome == 'failure'
        run: exit 1

      - name: Terraform Apply
        working-directory: ./terraform
        run: terraform apply -var="image_tag=$GITHUB_REF_NAME" -auto-approve

I believe the pipeline jobs and steps within are quite self explanatory and I will not go into details. I will mention though the important parts. Replace the AWS_REGION and IAM_ROLE_ARN environment values with your AWS region and the github_actions_role_arn value that you copied earlier from the terraform output.

In the build job, under the steps, change the ECR_REPOSITORY value with the values you set for the namespace, stage and name in the variables.tf file.

That's it! Commit everything, create a tag and push to GitHub. Now go to your repository in GitHub and click on the "Actions" tab. If everything was setup correctly you should see that the "Build and deploy with terraform" workflow has been started or it's starting.

After the deployment pipeline has finished successfully try again to access the ALB DNS in the browser. You should now see "Hello World!". If you still get a 503, give it a few minutes. It's possible that the Task did not start yet. Otherwise, for troubleshooting, go the the ECS/Cluster/{cluster name}/Services in the AWS Console and check the followings:

At least 1 Task is in running state
Unhealthy targets in the Target Groups
The "Deployments and events" tab
The logs under the "Logs" tab or in CloudWatch
The application is starting successfully and responds within the 200-399 http code range

Awesome, you made it! I hope it was easy to follow along. I tried to keep it simple and to the point as possible.

If, at this point, you want to delete the AWS resources created by terraform, run terraform destroy.

Additionally, If you want your website to be accessible under your custom domain, go to your DNS provider, e.g. GoDaddy and create a CNAME Record pointing to the ALB DNS. If your DNS is managed by Route 53 create an Alias (A) record pointing to the ALB DNS.

And finally, you can check the full code example in this repo: deploy-web-app-on-aws-with-terraform-and-github-actions

Check the original article. I will soon post the following articles there: