1  AWS CDK Introduction and installation

1.1 What is AWS CDK

The AWS Cloud Development Kit (AWS CDK) is a framework, a set of libraries, and a command-line tool to develop, provide, and manage AWS Cloud infrastructure solutions. The CDK team build it on top of the AWS service CloudFormation.

AWS CloudFormation is a mature and capable tool to define, provide, and manage AWS cloud infrastructure. Yet, it has been cumbersome to use, in particular for larger and more complex infrastructure solutions. The tools to support using CloudFormation have also been a bit lacking.

What AWS CloudFormation has done right is to provide a declarative way to describe the desired state of your infrastructure. You tell CloudFormation what you want, and it tries to make that happen. You do not need to specify the details of what resources to create, update, or delete - CloudFormation will figure that out.

A good thing here is that you can just describe exactly what you want. It is reasonably clear what settings are in place for each resource. A bad thing here is that you must describe exactly what you want. There can be too much detail and it becomes hard to grasp, anyway. Here is a small example of a CloudFormation definition (YAML format) of an instance of an EC2 virtual machine, configured to use the latest Amazon Linux, and run on a machine of type and size t3.micro. Do not worry if you do not understand all of it, it is simply for comparison purposes.

Resources:
  myEc2:
    Type: AWS::EC2::Instance
    Properties:
      AvailabilityZone: eu-west-1a
      ImageId:
        Ref: SSMImageParameter 
      InstanceType: t3.micro
      SecurityGroupIds:
      - Fn::GetAtt:
        - mySecurityGroup
        - GroupId
      SubnetId: subnet-12345678
      Tags:
      - Key: Name
        Value: my-stack/my-ec2

  mySecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: my-stack/my-ec2/InstanceSecurityGroup
      SecurityGroupEgress:
      - CidrIp: 0.0.0.0/0
        Description: Allow all outbound traffic by default
        IpProtocol: "-1"
      Tags:
      - Key: Name
        Value: my-stack/my-ec2
      VpcId: vpc-12345678
      
Parameters:
  SSMImageParameter:
    Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
    Default: "/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2"

The AWS CDK tries to provide the expressive power of programming languages to make it possible to describe the cloud infrastructure at a level that is easier to grasp, even if it becomes more complex. Under the hood, it will still generate the CloudFormation descriptions, but make it possible to hide much of the complexity. To illustrate this, below is a code snippet written in Python, that defines the same thing as the CloudFormation definition above. In fact, it is essentially the CloudFormation generated by this code, except the CloudFormation is a bit stripped down and with a bit nicer names.

vpc = ec2.Vpc.from_lookup(stack, 'my-vpc', is_default=True)
ec2.Instance(
    stack,
    'my-ec2',
    vpc=vpc,
    instance_type=ec2.InstanceType.of(ec2.InstanceClass.T3,
                                      ec2.InstanceSize.MICRO),
    machine_image=ec2.MachineImage.latest_amazon_linux2023()
)

There are simply less details that you have to bother with - you can if you want, but the general idea is that the AWS CDK should provide sane defaults. In this case, you can focus on your intention (latest Amazon Linux, using default VPC), and do not need to sort out all low level details.

Just as with any program you write, it is possible to write code for AWS CDK that is difficult to understand and maintain, as well as code that code for infrastructure that is straightforward to maintain and understand. You have that power. You choose what you will do with it. After this book, you should be well equipped to handle that power.

There are a few key concepts to keep in mind when using the AWS CDK:

  • An App. This the top level container, which contains everything that you can provision in the solution or project you are working with.
  • A Stack. This is a collection of AWS resources that you provision and manage as a unit. It could be your whole solution, or it could be part of a solution.
  • A Construct. This is a logical grouping of one or more AWS resources and may also encapsulate certain logic, practices and conventions.
  • A Resource. A unit of infrastructure in AWS, which is available via CloudFormation and AWS APIs primarily.
  • An Environment. A specific combination of an AWS account and an AWS region.
  • Synthesize. The process of executing CDK-based code to generate the corresponding CloudFormation representation.
  • Deploy. The process of taking the underlying CloudFormation representation that has been generated in the synthesize step to actually provision (create, update or delete) AWS resources.
  • Bootstrap. The process of preparing an environment for deployment with AWS CDK. This is typically a one-time process for each environment.

A CDK App will consist of a number of stacks, which in turn consists of one or more constructs. Each construct may encapsulate one or more resources.

CDK concepts

It is also helpful to know a few CloudFormation concepts:

  • A template. This a textual description of a collection of resources to manage as a unit, in either JSON or YAML format.
  • A Stack. This is representation of the provisioned set of resources described by a CloudFormation template, and managed by CloudFormation itself.
  • A Change Set. This is a representation of potential change of resources that CloudFormation will perform, to reach a desired target state from an existing state.

A CloudFormation template has a 1-to-1 mapping to a CloudFormation stack. These have a 1-to-1 mapping to a CDK Stack.

The process to provision from a set of CDK-based code to actual resources consists of

  1. Compile the code (if using a compiled programming language)
  2. Run the compiled result (Synthesize process), which builds the resource structures, and generates CloudFormation template(s)
  3. Create a CloudFormation change set (Deploy process), with potential approval step
  4. Provision changes defined in the change set (Deploy process)

Prior to running this provisioning cycle, you need to bootstrap each target environment. This essentially sets up a few resources that AWS CDK needs for deployment, and is a one-time process per environment.

CDK processes

The AWS CDK command-line tool is the primary tool to perform these process steps:

  • cdk synth
  • cdk deploy
  • cdk bootstrap

We will expand on the usage of these commands in later sections.

1.2 Installation

Before building something with the AWS CDK, and pick a language to use, we need to install the AWS CDK command-line tool. The tool itself is written in TypeScript, and uses the Node.js runtime. If you already have Node.js installed on your computer, then that is great! You can proceed to the actual CDK installation below. If you do not have Node.js you will need to install its runtime. You can download the Node.js runtime from the Node.js website. The long-term support (LTS) release is the recommended version to use. However, newer versions and some older versions are ok to use as well. You can also install Node.js via different package managers, depending on the computer environment you are working with. See the the Node.js package manager page for suggestions. You can also download tools there etc manage multiple separate versions of Node.js, should you ned that.

Once you have installed Node.js, it is time to install the AWS CDK command-line tool. For Python, or any language that is not TypeScript/JavaScript, you want to do a global install of the command-line tool (not a project-local install), since you would likely not use Node.js in the project itself.

To install the AWS CDK command-line tool globally, run the following command in a shell:

npm install -g aws-cdk

The command npm is the Node.js package manager, which installs the package aws-cdk. It will installed the latest version of AWS CDK, which is 2.171.1 at the time of this writing.

When you have installed the aws-cdk package, you will have the command cdk available through the command-line. You can check that it is working by running cdk version:

❯ cdk version
2.171.1 (build a95560c)

If you have this working, next step is to set up our basic Python tooling. In this book, we are going to use the tool uv to manage our projects. There are a few options to install uv, which can be found here. If you pick the direct installer, uv will be able to update itself. If you instyall via a package manager, you use the functionality of that package manager to update uv later.

If you already have Python installed, then that is great! Otherwise uv will set up a suitable Python version for you when we initialize the project later.

You are now all set to take the next step and set up a project in Python!

Let us get started with our infrastructure in the next chapter!

1.2.1 A note about AWS credentials

In all the following chapters, you will interact with an AWS environment. It is up to you to supply this environment.

All examples of running commands with the AWS CDK command-line tool assumes that your default/current AWS credentials are the ones you will be using. There are a few ways to set up your credentials that way:

  1. If you have an AWS credentials profile that is the default profile. You are good to go, nothing else to do.
  2. You have explicit and permanent AWS access key id and secret access key values. Set the AWS environment variables AWS_ACCESSS_KEY_ID, and AWS_SECRET_ACCESS_KEY with these values, in your command-line session.
  3. You have explicit and temporary AWS access key id and secret access key values. Set the AWS environment variables AWS_ACCESSS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN with these values, in your command-line session.
  4. You have an AWS credential profile, which is not the default profile. Set the environment variable AWS_PROFILE to the name of that profile.

Also remember to set the AWS_DEFAULT_REGION environment variable with your AWS region of choice, unless that is set explicitly in the AWS credential profile you are using.

Note that the AWS CDK command-line tool also supports the --profile option to specify the AWS credential profile, and you are free to use that one instead.