DEV Community: Nathan (Nursultan) Bekenov

Run Flyway DB migrations with AWS Lambda and RDS - Part 1

Nathan (Nursultan) Bekenov — Sat, 06 Jul 2024 20:32:14 +0000

Usually there is a need to run SQL database updates: update table columns, add new rows, create a new schema etc. Often developer teams are using Flyway It is an open-source database SQL deployment tool. In Flyway, all DDL and DML changes to the database are called migrations. Migrations can be versioned or repeatable.

If RDS cluster is in private subnet how then you are going to automate these DB migrations?
One of the solutions is to use AWS Lambda in the same VPC that will have flyway run against DB

Here is what we are going to do:

Part 1 - Create local setup

Initialize project
Docker image for PostgreSQL and Flyway so we can test our code
Write Java class that will run Flyway Migrations in our docker container

Part 2 - Deploy in AWS

Create AWS Lambda using Terraform
Update Java class and deploy code in Lambda
Configure access from Lambda to RDS (no DB password is needed)
Make some conclusions

Initialize project

create new java project using gradle init
you src folder should like this (Example https://github.com/nbekenov/flyway-lambda/tree/local-setup)

└── src
    ├── main
        ├── java
        │   └── com
        │       └── example
        │           └── DatabaseMigrationHandler.java
        └── resources
            └── db
                └── migration
                    └── V1__Create_table.sql

our SQL migration scripts will be stored in src/resources/db/migration folder
our main java class will be in DatabaseMigrationHandler.java (you can name you package the way you want - I named it com.example)

Docker Compose Setup for Local Development

In this setup, we are using Docker Compose to create a local environment for testing database migrations using Flyway and PostgreSQL. If you want you can skip explanation and get to git repo with the code

/docker
├── .env.pg_admin
├── README.md
├── docker-compose.yml
└── init
    └── create_schemas.sql

Create docker folder.
Create init folder inside docker folder
In init folder create new file create_schemas.sql. This file will be used for initialization and creating our DB schema.

CREATE SCHEMA IF NOT EXISTS myschema;

Create new file .env.pg_admin inside docker folder - this file contains values for env variables for one of the docker containers

PGADMIN_DEFAULT_EMAIL=user@domain.com
PGADMIN_DEFAULT_PASSWORD=mysecretpassword

And finally create docker-compose.yml inside docker folder

version: '3.1'

services:
  db:
    image: postgres
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - ./local-data:/var/lib/postgresql/data
      - ./init:/docker-entrypoint-initdb.d # init scripts are executed upon DB container startup
    ports:
      - 5432:5432

  flyway:
    image: flyway/flyway
    depends_on:
      - db 
    volumes:
      - ../src/main/resources/db/migration:/flyway/sql
    command: -url=jdbc:postgresql://db:5432/postgres -schemas=myschema -user=postgres -password=mysecretpassword -connectRetries=60 migrate

  pg_admin:
    image: dpage/pgadmin4
    depends_on:
      - db 
    env_file:
      - .env.pg_admin
    ports:
      - 80:80

volumes:
  local-data:
    external: false

We define three services: db, flyway, and pg_admin.

Database Service (db)

Environment Variables: Sets the PostgreSQL user and password.
Volumes:
- ./local-data:/var/lib/postgresql/data: Maps a local directory to the PostgreSQL data directory to persist data.
- ./init:/docker-entrypoint-initdb.d: Maps a local directory to the directory where PostgreSQL looks for initialization scripts.

Flyway Service (flyway)

Depends_on: Ensures that the db service starts before the Flyway service.
Volumes: Maps the local directory containing SQL migration scripts to Flyway's expected location.
Command: Provides Flyway with the necessary parameters to connect to the database and run the migrations:

   -url=jdbc:postgresql://db:5432/postgres: JDBC URL to connect to the PostgreSQL database.
   -schemas=myschema: Specifies the schema to migrate.
   -user=postgres and -password=mysecretpassword: Database credentials.
   -connectRetries=60: Retries the connection for up to 60 seconds if the database is not immediately available.
   migrate: Command to run the migrations.

pgAdmin Service (pg_admin)

Depends_on: Ensures the db service starts before pgAdmin.
Env_file: Loads environment variables from a .env.pg_admin file to configure pgAdmin.
Ports: Maps port 80 on the host to port 80 in the container to access pgAdmin through a web browser.

Start containers

cd docker
docker-compose up -d

Verify that Flyway run

docker ps -a
docker logs <container-id-or-name> --tail 20

Write Java class

In this section, we'll dive into the Java class DatabaseMigrationHandler that is designed to run Flyway migrations against a local PostgreSQL database set up in a Docker container. This class encapsulates all the necessary logic to establish a database connection, test the connection, and execute the migrations.

If you want you can skip explanation and get to git repo with the code

Package and Imports

package com.example;

import org.flywaydb.core.Flyway;

import java.sql.Connection;
import java.sql.SQLException;
import java.util.Properties;
import java.util.Objects;
import software.amazon.jdbc.PropertyDefinition;
import software.amazon.jdbc.ds.AwsWrapperDataSource;

Package Declaration: The class is part of the com.example package.
Imports: Necessary classes from the Flyway library, Java SQL package, and AWS JDBC wrapper for handling database connections are imported

Class and Instance Variables

public class DatabaseMigrationHandler {
    // instance vars
    private final String dbHost;
    private final String dbPort;
    private final String dbName;
    private final String dbSchema;
    private final String dbUser;
    private final String dbPassword;

    private static final String DB_HOST = "localhost";
    private static final String DB_PORT = "5432";
    private static final String DB_NAME = "postgres";
    private static final String DB_SCHEMA = "myschema";
    private static final String DB_USER = "postgres";
    private static final String DB_PASSWORD = "mysecretpassword";
}

Instance Variables: These store the database connection details such as host, port, name, schema, user, and password.
Static Constants: Default values for the database connection details are defined as static constants.

Constructor

    public DatabaseMigrationHandler() {
        this.dbHost = DB_HOST;
        this.dbPort = DB_PORT;
        this.dbName = DB_NAME;
        this.dbSchema = DB_SCHEMA;
        this.dbUser = DB_USER;
        this.dbPassword = DB_PASSWORD;
    }

Constructor: Initializes the instance variables with the default values defined above.

Test Connection Method

    private boolean testConnection() {
        try (Connection connection = getDataSource().getConnection()) {
            return connection != null;
        } catch (SQLException e) {
            e.printStackTrace();
            return false;
        }
    }

testConnection Method: Attempts to establish a connection to the database. Returns true if successful, otherwise logs the exception and returns false.

Run Migrations Method

    private void runMigrations() {
        try{
            Flyway flyway = Flyway.configure()
                    .dataSource(getDataSource())
                    .schemas(this.dbSchema.  )
                    .load();
            flyway.migrate();
            System.out.println("Completed Database migration!");
        } catch (Exception e) {
            System.out.println("Database migration failed!");
            e.printStackTrace();
        }
    }

runMigrations Method: Configures and runs Flyway migrations. It uses the Flyway class to set up the data source and schema, then initiates the migration process.

Data Source Configuration

    private AwsWrapperDataSource getDataSource() {
        Properties targetDataSourceProps = new Properties();
        targetDataSourceProps.setProperty("ssl", "false");
        targetDataSourceProps.setProperty("password", this.dbPassword);

        AwsWrapperDataSource ds = new AwsWrapperDataSource();
        ds.setJdbcProtocol("jdbc:postgresql:");
        ds.setTargetDataSourceClassName("org.postgresql.ds.PGSimpleDataSource");
        ds.setServerName(this.dbHost);
        ds.setDatabase(this.dbName);
        ds.setServerPort(this.dbPort);
        ds.setUser(this.dbUser);
        ds.setTargetDataSourceProperties(targetDataSourceProps);

        return ds;
    }
}

getDataSource Method: Configures the data source using AwsWrapperDataSource to connect to the PostgreSQL database. It sets the necessary properties such as server name, database name, port, user, and password.

Main method

    public static void main(String[] args) {
        DatabaseMigrationHandler handler = new DatabaseMigrationHandler();
        if (handler.testConnection()) {
            System.out.println("Database connection successful!");
            handler.runMigrations();
        } else {
            System.out.println("Failed to connect to the database.");
        }
    }

main Method: The entry point of the application. It creates an instance of DatabaseMigrationHandler, tests the database connection, and runs the migrations if the connection is successful.

Explanation of the build.gradle

In this section, we'll go through the build.gradle file, which is used to configure the build process for your Java project. We'll also cover some useful Gradle commands for building and running your project.

Plugins Section

plugins {
    id 'java'
    id 'groovy'
    id 'application'
}

application Plugin: Facilitates the creation of Java applications and provides tasks for running the application

Dependencies Section

dependencies {
    implementation 'org.flywaydb:flyway-core:9.22.3'
    implementation 'org.postgresql:postgresql:42.7.2'
    implementation 'software.amazon.jdbc:aws-advanced-jdbc-wrapper:2.3.0'

    testImplementation platform('org.junit:junit-bom:5.10.0')
    testImplementation 'org.junit.jupiter:junit-jupiter'
}

implementation: Declares dependencies required to compile and run the application. Here, flyway-core, postgresql, and aws-advanced-jdbc-wrapper are included.

Application Section

application {
    mainClass = 'com.example.DatabaseMigrationHandler'
}

mainClass: Specifies the main class of the application, which is com.example.DatabaseMigrationHandler. This is the entry point when running the application.

Once you have your build.gradle file set up, you can use several Gradle commands to manage your project. These commands are executed from the command line.

./gradlew clean

clean: Deletes the build directory, effectively cleaning the project. This is useful for ensuring a fresh build environment.

./gradlew build

build: Compiles the source code, runs tests, and packages the project into a JAR file. This command performs all the necessary steps to create a build artifact.

./gradlew run

run: Executes the main class specified in the application section. In this case, it will run com.example.DatabaseMigrationHandler, which handles the Flyway migrations.

In the logs you should see that connection to DB was established and DB migrations run successfully.

Securely connect to an Amazon RDS

Nathan (Nursultan) Bekenov — Mon, 06 May 2024 01:14:09 +0000

Hello there! In this post I am going to show you Terraform code example of how to create resources for secure connection to your DB in RDS cluster.

I am going to follow approach provided by AWS team in this article

Ok, let's figure out what resources we need to create.
I assume that you already have: VPC and RDS Cluster (if not yet then check out previous post ).

VPC endpoints (ssm, ssmmessages, ec2messages)
EC2 instance
Security Group for EC2 instance
IAM role and instance profile

I will put details after each part of the code. Also if you want to skip and jump right to the code then everything can be found in my repo

Below code creates VPC endpoints. Since we need 3 of them I am looping through the list. We also will need security group.

# ----------------
# VPC Endpoints
# ----------------
locals {
  endpoints = {
    "endpoint-ssm" = {
      name        = "ssm"
      private_dns = false
    },
    "endpoint-ssm-messages" = {
      name        = "ssmmessages"
      private_dns = false
    },
    "endpoint-ec2-messages" = {
      name        = "ec2messages"
      private_dns = false
    },
  }
}

resource "aws_vpc_endpoint" "endpoints" {
  for_each            = local.endpoints

  vpc_id              = module.vpc.vpc_id
  vpc_endpoint_type   = "Interface"
  service_name        = "com.amazonaws.${data.aws_region.current.name}.${each.value.name}"
  security_group_ids  = [aws_security_group.vpc_endpoint_sg.id]
  subnet_ids          = data.aws_subnets.private.ids
  private_dns_enabled = each.value.private_dns

}

# SG for VPC endpoints
resource "aws_security_group" "vpc_endpoint_sg" {
  name_prefix = "vpc-endpoint-sg"
  vpc_id      = module.vpc.vpc_id
  description = "security group for VPC endpoints"

  ingress {
    from_port   = 0
    to_port     = 65535
    protocol    = "tcp"
    cidr_blocks = [module.vpc.vpc_cidr_block]
    description = "allow all TCP within VPC CIDR"
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
    description = "allow all outbound traffic from VPC"
  }

  tags = {
    Name = "vpc-endpoints-sg"
  }
}

Now let's create EC2 instance and configure instance profile for it.

resource "aws_instance" "bastion_host" {
  ami                     = data.aws_ami.amazon_linux_2_ssm.id
  instance_type           = "t3.nano"
  subnet_id               = data.aws_subnets.private.ids[1]
  vpc_security_group_ids  = data.aws_security_groups.vpc_endpoint_sg.ids
  iam_instance_profile    = aws_iam_instance_profile.bastion_host_instance_profile.name
  user_data               = templatefile("ssm-agent-installer.sh", {})
  disable_api_termination = false
  metadata_options {
    http_endpoint = "enabled"
    http_tokens   = "required"
  }
  tags = {
    Name = "ssm-bastion-host"
  }
}

## Instance profile
resource "aws_iam_role" "bastion_host_role" {
  name = "EC2-SSM-Session-Manager-Role"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Service = "ec2.amazonaws.com"
        }
        Action = "sts:AssumeRole"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "bastion_host_role_policy" {
  policy_arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
  role       = aws_iam_role.bastion_host_role.name
}

resource "aws_iam_instance_profile" "bastion_host_instance_profile" {
  name = "EC2_SSM_InstanceProfile"
  role = aws_iam_role.bastion_host_role.name
}

For Instance IAM role we are using existing policy AmazonSSMManagedInstanceCore that we will need in order to be able to use SSM.
Note that in user_data I am using shell script to install necessary packages.

#!/bin/bash
main(){
    #####Installing dependencies and packages ####
    echo "Installing Security Updates..."
    sudo yum -y update
    echo "Installing ec2 instance connect..."
    sudo yum install ec2-instance-connect
    echo "Installing latest aws-ssm agent..."
    sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm
    sudo systemctl enable amazon-ssm-agent
    echo "Starting latest aws-ssm agent..."
    sudo systemctl start amazon-ssm-agent
    sudo amazon-linux-extras enable postgresql14
    sudo yum -y install postgresql
}
time main > /tmp/time-output.txt

Once all infra is created follow the steps from my Readme
https://github.com/nbekenov/rds-aurora/blob/main/bastion_host/README.md

Create a remote port forwarding session

aws ssm start-session \   
    --region us-east-1 \   
    --target <bastion instance id> \    
    --document-name AWS-StartPortForwardingSessionToRemoteHost \    
    --parameters host="<rds endpoint name>",portNumber="5432" localPortNumber="5432"

Connect to DB using PGAdmin

Use username and password from AWS Secrets Manager

In the next post I will be providing details on how to run DB Migrations using Flyway and Lambda Function

Create RDS cluster and manage passwords in 2024

Nathan (Nursultan) Bekenov — Thu, 01 Feb 2024 21:33:59 +0000

Hello there! In this post I am going to show you Terraform code example of how to create AWS RDS cluster and mange DB passwords in AWS Secrets Manager.

Ok, let's get started with creating RDS cluster. In my example I am going to create Aurora PostgreSQL Serverless DB. To create a cluster I am going to use existing terraform module . I will put details after each part of the code. Also the all scripts can be found in my repo

data.tf to get VPC details and engine details

data "aws_caller_identity" "current" {}

data "aws_vpc" "vpc" {
  filter {
    name   = "tag:Name"
    values = [var.vpc_name]
  }
}

data "aws_subnets" "private" {
  filter {
    name   = "tag:Name"
    values = ["${var.vpc_name}-private-*"]
  }
}

data "aws_rds_engine_version" "postgresql" {
  engine  = "aurora-postgresql"
  version = var.engine_version
}

vars.tf - update vars based on your environment setup

variable "database_name" {
  type        = string
  description = "database_name"
  default     = "aurorapostgres"
}

variable "admin_user_name" {
  type        = string
  description = "admin_user_name"
  default     = "aurora_admin"
}

variable "engine_version" {
  type        = string
  description = "postgresql engine_version"
  default     = "15.4"
}

variable "max_capacity" {
  type        = number
  description = "max scaling capacity"
  default     = 4
}

variable "min_capacity" {
  type        = number
  description = "min scaling capacity"
  default     = 2
}

variable "vpc_name" {
  type        = string
  description = "vpc_name"
  default     = "main-vpc"
}

rds.tf

resource "aws_kms_key" "aurora_kms_key" {
  description             = "CMK for Aurora PostgreSQL server side encryption"
  deletion_window_in_days = 10
  enable_key_rotation     = false
}

resource "aws_kms_alias" "aurora_kms_key_alias" {
  name          = "alias/aurora-data-store-key"
  target_key_id = aws_kms_key.aurora_kms_key.id
}

resource "aws_db_subnet_group" "serverlessv2_sg" {
  name       = "${var.database_name}-subnet_group"
  subnet_ids = data.aws_subnets.private.ids
}

module "aurora_postgresql_v2" {
  source  = "terraform-aws-modules/rds-aurora/aws"
  version = "8.5.0"

  name          = var.database_name
  database_name = var.database_name

  engine         = data.aws_rds_engine_version.postgresql.engine
  engine_version = data.aws_rds_engine_version.postgresql.version

  instance_class = "db.serverless"
  instances = {
    one = {}
    two = {}
  }
  serverlessv2_scaling_configuration = {
    min_capacity = var.min_capacity
    max_capacity = var.max_capacity
  }

  master_username                     = var.admin_user_name
  manage_master_user_password         = true
  storage_encrypted                   = true
  kms_key_id                          = aws_kms_key.aurora_kms_key.arn
  iam_database_authentication_enabled = true
  ca_cert_identifier                  = "rds-ca-rsa2048-g1"

  vpc_id               = data.aws_vpc.vpc.id
  db_subnet_group_name = aws_db_subnet_group.serverlessv2_sg.name
  security_group_rules = {
    vpc_ingress = {
      cidr_blocks = [data.aws_vpc.vpc.cidr_block]
    }
  }

  monitoring_interval = 60
  apply_immediately   = true
  skip_final_snapshot = true

  deletion_protection = true

}

So here I am at first creating KMS key that will be used in server side encryption. Then I am creating cluster with subnet group. Let's stop on DB master user and password

Previously there were couple ways to setup DB master user and password:

create secret (password=random string) in AWS Secrets Manager and then using terraform ${data.aws_secretsmanager_secret_version.db_password.secret_string} provide password to create the cluster. In this case if someone will get access to your Terraform state file they will be able to see the DB password in the plain text.
To workaround this you could have configured password update by enabling secrets rotation in AWS Secrets Manager. That would usually require additional Lambda function that will trigger rotation and password update in RDS cluster

But now (well since Dec 22, 2022) "...RDS fully manages the master user password and stores it in AWS Secrets Manager whenever your RDS database instances are created, modified, or restored. The new feature supports the entire lifecycle maintenance for your RDS master user password including regular and automatic password rotations; removing the need for you to manage rotations using custom Lambda functions."

The life become significantly easier - you just need to select the option

  master_username                     = var.admin_user_name
  manage_master_user_password         = true

And it will create secret for you. The rotation schedule by default is 7 days.

And that's it. We created RDS cluster and managing master password in most secure way with enabled rotation.

In the next post I will be providing details on how to configure secure access to RDS instances using Terraform

https://dev.to/aws-builders/securely-connect-to-an-amazon-rds-2i3p

ECS Blue/Green deployment with CodeDeploy and Terraform

Nathan (Nursultan) Bekenov — Thu, 30 Nov 2023 22:09:38 +0000

In this article you will find a helpful step by step guide on how to setup Blue/Green deployment with AWS CodeDeploy for ECS Fargate using Terraform and the ways of working around common challenges of doing this through the Terraform.

Note: if you want to skip and get to the solution then please follow this link to my repository

Assumptions:

You already know how to use Terraform
You already know what is AWS ECS and how to create ECS service in Fargate
You already know what is AWS ALB and Target Groups
You already have idea what is Blue/Green deployment strategy if no then check this page

So what are the challenges of doing this with Terraform? Before answering this question let me briefly go through the Blue/Green deployment process in ECS when it's performed by CodeDeploy.

This is what you should have in place before starting deployment:

ECS cluster, ECS task definition
In that cluster ECS service running behind Load Balancer
In that Load Balancer - ALB Listener rule (Production Listener for example with port 443) that forwards traffic to the Target group(Blue target group) where ECS service tasks are registered.
A second Listener (Test traffic listener for example with port 8443) that points to the Green Target group, there are no ECS service tasks registered in this group at the moment.
CodeDeploy app and deployment group - you can find my example here

Now to perform B/G deployment you need to:

Create new ECS task revision
Update appspec.yaml file with New Task arn and ALB information
Create a new deployment in CodeDeploy with provided appspec.yaml

This is what CodeDeploy will do

Creates new tasks with the new version of the image, adds them into Green Target Group. Now you can access new version of the app through the Test Listener port

Once Confirmed that new tasks are up and running (or all pre-hook tests are passed) CodeDeploy shifts traffic in LoadBalancer - Pointing Production Listener now to the Green Target Group

Once traffic is shifted CodeDeploy will (after configured time) decommission tasks running the old version of the app

So the challenges of doing this through the terraform:

CodeDeploy makes changes in ALB (shifts the traffic between target groups) outside of Terraform. If we run terraform apply it will rewrite all changes made my CodeDeploy

To workaround this add lifecycle { ignore_changes = ...} in ALB

resource "aws_lb_listener_rule" "example"{
...
 action {
  type = "forward"
  target_group_arn = aws_lb_target_group.example.arn
 }
# because CodeDeploy will switch target groups during the B/G deployment
 lifecycle {
   ignore_changes = [action] 
 }
}

After deployment is done CodeDeploy changes task version in ECS service and updates target group information outside of Terraform

To workaround this add lifecycle { ignore_changes = ...} in ECS

resource "aws_ecs_service" "example"{
...
 task_definition = aws_ecs_task_definition.example.arn

 load_balancer {
  container_name = "example"
  container_port = 8080
  target_group_arn = aws_lb_target_group.example.arn
 }
# because CodeDeploy will handle task definition and alb changes outside of terraform
 lifecycle {
   ignore_changes = [load_balancer, task_definition]
 }
}

To create deployment in CodeDeploy we need execute CLI
To update the appspec.yaml file we need to know the ARN of the new task revision. On different blog posts I saw examples of creating new task revision using CLI - but what if we want to manage ECS task through Terraform

To do this through Terraform use local_file and local-exec to update appspec.yaml and execute CLI to create deployment in CodeDeploy

In the code below we are creating content of the appspec.yaml file and then executing CLI commands to start the deployment and wait until it's finished.

locals {

  # appspec file  
  appspec = {
    version = "0.0"
    Resources = [
      {
        TargetService = {
          Type = "AWS::ECS::Service"
          Properties = {
            TaskDefinition = var.ecs_task_def_arn
            LoadBalancerInfo = {
              ContainerName = var.container_name
              ContainerPort = var.container_port
            }
          }
        }
      }
    ]
  }
  appspec_content = replace(jsonencode(local.appspec), "\"", "\\\"")
  appspec_sha256  = sha256(jsonencode(local.appspec))

  # create deployment bash script
  script = <<EOF
#!/bin/bash

echo "creating deployment ..."
ID=$(aws deploy create-deployment \
    --application-name ${var.codedeploy_application_name} \
    --deployment-group-name ${var.deployment_group_name} \
    --revision '{"revisionType": "AppSpecContent", "appSpecContent": {"content": "${local.appspec_content}", "sha256": "${local.appspec_sha256}"}}' \
    --output text \
    --query '[deploymentId]')

echo "======================================================="
echo "waiting for deployment $deploymentId to finish ..."
STATUS=$(aws deploy get-deployment \
    --deployment-id $ID \
    --output text \
    --query '[deploymentInfo.status]')

while [[ $STATUS == "Created" || $STATUS == "InProgress" || $STATUS == "Pending" || $STATUS == "Queued" || $STATUS == "Ready" ]]; do
    echo "Status: $STATUS..."
    STATUS=$(aws deploy get-deployment \
        --deployment-id $ID \
        --output text \
        --query '[deploymentInfo.status]')

    SLEEP_TIME=30

    echo "Sleeping for: $SLEEP_TIME Seconds"
    sleep $SLEEP_TIME
done

if [[ $STATUS == "Succeeded" ]]; then
    echo "Deployment succeeded."
else
    echo "Deployment failed!"
    exit 1
fi

EOF

}

resource "local_file" "deploy_script" {
  filename             = "${path.module}/deploy_script.txt"
  directory_permission = "0755"
  file_permission      = "0644"
  content              = local.script

  depends_on = [ 
    aws_codedeploy_app.this,
    aws_codedeploy_deployment_group.this,
  ]
}

resource "null_resource" "start_deploy" {
  triggers = {
    appspec_sha256 = local.appspec_sha256 # run only if appspec file changed
  }

  provisioner "local-exec" {
    command     = local.script
    interpreter = ["/bin/bash", "-c"]
  }

  depends_on = [ 
    aws_codedeploy_app.this,
    aws_codedeploy_deployment_group.this,
  ]
}

Use AWS CodeArtifact with Angular app builds

Nathan (Nursultan) Bekenov — Wed, 27 Sep 2023 18:20:39 +0000

Introduction
This is a short post describing how you can use AWS CodeArtifact with your application builds. I am using generic packages but there are other options. I will provide example for npm build but the approach can be used for other types of builds.

Note: I previously posted detailed walkthrough on how to host Angular up in S3 ( check out the link). This post will describe how we can now store the builds.

Understanding the Need for Artifact Repositories
Why Store Builds? Why can't we just deploy our applications immediately after building them? It's essential to understand the rationale behind storing builds in the first place.

Consistent Deployments: The "build once and deploy everywhere" mantra ensures that the same build is deployed across various environments, be it staging, QA, or production. This consistency eliminates discrepancies between environments and the notorious "it works on my machine" dilemma.
Versioning and Rollbacks: Storing builds provides a clear version history. If a new deployment encounters issues, teams can swiftly revert to a previous, stable build, ensuring minimal service disruption.
Streamlined Testing: With builds stored and versioned, testing becomes more efficient. Testers can pull specific builds for different testing stages, ensuring that the application undergoes thorough scrutiny before hitting production.
Audit and Compliance: A repository provides a clear audit trail of application iterations. This is invaluable for sectors with stringent regulatory requirements, as it offers transparency and traceability.

Setting Up an AWS CodeArtifact Repository

data "aws_kms_key" "codeartifact_key" {
  key_id = "alias/aws/codeartifact"
}

resource "aws_codeartifact_domain" "example" {
  domain         = "nbekenov"
  encryption_key = data.aws_kms_key.codeartifact_key.arn
}

resource "aws_codeartifact_repository" "example" {
  repository = "my-example-repo"
  domain     = aws_codeartifact_domain.example.domain
}

Build

npm run build:prod

This creates dist/ folder

Publish to CodeArtifact

export DOMAIN_NAME="nbekenov"
export REPOSITORY_NAME="my-example-repo"
export PACKAGE_NAME="example-package"
export PACKAGE_VERSION="1.0.0"

tar -cvzf asset.tar.gz dist/

export ASSET_SHA256=$(sha256sum asset.tar.gz | awk '{print $1;}')

aws codeartifact publish-package-version --domain $DOMAIN_NAME \
    --repository $REPOSITORY_NAME --format generic \
    --namespace $PACKAGE_NAME \
    --package $PACKAGE_NAME --package-version $PACKAGE_VERSION \
    --asset-content asset.tar.gz \
    --asset-name asset.tar.gz \
    --asset-sha256 $ASSET_SHA256

Get package from CodeArtifact

#!/bin/bash
export DOMAIN_NAME="nbekenov"
export REPOSITORY_NAME="my-example-repo"
export PACKAGE_NAME="example-package"

PACKAGE_VERSION=$1

aws codeartifact get-package-version-asset --domain $DOMAIN_NAME \
    --repository $REPOSITORY_NAME  --format generic \
    --namespace $PACKAGE_NAME \
    --package $PACKAGE_NAME \
    --package-version $PACKAGE_VERSION --asset asset.tar.gz asset.tar.gz

tar -xzvf asset.tar.gz

And that's it! Now you have packages based on the build number (package version) you provided and can deploy it.

Host angular app in AWS S3 and CloudFront using Terraform (complete setup)

Nathan (Nursultan) Bekenov — Sat, 19 Aug 2023 19:51:10 +0000

In this guide, I'll walk you through the steps to host your Angular app on AWS S3 and then optimize its delivery using CloudFront. Let's dive in!

What We're Going to Build
Before diving into the technicalities, let's set the stage by understanding what we aim to achieve by the end of this guide

Angular Application: We'll start with a basic Angular application. If you already have one, great! If not, don't worry. We'll briefly touch upon how to set up a simple Angular app using the Angular CLI. This will serve as our demo project to be hosted on AWS.
AWS S3 Bucket: We'll create an S3 bucket, which is essentially a storage space in AWS where we'll upload our Angular app's build files. This bucket will act as our web server, serving the static files of our application.
AWS CloudFront Distribution: To ensure our Angular app is delivered quickly and securely to users worldwide, we'll set up a CloudFront distribution. This will pull the static files from our S3 bucket and distribute them across a network of data centers (edge locations) around the globe. When a user accesses our app, they'll be served from the nearest edge location, ensuring minimal latency.
Custom Domain (Optional): For those who want to take it a step further, we'll also touch upon how to link a custom domain to our CloudFront distribution. This way, users can access our app using a friendly URL rather than the default AWS-generated one.
SSL Certificate for HTTPS: Security is paramount. We'll guide you on how to set up an SSL certificate (for free) using AWS Certificate Manager, ensuring that our Angular app is accessible via HTTPS, providing an encrypted and secure connection for our users.

By the end of this guide, you'll have a fully functional Angular application hosted on AWS, optimized for speed and security. Whether you're looking to host a personal project, a portfolio, or even a production-ready application, this setup will ensure your Angular app is accessible to users around the world with top-notch performance.

Let's get started!

Angular application

Let's create a simple "Hello World" Angular application using the Angular CLI.

Prerequisites:

Node.js and npm: Ensure you have Node.js and npm installed. If not, download and install them from Node.js official website.
Angular CLI: If you haven't installed the Angular CLI yet, you can do so using npm:

npm install -g @angular/cli

Steps to Create a Simple "Hello World" Angular App:

Create a New Angular Project: Open your terminal or command prompt and run the following command to create a new Angular project named my-app:

ng new my-app

Edit the App Component: Open the my-app/src/app/app.component.html file in your favorite code editor. Replace its content with:

<div style="text-align:center; margin-top: 40px;">
    <h1>Hello World!</h1>
    <p>Welcome to my simple Angular app.</p>
</div>

Serve the Application:

ng serve -o

Once compiled successfully, you can open your browser and navigate to http://localhost:4200/. You should see the "Hello World!" message displayed.
And that's it! You've successfully created a simple "Hello World" Angular application using the Angular CLI. This app can now be built for production and hosted on platforms like AWS, as discussed earlier.

Infrastructure

Alright! Let's set up the infrastructure for hosting our Angular app on AWS using Terraform. We'll create an S3 bucket for storing our app's static files and a CloudFront distribution for content delivery.

Prerequisites:

Terraform Installed: Ensure you have Terraform installed. If not, download and install it from Terraform's official website.
AWS CLI Configured: Ensure you have the AWS CLI installed and configured with the necessary access rights.
Existing Domain name (if you don't have any then follow instructions https://aws.amazon.com/getting-started/hands-on/get-a-domain/)

Steps to Create Infrastructure using Terraform

You can find all IaC in my repo
Update variables with your domain name and bucket name. Update backend configuration (backend.tf file)
Then run:

terraform init
terraform plan
terraform apply

Let's break down the infrastructure components we're setting up:

S3 Bucket for Source Code:
We are creating an S3 bucket, which is Amazon's object storage service. This bucket will store the static files of our Angular application. Once the application is built using the Angular CLI, the output files from the dist/ directory will be uploaded to this S3 bucket. By configuring the bucket as a website, it can serve these static files as a web application.
infra/modules/cloudfront-s3-cdn/s3_origin.tf
CloudFront Distribution with Geographical Restrictions:
CloudFront is AWS's content delivery network (CDN) service. We're setting up a CloudFront distribution to deliver our Angular app's content to users. The key advantage of using CloudFront is its vast network of edge locations worldwide, which caches content closer to the end-users, ensuring faster load times. For this setup, we're adding a geographical restriction to whitelist only the USA. This means that users outside the USA will not be able to access the content, ensuring that the application is only available to a specific audience.
infra/modules/cloudfront-s3-cdn/main.tf
S3 Bucket for CloudFront Access Logs:
Monitoring and logging are crucial for any application. We'll set up a separate S3 bucket dedicated to storing CloudFront's access logs. These logs provide detailed records about every user request that CloudFront receives. By analyzing these logs, you can gain insights into user behavior, troubleshoot issues, and even detect potential security threats.
infra/modules/cloudfront-s3-cdn/log_bucket.tf
SSL Certificate:
Security is paramount for web applications. We're integrating an SSL certificate to ensure that our Angular app is served over HTTPS. This encrypts the data between the user's browser and CloudFront, providing a secure browsing experience. We'll use AWS Certificate Manager (ACM) to provision, manage, and deploy the SSL/TLS certificate.
infra/dns.tf
Record in Route 53:
AWS Route 53 is a scalable domain name system (DNS) web service. Once our Angular app is up and running with CloudFront, we might want to link a custom domain to it, rather than using the default AWS-generated URL. We'll create a record in Route 53 that points our custom domain to the CloudFront distribution. This ensures that users can access our app using a friendly and memorable domain name.
infra/dns.tf

In summary, this infrastructure setup ensures that our Angular app is not only hosted efficiently but is also optimized for speed, security, and specific audience targeting. By leveraging AWS services like S3, CloudFront, ACM, and Route 53, we're building a robust and scalable hosting solution.

Deploy

Deploy to S3 using aws s3 sync:

Once you have your Angular application built and your AWS infrastructure set up using Terraform, the next step is to deploy the built Angular app to the S3 bucket. One of the most efficient ways to do this is by using the aws s3 sync command provided by the AWS CLI.

cd my-app
ng build --prod
aws s3 sync dist/my-app/ s3://my-angular-app-bucket/

Replace my-angular-app-bucket with the name of the S3 bucket you created using Terraform.

Invalidate CloudFront Cache (Optional):

If you've made changes to your app and want them to be immediately reflected via CloudFront, you might need to invalidate the CloudFront cache. This ensures that CloudFront fetches the latest version of your app from the S3 bucket:

aws cloudfront create-invalidation --distribution-id YOUR_DISTRIBUTION_ID --paths "/*"

Replace YOUR_DISTRIBUTION_ID with the ID of your CloudFront distribution.

Access the Application:

Once deployed, you can access your Angular app either through the S3 bucket's website URL or, preferably, through the CloudFront distribution URL. If you've set up a custom domain with Route 53, you can use that domain to access your app.

And that's it! Your Angular app is now live on AWS, hosted in an S3 bucket and delivered globally via CloudFront.
Great job! 👏

Further read Use CodeArtifact with Angular builds

Deploying a Node.js application in ECS with CodeCatalyst and Terraform

Nathan (Nursultan) Bekenov — Tue, 11 Jul 2023 23:39:47 +0000

In this step-by-step guide, I'll walk you through the entire process of deploying a Node.js application in ECS Fargate with CodeCatalyst as CI/CD tool and Terraform as IaC. From setting up your environment to configuring your containers and services, we'll cover everything you need to know to get your application up and running in no time. So whether you're new to cloud deployment or just looking for a more streamlined process, this guide is for you. Let's get started!

Prerequisites
You will need the following :

NPM to build and run the app locally
Docker to build and test your image
Terraform to create infrastructure in AWS
AWS account + AWS Builder ID (for CodeCatalyst)

Note:
If you interested only in part of Creating CI/CD pipeline in CodeCatalyst please go to step # 4

Step 0 [Optional] Build and run app locally.

Feel free to skip if you already have existing node.js app.
Create the following files:

src/app.js main app file in the src folder
package.json that includes dependencies

// Import the express module
const express = require('express');

// Create an instance of express
const app = express();

// Define a port
const port = 3000;

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

// Start the server
app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`);
});

My example code

Now you can build and run your app locally

npm install
npm run build
npm test
npm start

Step 1 - Containerize the app

Let's create Dockerfile

# Use an official Node.js runtime as a parent image
FROM node:20-alpine

# set the current mode
ENV NODE_ENV=production

# Set the working directory to /app
WORKDIR /usr/src/app

# Copy the application code to the container
COPY --chown=node:node . .

# Install the dependencies
RUN npm ci --only=production

# Expose the port that your application listens on
EXPOSE 3000

USER node

# Start the application
CMD ["node", "src/app.js"]

Now you can run your app in Docker

docker build -t test:latest .
docker run -p 3000:3000 test:latest

Step 3 - Create Infra

We are going to implement the following architecture using Terraform and open source modules.

First you will need to bootstrap your account:

create S3 and DynamoDB table for Terraform State file
create ECR
create IAM roles and policies for CodeCatalyst

Step 4 - create Pipeline

create AWS Builder ID
Log into CodeCatalyst and create new space and project
Connect AWS accounts
Create environments

Approve AWS CodePipeline Deployments from MS Teams

Nathan (Nursultan) Bekenov — Mon, 10 Jul 2023 14:15:34 +0000

With increasing number of pipelines running in multiple accounts for different applications it becomes difficult to manage all deployment approvals. The solution provided here enables you to approve CodePipeline stages in a centralized way using Microsoft Teams.

Architecture

The solution involves several components working together. Firstly, Notification Lambda function is used to send an approval request to an MS Teams channel via message card. This function is triggered by SNS topic configured in a AWS CodePipeline stage that requires manual approval. The Notification Lambda function uses the Microsoft Teams webhook connector to send a message card to the MS Teams channel, which includes a button that the approver can click to approve or reject the pipeline stage. When the approver clicks the approval button, the MS Teams channel sends a POST request to an API Gateway endpoint, which triggers another Lambda function. This second function Approval Lambda uses the AWS CodePipeline API to update the status of the pipeline stage based on the approver's response.

Implementation
The whole solution can be found in my git repository

For IaC I used Terraform but you can choose any other method you prefer. The most important part I believe is the code of Lambda functions. I wrote them using Python.

More about MS Teams message cards here

Notes

It's possible to enhance security by adding Lambda Authorizer for Api Gateway to ensure that requests are coming only from MS Teams.
Use a dedicated MS Teams channel for approval request to ensure that they are easily visible and distinguishable from other messages.
Make sure that people who allowed to trigger pipeline approval are added into channel and granted admin access Use descriptive and informative message card format that includes relevant information such as the pipeline name, stage name and etc.
Use appropriate error handling and logging in your Lambda functions to detect and handle errors and exceptions
Use monitoring and alerting to track usage and performance of your Lambda functions and other resources, and to alert you about potential issues or anomalies.
The same approach/solution can be done with Slack channels. The only difference will be in the part of sending requests to and from Slack.