Forem: exanubes

Connecting to RDS via Parameter Store config

exanubes — Wed, 05 Oct 2022 14:08:17 +0000

In this article we will go over creating and connecting to a database from an application deployed to ECS Fargate Containers. First we will need to create an RDS instance and store the database credentials, then we will update the CI/CD pipeline in order to perform database migration whenever new versions of the application are deployed. Last but not least, we will use the AWS SDK to communicate with Systems Manager to recover database credentials and connect to it.

Here's a diagram of what we're building

We're going to pick up where we left off in ECS with CI/CD Pipeline with a Fargate cluster behind an ALB and a CI/CD pipeline for automatic deployments. In this article we will focus on implementing the second private subnet with an RDS instance that has a security group configured to allow inbound traffic on port 5432 from within the VPC. This way, CodeBuild will be able to run migration queries and Fargate Container - our App - will be able to communicate with the database. In order for the application to gain access to the database, we will grab credentials from the SSM Parameter Store.

Go to GitHub if you're looking for finished code. To follow along clone the starter repo

git clone -b start git@github.com:exanubes/connecting-to-rds-via-ssm-parameter-store-config.git

RDS Instance

The overall creation of RDS Instance is quite straightforward. What we want to keep in mind while doing this is to place it within our own VPC.

// stacks/rds.stack.ts
interface Props extends StackProps {
  vpc: IVpc;
  dbConfig: Pick<DatabaseConfig, 'database' | 'username' | 'password'>;
  securityGroup: SecurityGroup;
}

export class RdsStack extends Stack {
  public readonly db: DatabaseInstance;

  constructor(scope: Construct, id: string, props: Props) {
    super(scope, id, props);

    this.db = new DatabaseInstance(this, 'exanubes-database', {
      engine: DatabaseInstanceEngine.POSTGRES,
      vpc: props.vpc,
      credentials: {
        username: props.dbConfig.username,
        password: SecretValue.plainText(props.dbConfig.password),
      },
      databaseName: props.dbConfig.database,
      storageType: StorageType.STANDARD,
      instanceType: InstanceType.of(
        InstanceClass.BURSTABLE3,
        InstanceSize.SMALL
      ),
      securityGroups: [props.securityGroup],
      parameterGroup: ParameterGroup.fromParameterGroupName(
        this,
        'postgres-instance-group',
        'postgresql13'
      ),
    });
  }
}

Here we're creating a new database instance and assigning it to a property on the RdsStack. This is also the place where we define our vpc as the location of our database. AWS will put it in a private subnet by default, however, if you wish to have more control over it, you can use subnetGroup and vpcSubnets properties.

Moving on, we define credentials for the database and the database name as well as the type and size of the instance. We're using the cheapest options with standard storage type. Last but not least we're pointing to a postgres version inside RDS parameter groups that we want to use for our database.

Should you have an error related to invalid/non-existent parameterGroup, you will have to go to RDS>Parameter Groups and create it yourself

CI/CD Pipeline

With RDS Instance created, we still need a way to synchronize the database, create tables, add columns etc. and obviously we want to automate it. To accomplish that, we will be adding an additional step to the existing CodePipeline.

// stacks/pipeline.stack.ts

private getMigrationSpec() {
    return BuildSpec.fromObject({
      version: "0.2",
      env: {
        shell: "bash",
      },
      phases: {
        install: {
          commands: ["(cd ./backend && npm install)"],
        },
        build: {
          commands: [
            "./backend/node_modules/.bin/sequelize db:migrate --debug --migrations-path ./backend/db/migrations --url postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:5432/${DB_NAME}",
          ],
        },
      },
    });
 }

First off we need a buildspec that will install our dependencies. Then we will use Sequelize CLI to run a migration command against our database.

// stacks/pipeline.stack.ts
const migrationProject = new Project(this, 'migration-project', {
  projectName: 'migration-project',
  securityGroups: [props.securityGroup],
  vpc: props.vpc,
  buildSpec: this.getMigrationSpec(),
  source,
  environment: {
    buildImage: LinuxBuildImage.AMAZON_LINUX_2_ARM_2,
    privileged: true,
  },
  environmentVariables: {
    DB_USER: {
      value: props.dbConfig.username,
    },
    DB_PASSWORD: {
      value: props.dbConfig.password,
    },
    DB_HOST: {
      value: props.dbConfig.hostname,
    },
    DB_PORT: {
      value: props.dbConfig.port,
    },
    DB_NAME: {
      value: props.dbConfig.database,
    }
  },
});

Now, defining a separate Project for the migration step. Most of the configuration is the same as in ECS with CI/CD what changed is the fact that we actually need to assign it to our own VPC to be able to reach the RDS Instance. We're also adding a security group to be able to communicate with the database. More on that later. This is also the place where we can pass all the relevant environmental variables i.e. database credentials.

// stacks/pipeline.stack.ts
  const pipelineActions = {
    //...
    migrate: new CodeBuildAction({
      actionName: 'dbMigrate',
      project: migrationProject,
      input: artifacts.source,
    }),
  };

  const pipeline = new Pipeline(this, 'DeployPipeline', {
    pipelineName: `exanubes-pipeline`,
    stages: [
      { stageName: 'Source', actions: [pipelineActions.source] },
      { stageName: 'Build', actions: [pipelineActions.build] },
      { stageName: 'Migrate', actions: [pipelineActions.migrate] },
      {
        stageName: 'Deploy',
        actions: [pipelineActions.deploy],
      },
    ],
  });
}

To finish it off we define a CodeBuildAction using the new project and the source Artifact and then finally add the Migrate stage to the pipeline.

Update build project

Now, because app's Dockerfile slightly changed, we have to update the build project and spec.

First we add AWS_ACCESS_KEY, AWS_SECRET_ACCESS_KEY environment variables to the buildProject.

// stacks/pipeline.stack.ts
  AWS_ACCESS_KEY: {
    value: AWS_ACCESS_KEY,
  },
  AWS_SECRET_ACCESS_KEY: {
    value: AWS_SECRET_ACCESS_KEY,
  }

And now we have to update the build property of the buildSpec to account for the new environment variables

// stacks/pipeline.stack.ts
 build: {
    commands: [
      "echo Build started on `date`",
      "echo Build Docker image",
      "docker build -f ${CODEBUILD_SRC_DIR}/backend/Dockerfile --build-arg region=${AWS_STACK_REGION} --build-arg clientId=${AWS_ACCESS_KEY} --build-arg clientSecret=${AWS_SECRET_ACCESS_KEY} -t ${REPOSITORY_URI}:latest ./backend",
      'echo Running "docker tag ${REPOSITORY_URI}:latest ${REPOSITORY_URI}:${IMAGE_TAG}"',
      "docker tag ${REPOSITORY_URI}:latest ${REPOSITORY_URI}:${IMAGE_TAG}",
    ],
  }

The only real difference here is that we provide --build args to the build command to set the relevant environment variables that are required to establish a connection with aws.

SSM Parameter Store

In order to be able to connect with a database we need to know the location and credentials. I have opted for Parameter Store as I find it a very convenient way to organize environment variables.

// stacks/parameter-store.stack.ts
interface Props extends StackProps {
  dbConfig: DatabaseConfig;
}

export class ParameterStoreStack extends Stack {
  constructor(scope: Construct, id: string, props: Props) {
    super(scope, id, props);
    new SecureStringParameter(this, 'database-password', {
      parameterName: '/production/database/password',
      stringValue: props.dbConfig.password,
      tier: ParameterTier.STANDARD,
      dataType: ParameterDataType.TEXT,
    });
    new StringParameter(this, 'database-user', {
      parameterName: '/production/database/username',
      stringValue: props.dbConfig.username,
      tier: ParameterTier.STANDARD,
      dataType: ParameterDataType.TEXT,
    });
    new StringParameter(this, 'database-hostname', {
      parameterName: '/production/database/hostname',
      stringValue: props.dbConfig.hostname,
      tier: ParameterTier.STANDARD,
      dataType: ParameterDataType.TEXT,
    });
    new StringParameter(this, 'database-port', {
      parameterName: '/production/database/port',
      stringValue: String(props.dbConfig.port),
      tier: ParameterTier.STANDARD,
      dataType: ParameterDataType.TEXT,
    });
    new StringParameter(this, 'database-socket-address', {
      parameterName: '/production/database/socketAddress',
      stringValue: props.dbConfig.socketAddress,
      tier: ParameterTier.STANDARD,
      dataType: ParameterDataType.TEXT,
    });
    new StringParameter(this, 'database-database', {
      parameterName: '/production/database/name',
      stringValue: props.dbConfig.database,
      tier: ParameterTier.STANDARD,
      dataType: ParameterDataType.TEXT,
    });
  }
}

All we do here is create string parameters for database credentials and location. Password is created as a secure string, meaning it is encrypted using AWS KMS.

SecureStringParameter is imported from @exanubes/aws-cdk-ssm-secure-string-parameter because of limitations of AWS CloudFormation. This construct utilises a Lambda and AWS SDK to create the secure string parameter.

Access and firewall management

All the resources are in place, we have a RDS instance, a migration stage in CI/CD pipeline and parameters for the application. However, we still need to handle access permissions to the database for both the pipeline stage as well as the fargate service. We also need to configure the firewall to allow traffic from those origins. This can be managed with security groups.

// stacks/security-group.stack.ts

interface Props extends StackProps {
  vpc: IVpc;
}

export class SecurityGroupStack extends Stack {
  databaseSg: SecurityGroup;
  databaseAccessSg: SecurityGroup;

  constructor(scope: Construct, id: string, props: Props) {
    super(scope, id, props);
    this.databaseAccessSg = new SecurityGroup(this, 'database-access-sg', {
      vpc: props.vpc,
      description:
        'Security group for resources that need access to rds database instance',
    });

    this.databaseSg = new SecurityGroup(this, 'rds-allow-postgres-traffic', {
      vpc: props.vpc,
      description: 'Security group for rds database instance',
    });
    this.databaseSg.addIngressRule(
      this.databaseAccessSg,
      Port.tcp(5432),
      `Allow inbound connection on port 5432 for resources with security group: "${this.databaseAccessSg.securityGroupId}"`
    );
  }
}

Here we're creating two security groups in our vpc. The databaseSg is for opening up the 5432 port on database instance and I'm using databaseAccessSg as source. This way, every resource that has databaseAccessSg assigned will have access to the database and if I want to revoke access, I can just remove the security group from that service.

This is not all though. We still need to grant connection permissions to the instances.

// stacks/pipeline.stack.ts
props.rds.grantConnect(migrationProject.grantPrincipal);

// stacks/elastic-container.stack.ts
const taskRole = new Role(this, 'exanubes-fargate-application-role', {
  assumedBy: new ServicePrincipal('ecs-tasks.amazonaws.com'),
});
props.rds.grantConnect(taskRole);
const taskDefinition = new FargateTaskDefinition(
  this,
  'fargate-task-definition',
  {
    runtimePlatform: {
      cpuArchitecture: CpuArchitecture.ARM64,
      operatingSystemFamily: OperatingSystemFamily.LINUX,
    },
    taskRole,
  }
);

// stacks/elastic-container.stack.ts
this.service.connections.allowToDefaultPort(props.rds);

First we go into pipeline stack and grant connect permission to our migration project principal. Then we have to do the same inside the elastic stack. To do this we create a task role for the ecs-tasks principal which basically defines which entity - user, app, organization, service etc. - can perform actions with this role. Then we grant connect permissions to this role and use it in Fargate Task Definition construct. Lastly, we also have to allow Fargate Service to establish a connection with RDS Instance.

You can find a list of service principals in this gist

Due to circular dependency error when using a Security Group, we have to add the rds connection manually via the .allowToDefaultPort() method.

Connecting to RDS

Now that everything is setup, we can use AWS SDK to load the database credentials.

// backend/src/config/config.provider.ts

async () => {
  const isProd = process.env.NODE_ENV === 'production';
  if (!isProd) {
    return config;
  }
  const client = new SSMClient({
    region: String(process.env.region),
    credentials: {
      accessKeyId: String(process.env.clientId),
      secretAccessKey: String(process.env.clientSecret),
    },
  });
  const command = new GetParametersByPathCommand({
    Path: '/production',
    Recursive: true,
    WithDecryption: true,
  });
  const result = await client.send(command);
  return transformParametersIntoConfig(result.Parameters || []);
};

Here, we setup the client with credentials passed in to the Dockerfile in the Build Stage of our CI/CD pipeline. Then we can just load all the parameters prefixed with /production and transform it into a simpler to use data structure. I used the WithDecryption option in order to get a decrypted value of the database password parameter.

Deployment

While deployment is in progress, remember to push the initial image to ECR, otherwise the deployment will hang on ElasticContainerStack. Once all the stacks have been deployed, we're going to need to trigger the pipeline which will trigger the migration after which we should be able to see the data on /users endpoint. That tells us we're connected!

npm run build && npm run cdk:deploy -- --all

Before deploying make sure that all the secrets and ARNs are your own. Double check the src/config.ts and .env files.

Don't forget to tear down the infrastructure to avoid unnecessary costs

npm run cdk:destroy -- --all

Summary

In this article we have gone through setting up a Database Instance, configuring the user, name, size and engine. Then, we have used it for the CI/CD pipeline in order to run a migration script as part of the automated deployment strategy. To be able to connect to the database from our application, we have saved all relevant database information in SSM Parameter Store and used the AWS SDK in the app to load the config. Lastly, we have opened up the 5432 port on the RDS Instance to our migration stage and ECS Service and granted connection permissions to them, following the principle of least privilege.

CI/CD pipeline for ECS application

exanubes — Wed, 28 Sep 2022 08:12:16 +0000

Any modern application these days needs to have an automated deployment process. Usually it is setup via a webhook, other times we need to manually trigger the deployment, sometimes even requiring more than one person to approve. In this article we will learn how to build a CI/CD pipeline for an ECS Fargate application utilising AWS Code Pipeline, Code Build and Code Deploy services. By the end of this article, we will be able to automatically deploy a new version of our application by simply pushing new commits to the master branch of a Github repository.

Starting point

As you can see in the diagram, we're starting off with a Load Balanced Fargate Cluster inside a VPC. The application is secured with an SSL certificate on a custom domain. Download code from the previous article about adding SSL certificate to a Fargate app if you'd like to follow along. Keep in mind you will need a SSL certificate and a hosted zone to get this to work. If you'd like to see the finished code for this article, you can find it on github.

Configuring Github Credentials

Starting off, we need to define the source of our application's sourcecode. In this case, we're going to use github.

// lib/pipeline.stack.ts

interface Props extends StackProps {}
const secretConfig = {
  arn: "arn:aws:secretsmanager:eu-central-1:145719986153:secret:github/token",
  id: "github/token",
}
export class PipelineStack extends Stack {
  constructor(scope: Construct, id: string, private readonly props: Props) {
    super(scope, id, props)
    new GitHubSourceCredentials(this, "code-build-credentials", {
      accessToken: SecretValue.secretsManager(secretConfig.id),
    })
  }
}

As you can see, we're loading up a github token from the Secrets Manager. Here's a quick guide on how to generate and store a personal access token. This piece of code tells Code Build what credentials to use when communicating with Github API. Important to note that AWS allows only one Github credential per account per region.

Code Source

Now that Code Build is authorized to communicate with GitHub in our name, we can define where it should take the code from

// lib/pipeline.stack.ts
const githubConfig = {
  owner: "exanubes",
  repo: "ecs-fargate-ci-cd-pipeline",
  branch: "master",
}

const source = Source.gitHub({
  owner: githubConfig.owner,
  repo: githubConfig.repo,
  webhook: true,
  webhookFilters: [
    FilterGroup.inEventOf(EventAction.PUSH).andBranchIs(githubConfig.branch),
  ],
})

This is how we can subscribe to a Github Webhook that will trigger an event every time someone pushes to a master branch in the ecs-fargate-ci-cd-pipeline repo that belongs to exanubes.

Build spec

// lib/pipeline.stack.ts

private getBuildSpec() {
    return BuildSpec.fromObject({
        version: '0.2',
        env: {
            shell: 'bash'
        },
        phases: {
            pre_build: {
                commands: [
                    'echo logging in to AWS ECR',
                    'aws --version',
                    'echo $AWS_STACK_REGION',
                    'echo $CONTAINER_NAME',
                    'aws ecr get-login-password --region ${AWS_STACK_REGION} | docker login --username AWS --password-stdin ${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_STACK_REGION}.amazonaws.com',
                    'COMMIT_HASH=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-7)',
                    'echo $COMMIT_HASH',
                    'IMAGE_TAG=${COMMIT_HASH:=latest}',
                    'echo $IMAGE_TAG'
                ],
            },
            build: {
                commands: [
                    'echo Build started on `date`',
                    'echo Build Docker image',
                    'docker build -f ${CODEBUILD_SRC_DIR}/backend/Dockerfile -t ${REPOSITORY_URI}:latest ./backend',
                    'echo Running "docker tag ${REPOSITORY_URI}:latest ${REPOSITORY_URI}:${IMAGE_TAG}"',
                    'docker tag ${REPOSITORY_URI}:latest ${REPOSITORY_URI}:${IMAGE_TAG}'
                ],
            },
            post_build: {
                commands: [
                    'echo Build completed on `date`',
                    'echo Push Docker image',
                    'docker push ${REPOSITORY_URI}:latest',
                    'docker push ${REPOSITORY_URI}:${IMAGE_TAG}',
                    'printf "[{\\"name\\": \\"$CONTAINER_NAME\\", \\"imageUri\\": \\"$REPOSITORY_URI:$IMAGE_TAG\\"}]" > docker_image_definition.json'
                ]
            }
        },
        artifacts: {
            files: ['docker_image_definition.json']
        },
    })
}

Lots of cool things happening here. First of all, the build spec are instructions for Code Build on how it should handle building our projects. AWS provides us with some life cycle hooks so we can decide at what point in the life cycle of the build process certain actions should happen. The version key/pair defines the version of the build spec API, 0.2 is the most recent version at the time of writing.

Starting out, we have a pre_build life cycle hook, here we're checking our environment, logging into docker with ECR credentials and creating an image tag from a commit sha.

Moving over to the build stage of the life cycle, it's time to build the Dockerfile image. The repository I'm using has both backend and infrastructure code in it so we have to define the path to the Dockerfile as well as the execution context both of which are inside the /backend directory. Then we just tag it and move over to our post_build commands.

Now we take the REPOSITORY_URI variable and the IMAGE_TAG generated in the pre_build step and we push our image to both the latest tag and our own generated tag in order to keep track of our image versions. Last but not least, we generate a image definitions file that will hold the name of our container and the image uri. This is necessary to substitute our Task Definition's image section with a new image and this will also be the artifact/output of Code Build.

Build config

// lib/pipeline.stack.ts

const stack = Stack.of(this)
const buildSpec = this.getBuildSpec()

const project = new Project(this, "project", {
  projectName: "pipeline-project",
  buildSpec,
  source,
  environment: {
    buildImage: LinuxBuildImage.AMAZON_LINUX_2_ARM_2,
    privileged: true,
  },
  environmentVariables: {
    REPOSITORY_URI: {
      value: props.repository.repositoryUri,
    },
    AWS_ACCOUNT_ID: {
      value: stack.account,
    },
    AWS_STACK_REGION: {
      value: stack.region,
    },
    GITHUB_AUTH_TOKEN: {
      type: BuildEnvironmentVariableType.SECRETS_MANAGER,
      value: secretConfig.arn,
    },
    CONTAINER_NAME: {
      value: props.container.containerName,
    },
  },
})

Since we know where to look for application sourcecode and we know how to build the app, we can now create a Code Build project to put this all together.

Our Fargate application is running on ARM64 architecture and unfortunately the version of docker in codebuild does not support defining a platform when building an image. This is why we have to explicitly set the buildImage to Linux ARM64 Platform in the environment settings.

In the buildspec we're using quite a few environment variables and this is where we set it. Some of them will come from other stacks, we also have to use the github secret arn that we created in the beginning but also use some stack config.
For this, we're gonna use Stack.of(this) to get the scope of our current stack.

We also have to update our Props interface as we're relying on components from other stacks.

// lib/pipeline.stack.ts
interface Props extends StackProps {
  repository: IRepository
  service: IBaseService
  cluster: ICluster
  container: ContainerDefinition
}

Permissions

As everything in AWS, Code Build needs to have relevant permissions to be able to interface with other services.

// lib/pipeline.stack.ts

project.addToRolePolicy(
  new PolicyStatement({
    actions: ["secretsmanager:GetSecretValue"],
    resources: [secretConfig.arn],
  })
)
props.repository.grantPullPush(project.grantPrincipal)

First off, we gotta give the Code Build Project access to our github access token from the Secrets Manager. It's also going to pull and push to and from the ECR repository.

Defining pipeline actions

We can finally start creating the different actions for our pipeline. We will have a source action – downloading code from Github – a build action for building the docker image and pushing it to the ECR repository, and to finish it off we'll have a deploy action that will take the output of the build action – BuildOutput Artifact – and use it to deploy a new version of our application on ECS.

// lib/pipeline.stack.ts
const artifacts = {
  source: new Artifact("Source"),
  build: new Artifact("BuildOutput"),
}
const pipelineActions = {
  source: new GitHubSourceAction({
    actionName: "Github",
    owner: githubConfig.owner,
    repo: githubConfig.repo,
    branch: githubConfig.branch,
    oauthToken: SecretValue.secretsManager("github/cdk-pipeline"),
    output: artifacts.source,
    trigger: GitHubTrigger.WEBHOOK,
  }),
  build: new CodeBuildAction({
    actionName: "CodeBuild",
    project,
    input: artifacts.source,
    outputs: [artifacts.build],
  }),
  deploy: new EcsDeployAction({
    actionName: "ECSDeploy",
    service: props.service,
    imageFile: new ArtifactPath(
      artifacts.build,
      "docker_image_definition.json"
    ),
  }),
}

Let's start with defining our artifacts – the output of a particular action in the pipeline – which will be stored in CodePipeline's S3 Bucket. Each subsequent action will use the previous action's artifact so this is very important. In this pipeline we only have two artifacts, first one will be the code downloaded from the repository. The source Artifact will be the input for the build action and as per the build spec we're going to output the image definition file – docker_image_definition.json – as build output Artifact. This is then used in the deploy action and we're passing that file to be used during deployment.

Defining pipeline stages

Now that we have everything setup, we can finally define the pipeline stages and assign appropriate actions to them.

// lib/pipeline.stack.ts
const pipeline = new Pipeline(this, "DeployPipeline", {
  pipelineName: `exanubes-pipeline`,
  stages: [
    { stageName: "Source", actions: [pipelineActions.source] },
    { stageName: "Build", actions: [pipelineActions.build] },
    { stageName: "Deploy", actions: [pipelineActions.deploy] },
  ],
})

In this simple example we have only one action per stage but nothing's stopping us from adding another action that will run integration tests in the Build stage, for example.

Deployment

Now that our pipeline is ready, there's still a few things we need to sort out. Because our pipeline needs environment variables such as account id and region, we actually have to explicitly pass those to our stacks.

// bin/infrastructure.stack.ts
import {
  getAccountId,
  getRegion,
  resolveCurrentUserOwnerName,
} from "@exanubes/cdk-utils"

async function start(): Promise<void> {
  const owner = await resolveCurrentUserOwnerName()
  const account = await getAccountId()
  const region = await getRegion()
  const env: Environment = { account, region }
  const app = new cdk.App()
  const ecr = new EcrStack(app, EcrStack.name, { env })
  const vpc = new VpcStack(app, VpcStack.name, { env })
  const ecs = new ElasticContainerStack(app, ElasticContainerStack.name, {
    vpc: vpc.vpc,
    repository: ecr.repository,
    env,
  })
  new Route53Stack(app, Route53Stack.name, {
    loadBalancer: ecs.loadBalancer,
    env,
  })
  new PipelineStack(app, PipelineStack.name, {
    repository: ecr.repository,
    service: ecs.service,
    cluster: ecs.cluster,
    container: ecs.container,
    env,
  })
  Tags.of(app).add("owner", owner)
}

start().catch(error => {
  console.log(error)
  process.exit(1)
})

Here we're getting the account and region from utility functions I've imported from @exanubes/cdk-utils that use AWS SDKv3. Then I pass them to every stack as it often happens that there are errors when one stack has explicitly set env and others do not so I recommend passing it to all stacks as those errors can be quite difficult to debug sometimes.

Important to note that we're also passing repository, service, cluster and container to the pipeline stack as it relies on references to these resources. Do make sure that they're available on your ElasticContainerStack instance.

// lib/elastic-container.stack.ts
public readonly container: ContainerDefinition
public readonly service: FargateService
public readonly cluster: Cluster

I've also added an owner tag – your account name – to each resource for good measure.

Now we can build and deploy

npm run build && npm run cdk:deploy -- --all

Keep in mind you will have to upload your first image to ECR otherwise deployment will hang on ElasticContainerStack. This can be done during the deployment as stacks are deployed in a sequence and ECR is the first one. After deploying the infrastructure, try and make changes in the app.service.ts file and see if the automatic deployment works when you push to your repository.

Don't forget to destroy the stack when you're done

npm run cdk:destroy -- --all

Summary

In this article we were able to take our current application infrastructure and add a CI/CD pipeline to it. First we defined how Code Build should talk to the Github API by defining credentials. Then we needed to create a buildspec which would instruct Code Build on how to build our application by utilising different life cycle hooks of the entire process. Last but not least we output a BuildOutput Artifact that can then be used by Code Deploy to update our app.

Adding SSL Certificate to Fargate app

exanubes — Tue, 20 Sep 2022 12:04:49 +0000

Previously, we were able to deploy a simple Nestjs web server to ECS fargate and serve it through a load balancer. However, that connection is not secure and the url is not very user friendly so in this article we will go over serving the application with our own domain name and securing it with a SSL Certificate.

The starting point for this article is the repository for deploying application to ECS Fargate.
You can find the finished code on github.

Requirements

To follow along you will definitely need a domain name. Should you have a domain outside of aws you can checkout this article to create a hosted zone in AWS with your existing domain – moving domain over to AWS not required. Other than that, you will also need to generate a certificate for your domain in the AWS Certificate Manager in the same region as your ECS deployment.

Adding a certificate to load balancer

To serve our application over https we're going to need a couple things. First we need to add a listener to our Load Balancer with https protocol and port 443, this will also require from us to provide a certificate. Then, we will need to open up the port 443 in Load Balancer's security group to allow traffic on that port.

// lib/elastic-container.stack.ts
const CERTIFICATE_ARN =
  'arn:aws:acm:eu-central-1:123456789012:certificate/uuid';

albSg.addIngressRule(Peer.anyIpv4(), Port.tcp(443));
const sslListener = this.loadBalancer.addListener('secure https listener', {
  port: 443,
  open: true,
  sslPolicy: SslPolicy.RECOMMENDED,
  certificates: [{ certificateArn: CERTIFICATE_ARN }],
});

const targetGroup = sslListener.addTargets('tcp-listener-target', {
  targetGroupName: 'tcp-target-ecs-service',
  protocol: ApplicationProtocol.HTTP,
  protocolVersion: ApplicationProtocolVersion.HTTP1,
});

Here, we have also assigned our target group to the sslListener rather than httpListener. Speaking of which, it would be good to redirect users to https even if they're using http.

// lib/elastic-container.stack.ts
const httpListener = this.loadBalancer.addListener('http listener', {
  port: 80,
  open: true,
  defaultAction: ListenerAction.redirect({
    port: '443',
    protocol: ApplicationProtocol.HTTPS,
  }),
});

By changing the default behaviour, we can reroute all requests on port 80 to port 443 – HTTPS – then we will use our target group and route users to our app.

Last but not least, we will need access to the load balancer in the next step, so we need to assign it to a property on the stack instance.

// lib/elastic-container.stack.ts
this.loadBalancer = new ApplicationLoadBalancer(...)

Assigning domain

Now that we've assigned a certificate to the load balancer, we only have to create an appropriate DNS Record to be able to use the domain along with our SSL Certificate.

For this we will need to things: hosted zone id and hosted zone name. The hosted zone name is the domain name or subdomain you used to create your hosted zone, e.g., dev.exanubes.com. Both hosted zone id and hosted zone name can be found in Route 53 > Hosted zones

Now, once you have this, we can create an instance of our existing hosted zone.

// lib/route53.stack.ts
interface Props extends StackProps {
  loadBalancer: IApplicationLoadBalancer;
}
const HOSTED_ZONE_ID = 'YOUR_HOSTED_ZONE_ID';
export class Route53Stack extends Stack {
  constructor(scope: Construct, id: string, props: Props) {
    super(scope, id, props);
    const hostedZone = HostedZone.fromHostedZoneAttributes(
      this,
      'hosted-zone',
      {
        hostedZoneId: HOSTED_ZONE_ID,
        zoneName: 'dev.exanubes.com',
      }
    );
  }
}

And finally, we can create an Alias and use the Load Balancer as target.

// lib/route53.stack.ts
new ARecord(this, 'ecs-alb-alias-record', {
  zone: hostedZone,
  target: RecordTarget.fromAlias(
    new targets.LoadBalancerTarget(props.loadBalancer)
  ),
});

Deployment

Now it's time to create our stacks and deploy

// bin/ecs-fargate-deployment.ts
const app = new cdk.App();
const ecr = new EcrStack(app, EcrStack.name, {});
const vpc = new VpcStack(app, VpcStack.name, {});
const ecs = new ElasticContainerStack(app, ElasticContainerStack.name, {
  vpc: vpc.vpc,
  repository: ecr.repository,
});
new Route53Stack(app, Route53Stack.name, { loadBalancer: ecs.loadBalancer });

Here, you can see why we needed to assign load balancer to a public property on the class instance as we are passing it to the Route53Stack.

When deploying, keep in mind you will have to upload a Docker Image, otherwise it will hang when deploying the ElasticContainerStack, you can do it while it's deploying all stacks or deploy EcrStack first:

npm run build && npm run cdk:deploy EcrStack

and after pushing a Docker Image to ECR:

npm run cdk:deploy -- --all

Now you can go to the domain name you chose for the application and it should automatically redirect you to a secure connection – https.

Don't forget to tear it all down when you're done:

npm run cdk:destroy -- --all

Summary

To sum up, in this article we've successfully reached our application via our own domain name and secured it with an SSL Certificate.

However, this is not yet a modern application as each time we'd like to release a new version, we'd have to manually go through the release process. Next up, deploying Fargate application with a CI/CD Pipeline.

Deploying ECS Fargate Application

exanubes — Tue, 13 Sep 2022 14:51:38 +0000

In this article we will build and deploy a simple NestJS application on ECS Fargate. To do that we will upload a Docker Image to our ECR Repository. Then we'll create a simple vpc where we will put our application. Next, we will go ahead and create ECS Cluster which will spin-up a Fargate Service
from a Task Definition which will be using the aforementioned Docker Image. After all this, we will setup a Load Balancer that will be listening on port 80 and redirecting all traffic to a Target Group which will have our ECS Task instances automatically registered as targets of the Load Balancer.

You can find the finished code on Github

ECR Stack

First off, we need a repository for the Docker image of our application. We need to do this first because later ECS Service will be pulling this image in order to start a task.

// lib/ecr.stack.ts
export class EcrStack extends Stack {
  public readonly repository: IRepository;

  constructor(app: Construct, id: string, props: StackProps) {
    super(app, id, props);
    this.repository = new Repository(this, 'exanubes-repository', {
      imageScanOnPush: false,
      removalPolicy: RemovalPolicy.DESTROY,
    });
  }
}

All we do here is create a ECR Repo. The imageScanOnPush option would look for vulnerabilities in our image but we don't need it right now so it's turned off.

Now we can put it in the bin file...

//bin/infrastructure.ts
const app = new cdk.App();
const ecr = new EcrStack(app, EcrStack.name, {});

...and deploy

npm run build && npm run cdk:deploy -- --all

Uploading a Docker Image

Now, if you go to ECR in the AWS Console and check your repository, you should have a View push commands button in the top right corner. Go to your application directory where you have a Dockerfile – or use nest app from the repo – and follow these instructions with one caveat.
We will be deploying ECS Fargate with the ARM64 architecture as it is cheaper, so unless you have a computer with a ARM64 processor e.g., Apple Silicone, you will have to change the second step to:

docker buildx build --platform="linux/arm64" -t <image-tag> .

When successful you should see your docker image in ECR as so:

VPC Stack

Before getting started on the ECS, first we need to create a VPC to put it in. We could – of course – use the default VPC for this as well.

// lib/vpc.stack.ts
export class VpcStack extends Stack {
  public readonly vpc: IVpc;
  constructor(scope: Construct, id: string, props: StackProps) {
    super(scope, id, props);
    this.vpc = new Vpc(this, 'exanubes-vpc', {
      cidr: '10.100.0.0/16',
      maxAzs: 2,
      subnetConfiguration: [
        {
          name: 'public-1',
          cidrMask: 24,
          subnetType: SubnetType.PUBLIC,
        },
        {
          name: 'private-1',
          cidrMask: 24,
          subnetType: SubnetType.PRIVATE_WITH_NAT,
        },
      ],
    });
  }
}

We're defining here a 10.100.0.0 with the size 16 CIDR block – this basically means that the first 16 bits are locked and the other 16 bits are available for us to use, so essentially we have 255*255 IP addresses available to us.
Selecting only two azs to have high availability – one would also be fine for this – and defining only one public and private subnet for each AZ – so we will have 4 in total.

Worth noticing is that we assigned the vpc to a property on the class instance, that's because we will want to pass that vpc to our ECS Cluster later.

ECS Stack

First off, we gotta create a cluster, which is just a logical grouping of tasks and services. All the tasks and services are running on an infrastructure registered to a cluster. When separating resources, we'd want to deploy multiple clusters.

// lib/elastic-container.stack.ts

interface Props extends StackProps {
  vpc: IVpc;
  repository: IRepository;
}

const CONTAINER_PORT = 8081;

export class ElasticContainerStack extends Stack {
  constructor(scope: Construct, id: string, private readonly props: Props) {
    super(scope, id, props);
    const cluster = new Cluster(this, 'exanubes-cluster', {
      vpc: props.vpc,
      clusterName: 'exanubes-cluster',
      containerInsights: true,
    });
  }
}

Here, we're creating a cluster and putting it inside the VPC we created earlier. Container Insights are CloudWatch performance logs that will be collected which we can later aggregate and analyze to see how our containers perform.

// lib/elastic-container.stack.ts

const albSg = new SecurityGroup(this, 'security-group-load-balancer', {
  vpc: props.vpc,
  allowAllOutbound: true,
});

const loadBalancer = new ApplicationLoadBalancer(this, 'exanubes-alb', {
  vpc: props.vpc,
  loadBalancerName: 'exanubes-ecs-alb',
  internetFacing: true,
  idleTimeout: Duration.minutes(10),
  securityGroup: albSg,
  http2Enabled: false,
  deletionProtection: false,
});

Next, we need an Application Load Balancer(ALB) and a security group(SG) for it. CDK would create a default SG but we will then need to allow traffic from it to the ECS Service, so I prefer to create it explicitly.
ALB will also be placed inside our VPC and most importantly we need to have it open to the internet – internet facing. Deletion Protection ensures that no one removes a load balancer by accident as it first needs to be disabled before being deleting when protection's enabled.

// lib/elastic-container.stack.ts
const httpListener = loadBalancer.addListener('http listener', {
  port: 80,
  open: true,
});

const targetGroup = httpListener.addTargets('tcp-listener-target', {
  targetGroupName: 'tcp-target-ecs-service',
  protocol: ApplicationProtocol.HTTP,
  protocolVersion: ApplicationProtocolVersion.HTTP1,
});

When users visit our domain they will actually hit the load balancer which then needs to know how to reach our application. We achieve this with listeners and target groups.
A listener tells the load balancer on what port it should expect traffic, then it has three options - forward, redirect or custom response. We can also define rules and depending on headers, request methods, path or query strings we can tell the Load Balancer to route to a different target group.
Whereas target group routes requests to registered targets – which in our case will be the ECS Fargate Task.

// lib/elastic-container.stack.ts
const taskDefinition = new FargateTaskDefinition(
  this,
  'fargate-task-definition',
  {
    runtimePlatform: {
      cpuArchitecture: CpuArchitecture.ARM64,
      operatingSystemFamily: OperatingSystemFamily.LINUX,
    },
  }
);
const container = taskDefinition.addContainer('web-server', {
  image: EcrImage.fromEcrRepository(props.repository),
});
container.addPortMappings({
  containerPort: CONTAINER_PORT,
});

Now it's finally time to create our Task Definition. This is similar to a Docker Image, which is an instruction manual on how to build and run the application. Task definition is a manual on how to perform a task, which and how many containers to use, how much CPU and memory etc.
A task definition is also where we define what architecture – or runtime platform – we'd like to use. Because it's significantly cheaper, we opt for Linux OS on ARM64 machine.

When creating a container, we also have to tell ECS what port it's going to run on – this should be the same port we expose in the Dockerfile.

// lib/elastic-container.stack.ts

const securityGroup = new SecurityGroup(this, 'http-sg', {
  vpc: props.vpc,
});
securityGroup.addIngressRule(
  Peer.securityGroupId(albSg.securityGroupId),
  Port.tcp(CONTAINER_PORT),
  'Allow inbound connections from ALB'
);
const fargateService = new FargateService(this, 'fargate-service', {
  cluster,
  assignPublicIp: false,
  taskDefinition,
  securityGroups: [securityGroup],
  desiredCount: 1,
});

Nearing the end, we can finally create an ECS Service. The difference between tasks and services are that a task does a finite job and then exits, whereas service is more for infinite tasks like a web server for example.
We need to define which cluster the service belongs to and what task definition it's supposed to use to spin-up tasks. We can also opt-out of assigning public IP addresses as we won't be needing those.
Desired count is the minimum amount of tasks that the service will attempt to keep running at all times. We choose 1 to keep the costs low, make sure you don't put some ridiculously large number here as it could cost you a lot of money.

// lib/elastic-container.stack.ts

targetGroup.addTarget(fargateService);

Last but not least, a very important step. We're adding the ECS Service as target to the target group. Thanks to this, target group will automatically register all new Tasks and make them available to the load balancer and thus, the end user.

All of ElasticContainerStack

// lib/elastic-container.stack.ts
interface Props extends StackProps {
    vpc: IVpc
    repository: IRepository
}

const CONTAINER_PORT = 8081

export class ElasticContainerStack extends Stack {

    constructor(scope: Construct, id: string, private readonly props: Props) {
        super(scope, id, props);
        const cluster = new Cluster(this, 'exanubes-cluster', {
            vpc: props.vpc,
            clusterName: 'exanubes-cluster',
            containerInsights: true,
            enableFargateCapacityProviders: true,
        })
        const albSg = new SecurityGroup(this, 'security-group-load-balancer', {
            vpc: props.vpc,
            allowAllOutbound: true
        })

        const loadBalancer = new ApplicationLoadBalancer(this, 'exanubes-alb', {
            vpc: props.vpc,
            loadBalancerName: 'exanubes-ecs-application-LB',
            internetFacing: true,
            idleTimeout: Duration.minutes(10),
            securityGroup: albSg,
            http2Enabled: false,
            deletionProtection: false
        })

    const httpListener = loadBalancer.addListener("http listener", {
      port: 80,
      open: true,
    })

    const targetGroup = httpListener.addTargets("tcp-listener-target", {
      targetGroupName: "tcp-target-ecs-service",
      protocol: ApplicationProtocol.HTTP,
      protocolVersion: ApplicationProtocolVersion.HTTP1,
    })

        const taskDefinition = new FargateTaskDefinition(this, 'fargate-task-definition', {
            runtimePlatform: {
                cpuArchitecture: CpuArchitecture.ARM64,
                operatingSystemFamily: OperatingSystemFamily.LINUX
            }
        });
        const container = taskDefinition.addContainer('web-server', {
            image: EcrImage.fromEcrRepository(props.repository),
        })
        container.addPortMappings({
            containerPort: CONTAINER_PORT
        })
        const securityGroup = new SecurityGroup(this, 'http-sg', {
            vpc: props.vpc,
        })
        securityGroup.addIngressRule(Peer.securityGroupId(albSg.securityGroupId), CONTAINER_PORT, 'Allow inbound connections from ALB')
        const fargateService = new FargateService(this, 'fargate-service', {
            cluster: cluster,
            assignPublicIp: true,
            taskDefinition,
            securityGroups: [securityGroup],
            desiredCount: 1
        })
        targetGroup.addTarget(fargateService)
    }

Accessing Load Balancer DNS

Now that everything is setup you can go to AWS Console > EC2 > Load Balancers and copy/paste the LB URL, however, for some reason this does not work right now. Could not figure why though so I have a stack overflow question open. This seems to be a common problem from what I could see when researching this and it's always the same – problem with port 80.

Anyway, we can still checkout our app by changing our Load Balancer listener for the container port and also allowing traffic for that port in the Load Balancer Security Group.

// lib/elastic-container.stack.ts
albSg.addIngressRule(Peer.anyIpv4(), Port.tcp(CONTAINER_PORT));

const httpListener = loadBalancer.addListener('http listener', {
  port: CONTAINER_PORT,
  open: true,
});

After changing this in our infrastructure, we should be able to go to load-balancer-dns-example-url.com:YOUR_CONTAINER_PORT.

Deployment

Now it's time to create our stacks and deploy

// bin/infrastructure.ts
const app = new cdk.App();
const ecr = new EcrStack(app, EcrStack.name, {});
const vpc = new VpcStack(app, VpcStack.name, {});
new ElasticContainerStack(app, ElasticContainerStack.name, {
  vpc: vpc.vpc,
  repository: ecr.repository,
});

Deploy:

npm run build && npm run cdk:deploy -- --all

And don't forget to tear it down when you're done:

npm run cdk:destroy -- --all

Summary

In this article we've gone over the most important components of an ECS Fargate application. We created a cluster – which is a logical grouping of tasks and services – inside our custom VPC.
Provided instructions on how our app should function in the Task Definition and instructed how many Tasks we want when creating the Fargate Service.
We were also able to connect to the app by using a load balancer which thanks to its listeners is able to route traffic via a Target Group which automatically registers every new Task in our Service.

Worth noting is that aws-cdk team have prepared for us an ApplicationLoadBalancedFargateService Construct that will set it all up for us as well.

In the next article, we will go over how to setup SSL certificate for our application with a custom domain.