Infrastructure as code (IaC) is the standard practice of defining various infrastructure components using code. You must have heard about a few of these software tools, such as Chef, Puppet, Terraform, or the old-school Bash programming, to set up servers in a predictable way.

The need for IaC was born out of the toolset for spinning up servers circa 2006 lacking the predictability, speed, and agility of the code used in programs that were deployed onto servers. Pre IaC, the normal workflow of deploying something on AWS would be this:

1. Spinning up Elastic Compute Cloud (EC2) servers manually via the dashboard
2. SSHing into the machines
3. Copying some Bash configuration files using Secure Copy Protocol (SCP)
4. Running them in a certain sequence to deploy an application
5. Configuring database connections

This is one of the better scenarios of how things were done back then.

Needless to say, this method was not scalable, repeatable, or reliable enough to deal with the ever-increasing complexity of web applications on the cloud. Around the same time, tools such as Chef, Puppet, and a few others showed up, which helped immensely with server configuration.

A couple of years later, tools such as Terraform popped up, which at the time were quite revolutionary in the way that they defined the desired state of the deployment on a given cloud service provider (CSP) such as Amazon Web Services (AWS) in a declarative fashion. This configuration would then be fed into the Terraform toolset, which would then decide which AWS services needed to be created, deleted, or modified. Let’s look at one such Terraform configuration file:

resource "aws_instance" "single-instance"{
  ami           = "ami-ebd02392"
  instance_type = "t2.micro"
  subnet_id     = "subnet-eddcdzz4"
  vpc_security_group_ids = ["sg-12345678"]
}

The preceding Terraform configuration file defines an AWS EC2 server using the aws_instance resource type provided by Terraform’s AWS provider and then is given an Amazon Machine Image (AMI) configuration (which is essentially the operating system image) instance type to define its CPU and RAM configuration and other network settings. If you have Terraform set up correctly locally, this will investigate your AWS setup, see that this server doesn’t exist, and then proceed to create this server for you.

Obviously, this is a very simple example. There are Terraform configuration projects with many thousand lines of configuration files. These projects can get quite elaborate and out of hand once the complexity of the deployment increases. There are various remedies for this, none of which—in our opinion—really addresses the issue here. Have you spotted the problem?

The problem is that these configurations are not really defined as code. They are defined as declarations in a declarative language that are not Turing Complete code blocks.

In this chapter, we will cover the following main topics:

• Introduction to AWS CDK
• Setting up your local environment and writing your first CDK app
• Creating a containerized web application in AWS CDK using Docker
• Understanding the inner workings of AWS CDK

You will be able to find the code associated with this book in this GitHub repository: https://github.com/PacktPublishing/AWS-CDK-in-Practice.

This repository is organized into directories for each chapter. This code in this chapter can be found in this directory: https://github.com/PacktPublishing/AWS-CDK-in-Practice/tree/main/chapter-1-getting-started-with-iac-and-aws-cdk.

The code examples provided in this book are written in TypeScript. Cloud Development Kit (CDK) supports JavaScript, Python, Java, and C#. We’re sticking with TypeScript since it’s the best supported of the bunch by the CDK development team, and every feature, doc, or material is first released on TypeScript and then translated into other programming languages.

That said, converting the TypeScript code samples in this book into the programming language of your choice is relatively easy since the framework follows a set of common interface definitions. AWS has a handy guide for you: https://docs.aws.amazon.com/cdk/v2/guide/multiple_languages.html.

Do also note that to work with CDK, you will need an AWS account. You can sign up for one here: https://portal.aws.amazon.com/billing/signup.

For more advanced users, we recommend setting up a different AWS organization for working with CDK while you’re learning the ropes so that your development doesn’t interfere with applications that you might have already spun up in your account. You can find out more about AWS Organizations here: https://aws.amazon.com/organizations/.

We also highly recommend setting AWS billing alarms. We will keep things within the free tier of various services as much as we can in this book and will destroy stacks as soon as we’ve spun them up and interacted with them. But it’s best to be on the safe side and set a spending alarm in case mistakes happen or you forget to destroy stacks. A spending alarm of $10 should do the trick. The following link describes how you can do this: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/monitor_estimated_charges_with_cloudwatch.html.

The Code in Action video for this chapter can be viewed at: https://packt.link/nX11h.

In the introduction to this chapter, we covered a basic history of IaC and how these software tools lack the expressiveness of modern programming languages. AWS without a doubt is the frontrunner in the cloud industry, and its answer to difficult infrastructure setup is CDK.

In AWS’s own definition, CDK is an open source software development framework—notice how AWS is not calling it an infrastructure provisioning framework—that defines AWS resources for a cloud application using familiar programming languages.

AWS’s definitiomeans, for example, that instead of defining the EC2 instance using declarative configuration files as we did with Terraform’s HashiCorp Configuration Language (HCL) in the intro, you can define the same instance as the following:

import * as cdk from '@aws-cdk/core'
import * as ec2 from '@aws-cdk/aws-ec2'
 export class MyAppStack extends Stack {
  public readonly default_vpc: IVpc;
  public readonly my_virtual_machine: Instance;
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.default_vpc = Vpc.fromLookup(this, 'VPC', {
      // This will get the default account VPC
      isDefault: true,
    });
    this.my_virtual_machine = new Instance(this, 'single-intance', {
      // The type of instance to deploy (e.g. a 't2.micro')
      instanceType: new InstanceType('t2.micro'),
      // The type of image to use for the instance
      machineImage: new AmazonLinuxImage(),
      // A reference to the object representing the VPC
      vpc: this.default_vpc,
    });
  }
}

Note

Don’t worry about running the code in this section; we will get into that after we’ve completed setting up your local machine for CDK development.

You might (rightfully) think that in terms of lines of code, this doesn’t really save you much time. It’s more or less the same amount of configuration we declare. Let’s see what happens if we want to declare 100 EC2 instances:

import * as cdk from '@aws-cdk/core'
import * as ec2 from '@aws-cdk/aws-ec2'
 export class MyAppStack extends Stack {
  public readonly default_vpc: IVpc;
  public readonly my_virtual_machines: Instance[];
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.default_vpc = Vpc.fromLookup(this, 'VPC', {
      isDefault: true,
    });
    this.my_virtual_machines = [...Array(100).keys()].map(
      i =>
        new Instance(this, `single-intance-${i}`, {
          instanceType: new InstanceType('t2.micro'),
          machineImage: new AmazonLinuxImage(),
          vpc: this.default_vpc,
        }),
    );
  }
}

Are you excited yet? Let’s now imagine we want to deploy 100 EC2 instances and we want every odd one to be a t2.large instance type instead. Let’s also throw in a Simple Storage Service (S3) bucket too and give all the programs that run within our VMs read access to some files in this S3 bucket. Perhaps there is a shell script in there that we want them to run as soon as they spin up. The following CDK code does exactly that:

import { RemovalPolicy, Stack, StackProps } from 'aws-cdk-lib/core';
import { Instance, InstanceType, AmazonLinuxImage, Vpc, IVpc } from 'aws-cdk-lib/aws-ec2';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';
export class MyAppStack extends Stack {
  public readonly bucket: Bucket;
  public readonly default_vpc: IVpc;
  public readonly my_virtual_machines: Instance[];
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.default_vpc = Vpc.fromLookup(this, 'VPC', {
      isDefault: true,
    });
    this.my_virtual_machines = [...Array(100).keys()].map(
      i =>
        new Instance(this, `single-intance-${i}`, {
          instanceType: new InstanceType(i % 2 ? 't2.large' : 't2.micro'),
          machineImage: new AmazonLinuxImage(),
          vpc: this.default_vpc,
        }),
    );
    this.bucket = new Bucket(this, 'MyBucket', {
      removalPolicy: RemovalPolicy.DESTROY,
    });
    this.my_virtual_machines.forEach(virtual_machine => {
      this.bucket.grantRead(virtual_machine);
    });
  }
}

As you can see, CDK is an extremely versatile IaC framework. It unleashes the power of programming languages and compilers to declare highly complex AWS infrastructure with code that is, compared to the alternatives, easily readable and extensible. We can loop, map, reference, write conditions, and—more importantly—use the helper functions CDK provides to simplify the previously daunting task of implementing IaC.

This is a revolutionary concept. Full stack developers no longer must learn convoluted domain-specific languages (DSLs) to interact with AWS services; they can bring their current development skills to the world of cloud provisioning. There is no longer a context switch between development and DevOps. You no longer need to leave your IDE, and you can build and deploy the CDK infrastructure using common tools you’ve previously used—for example, npm.

Additionally, CDK has powerful customization and component sharing baked in. You can create batches of stacks, with your own set of governance and compliance requirements as reusable components. A set of certain EC2 machines with AWS Systems Manager parameter store configuration, security groups, certificates, and load balancers that is common within your stack can then be defined as a component (or in CDK terms, a construct) and then initialized and reused as many times as you desire. This is the true power of CDK, and it unleashes countless new opportunities for developers, as we will explore in the following chapters.

Till now, we’ve learned why CDK is cool. We hope you grow to love the toolset just as much as I do as you apply it to your own programming stack. Let’s now get into the good bits and start off by setting up your local machine for CDK development.

AWS CDK comes with two important tools, as follows:

• The AWS CDK v2 standard library, which includes constructs for each of the AWS services
• The CDK CLI, which is a command-line tool for interacting with apps and stacks

Before setting these up, let’s go ahead and set up AWS’s main CLI application to aid us with our CDK setup and deployments later on.

Setting up the AWS CLI and profile

To use CDK to provision AWS services, we will first need to set up our local machine with the configuration it needs to work with AWS. The easiest way to do this is via the AWS CLI.

Note

The AWS CLI is different from the AWS CDK CLI. The AWS CLI is mainly used to interact with AWS via command-line or Bash scripts, but it also comes in handy when using CDK.

AWS has detailed AWS CLI installation documentation for various operating systems and processor architectures, which can be found by visiting the following link: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html.

Follow the steps required for your operating system and come back here once you’re done.

We hope that wasn’t too painful. we’re on macOS, which seems to have the fewest steps of them all. Next, let’s check the installation was successful by running the following command:

$ aws --version

If all has gone well during the installation process, you should be seeing an output like the following screenshot:

Figure 1.1 – AWS CLI version output

Next, let’s create a separate profile for this book. As mentioned in the Technical requirements section, We highly recommend you create a separate account while you’re developing with CDK rather than using the account you normally use in your day-to-day activities.

Log in to the AWS account of your choosing, and once logged in, type IAM in the search box at the top of the AWS dashboard:

Figure 1.2 – Finding IAM in the sea of AWS services

Click on IAM next, and from the menu on the left, select Users:

Figure 1.3 – Users section in IAM

From the list of users, click on your own username. You will be taken to the user dashboard where the Permissions tab is active:

Figure 1.4 – IAM user roles

As you can see in the preceding screenshot, we’ve given our user AdministratorAccess permissions so that we have free rein on spinning up various services via CDK. Otherwise, we will have to constantly come back here and give ourselves service-specific permissions to spin up services.

If you are the root account holder, you should already have these permissions assigned to you. If not, you can click on Add permissions to search for your username and give yourself this permission, or it might be something that you have to ask your account administrator to do for you.

Important note

It’s generally not advised to use the root account to spin up services via CDK or any other means directly. The root account should be used to give granular permissions to secondary users that can then deploy CDK stacks. We are, for now, skipping such steps to simplify the instructions.

Next, click on the Security credentials tab. Under Access keys, click Create access key. A popup should appear offering you the option to download the credentials as a CSV file or copy them directly from the popup. You can do whichever one of them you like. Once we use the credentials, don’t forget to delete the CSV file on disk.

Now that we have the keys file downloaded from the AWS console, let’s configure our local environment with these given keys. Run the following command:

$ aws configure --profile cdk

You will be prompted to enter the AWS access key ID. You can get this from the CSV file you downloaded or the value you copied over from the previous step. Once you have done this, press Enter.

Next, you will be prompted to enter the AWS secret access key. Just as in the previous step, copy this over and press Enter.

Now you will be prompted to enter a default Region name. We normally work within us-east-1 since it’s one of the cheapest Regions (yes—AWS pricing differs per Region) and one of the first ones to receive new services and products. You can choose a Region near your geographical location if response promptness during the course of this book matters to you. us-east-1 has been selected—off we go.

Last, the tooling will ask you for a default output format; enter json.

Now, let’s make sure you’ve set things up right. To do that, run the following command:

$ aws configure list --profile cdk

If you see an output like the one shown in the following screenshot, voilà! You’re all set:

Figure 1.5 – Checking the configuration with the AWS CLI

Important note

As you see, even though the list command covers most of our keys and secrets, we’re not taking any chances because even the last few characters could be used by a malicious actor for tracking. Keep your AWS keys as secret as your bank account details because if leaked, you could take a considerable financial hit.

Setting up the AWS CDK CLI

The AWS CDK CLI is a command-line tool that is installed as an npm package. If you’re a JavaScript or TypeScript developer, you will have it already installed on your machine; otherwise, here is a link to the Node.js website to install this as well as Node’s package manager, npm: https://nodejs.org/en/download/.

Note

Aim for the Long-Term Support (LTS) version of Node.js when downloading it. Generally, a good habit to hold as a developer is to use LTS versions of their tooling.

Once you have npm running, installing cdk on any operating system can be done by simply running the following command:

$ npm install -g aws-cdk@2.25.0

By running this, we are aiming for a specific version of the CLI, and we will also do the same with the library. CDK changes quite significantly between versions, therefore it’s best for us to focus on a specific version of CDK. Once you’ve learned the ropes, you will be able to upgrade to a later version of it when available. At the time of writing this, 2.25.0 is the latest version of CDK.

Next, type in and run the following command:

$ cdk -h

If you see a bunch of commands like the ones seen in the following screenshot, you’ve done things right:

Figure 1.6 – Making sure the CDK toolset is installed correctly

Great! Now that we have the CDK CLI installed, let’s go ahead and create our first CDK app.

Creating our first CDK app

Go ahead and create a directory on your workspace. In the example code provided, we’ve named it chapter-1-introduction-to-iac-and-aws-cdk. Next, bring up the CLI of your beloved operating system and run the following command inside the directory:

$ cdk init app --language typescript

A bunch of green text should appear while CDK does its magic. Once done, run the ls command to see the top-level folder structure, or even better, if you have the tree command installed, run it as such:

$ tree -I node_modules

The following is what you should be seeing:

Figure 1.7 – Folder structure of our CDK app

If you don’t have tree installed, you can install it with one of the following commands.

On Mac (using the Homebrew package manager), run this command:

brew install tree

On Linux (Ubuntu), run this command:

sudo apt install tree

Note

tree is already installed on Windows 10/11.

We’ve intentionally told the tree command to ignore node_modules since it’s an abyss of directories we don’t need to know about. At a high level, here are explanations of the files and directories:

• README.md is essentially a Markdown documentation file. You must’ve come across it.
• The bin directory is essentially where the top-level CDK app files reside:
  • chapter-1-introduction-to-iac-and-aws-cdk.ts is the file cdk created based on the name of the directory we ran the CLI init command in. This file contains the entry point of the application.
• cdk.json tells the toolkit how to run the application and passes along some further configurations.
• jest.config.js is the configuration file the cdk library uses to run local tests.
• lib contains all the goodies. All the constructs we will be creating for our project will be placed inside here, as outlined next:
  • chapter-1-introduction-to-iac-and-aws-cdk-stack.ts is one such construct or component. In this chapter, we will be spending most of our time here.
• You can safely ignore package-lock.json for now; it’s what npm uses to keep track of specific versions of node libraries installed.
• package.json is the npm module’s manifest information such as app, versions, dependencies, and so on.
• test is pretty self-explanatory. Our test files reside here, as detailed next:
  • chapter-1-introduction-to-iac-and-aws-cdk.test.ts: cdk has gone ahead and created a test file for us, urging us to test our application. We will do so in later chapters. For now, ignore it.
• tsconfig.json is where TypeScript-specific configuration is stored.

Now that we’ve learned about the files cdk has created, let’s dive in and kick off our first AWS CDK app!

In this step, we will keep things as simple as we can. The aim is to get you going with coding your first CDK app as quickly as you can. So, let’s get started.

Open lib/chapter-1-introduction-to-iac-and-aws-cdk-stack.ts in your favorite editor. We’re using Visual Studio Code. You will see the following code already present in the file. CDK has pretty much wired up everything for us and is ready to go:

import  * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
// import * as sqs from 'aws-cdk-lib/aws-sqs';
export class Chapter1IntroductionToIacAndAwsCdkStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    // The code that defines your stack goes here
    // example resource
    // const queue = new sqs.Queue(this, 'Chapter1IntroductionToIacAndAwsCdkQueue', {
    //   visibilityTimeout: cdk.Duration.seconds(300)
    // });
  }
}

We could get rid of all the comments and start adding our code, but for the sake of simplicity, let’s delete all that and paste the following code instead into the file:

import { Stack, StackProps } from 'aws-cdk-lib';
import { ContainerImage } from 'aws-cdk-lib/aws-ecs';
import { ApplicationLoadBalancedFargateService } from 'aws-cdk-lib/aws-ecs-patterns';
import { Construct } from 'constructs';
export class Chapter1IntroductionToIacAndAwsCdkStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    new ApplicationLoadBalancedFargateService(this, 'MyWebServer', {
      taskImageOptions: {
        image: ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
      },
      publicLoadBalancer: true
    });
  }
}

Alright—save the file, open up the command line, cd into the working directory (the root of our cdk application), and run the following:

$ cdk bootstrap --profile cdk

This command will bootstrap the AWS environment, meaning it will create all the necessary AWS resources on the cloud to make CDK work properly.

Then, run the following command:

$ cdk deploy --profile cdk

If you’ve followed the instructions correctly so far, you will see a nice green-text screen. Let’s examine it:

Figure 1.8 – Deploying our first CDK stack

The preceding screen is first warning you that potentially sensitive changes are about to occur with this deployment; this is due to the IAM roles the stack creates. It’s fine for you to ignore this for now.

Next, it lists the names of AWS resources that are about to be created, categorized by service. The + sign and the green color of the text indicate that these resources are about to be added. Later, we will see resources that will be marked for destruction, which is logically indicated by a – sign at the beginning of the line and the color red.

Yes—you’ve earned it: go ahead and type y and press Enter.

Note

If you’re in the middle of a stack being created and are about to take a break or attend to another matter, destroy the stack with cdk destroy --profile cdk to avoid unnecessary costs.

CDK will create an AWS CloudFormation template (we will cover this later in the chapter) and continue to deploy the stack. It will also keep you informed of the progress. If your user has got the necessary permissions, CDK will succeed in deploying the stack; else, it will fail and automatically roll back the changes.

The process is complete; we see a bunch of information being outputted. Under the Outputs section, you will see two links:

Figure 1.9 – CloudFormation stack output links

Copy either of the links into your web browser and navigate to it. You should see a page load up:

Figure 1.10 – The output of the Elastic Container Service (ECS) server

Nice! You’ve successfully deployed your first CDK application. If you now go back to your AWS dashboard and go to ECS Service, you will see a new cluster of services has been spun up on your behalf.

If you click on the cluster name, which should be Chapter1IntroductionToIacAndAwsCdkStack-{some other random text}, then you will be able to see the service, tasks, metrics, logs, and all the rest. This is a containerized ECS Fargate application with a lot of built-in resiliency already spun up by you already. So many other good things are about to come.

Right—we’ve had our fun. Let’s now go ahead and destroy the stack before we do anything else. To destroy the stack—you guessed it—run the following:

$ cdk destroy --profile cdk

Confirm by entering y. AWS CDK will now go ahead and destroy our favorite PHP stack. Perhaps it’s for the best.

Going back to the dashboard and to the ECS Service root page, you will see that the cluster is no longer there. Neither is our simple PHP app. All gone. Clean.

We hope that was fun. In the previous section, we mentioned AWS CloudFormation and how CDK outputs a CloudFormation template and then manages its life cycle.

According to AWS, CloudFormation is an IaC service (again, I’d argue with the code bit) that you can use to model, provision, and manage AWS services. In short, it’s a YAML or JSON file with an AWS service definition of its properties and relationships.

Learning CloudFormation is outside the scope of this book, but it’s useful for you to understand and read about it, to better debug your CDK applications. Let’s take a brief look at a CloudFormation excerpt sample YAML configuration.

Here is how you set up a basic EC2 instance and open up the 22 port for SSH access. Reading YAML is straightforward, and if you look closely, you will be able to read the various components our CloudFormation configuration defines:

Parameters:
  KeyName:
    Description: The EC2 Key Pair to allow SSH access to the instance
    Type: 'AWS::EC2::KeyPair::KeyName'
Resources:
  Ec2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      SecurityGroups:
        - !Ref InstanceSecurityGroup
        - MyExistingSecurityGroup
      KeyName: !Ref KeyName
      ImageId: ami-7a11e213
  InstanceSecurityGroup:
    Type: 'AWS::EC2::SecurityGroup'
    Properties:
      GroupDescription: Enable SSH access via port 22
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 22
          ToPort: 22
          CidrIp: 0.0.0.0/0

Well, CDK uses the same underlying mechanism. Working with AWS CloudFormation directly can be very daunting and complicated, even for relatively simple stacks. To prove this point, go to this chapter’s CDK app root and run the following command:

$ cdk synth

You guessed it right—this gigantic abomination of a YAML output is the result of about 20 lines of CDK TypeScript code. CDK essentially compiles your code into a CloudFormation stack and manages the rest of the complexity of adding and removing various bits, linking resources together, and a ton of other things for you.

The amount of time that developers save is undeniably massive. The amount of confusion, mistakes, and painful trials and errors of CloudFormation or any other configuration-defined IaC tool that CDK eliminates makes CDK and the new set of similar tools such as Pulumi clear winners of the IaC race. Businesses that onboard CDK into their development practices will be able to deliver a lot more in a shorter amount of time.

Developers with CDK skills will be highly sought after. Welcome aboard—this is the future of software development on the cloud!

In this chapter, we took a brief look at problems and issues with the current IaC tools and methods. We introduced CDK, got a taste of what it is capable of, and understood some of the inner workings of CDK, as well as how potentially revolutionary it is.

In the next chapter, we will dive deeper into setting up our workspace, directory structures, and environment correctly. We will also explain the concept of constructs and stacks and get to know other important aspects of CDK.