DEV Community: M Avdi

Creating an AWS CodePipeline Stack and troubleshooting common issues

M Avdi — Wed, 01 Jul 2020 05:06:57 +0000

Creating an AWS CodePipeline Stack and troubleshooting common issues

AWS CDK is a relatively new framework that aims for faster development of AWS Cloud stacks when compared to AWS CloudFormation and AWS SAM. This article will present how to deploy a complete AWS CodePipeline using AWS CDK and troubleshoot all common issues that may occur in the process of creating the CDK application. For additional information about the framework, read the previous article named "How AWS CDK facilitates the development process of AWS Cloud Stacks".

AWS CDK setup

To create any AWS CDK application, it is necessary to have the CDK installed in the machine and updated to its latest version. To do so, the following command can be used:

npm install -g aws-cdk

After this command finishes its process, AWS CDK will be updated to its latest version. This process is important due to updates constantly being released, integrating new functionalities and solving issues from previous versions. To check out if the current CDK version installed is the updated, check the latest release on the CDK Github repository and compare with the output of the following command:

cdk --version

Quick starting an AWS CDK application

With the latest version of the AWS CDK installed, it is possible to start the CDK project that will generate the desired AWS cloud environment containing all the resources needed for a given application. The following command is necessary to start the project:

cdk init app --language=typescript

The command above starts a CDK application using the app template, in the language typescript. Issues that may happen when using this command are:

Unknown init template: it is important to notice that app does not stand for the name of the application. It stands for the template that is going to be used to quick start the application. Three templates are available: app, lib and sample-app, and each template has a list of languages supported. The current default template is app;
Unsupported language: as described in the previous item, some languages are not yet supported by all templates. The command below will specify all templates available and which languages are supported by them for the current CDK version installed.

cdk init --list

No language was selected: by the time of this article, AWS CDK does not have a standard language. One of the main goals of the framework is to let the developers decide which programming languages they want to use. Due to this, this event will fire when running the init command without specifying the language.
cdk init cannot be run in a non-empty directory: since it is only specified in this command the name of the template to be used, AWS CDK relies on the folder name to generate the name of the application, and it cannot be initialized in any folder that is not empty. To solve this issue, a new folder needs to be created, and the command should be used again inside this new folder.

AWS CDK constructs and versioning

The main goal when creating CDK applications is to easily deploy AWS Cloud resources. With that in mind, each resource that is going to be used in the application needs to be installed. Each language has its own way in how to install those packages, and documentation about it can be found in thetroubleshooting section, and each construct module name can be found in its section in the API Reference.

The same CDK application is usually used for long periods of time, as it defines the entire architecture of AWS projects. It is a common necessity to add more constructs to the stacks, as the project keeps growing, which can be achieved, using Amazon S3 as example, using the command below:

npm i @aws-cdk/aws-s3

By doing so, an issue might appear: dependencies which versions are mismatching, triggering the error Argument of type 'this' is not assignable to parameter of type 'Construct'. It happens when constructs can't interact with each other, making the parameter this passed to be marked as invalid. To prevent this issue from happening, it is necessary to update the dependencies using the command npm update every time a new construct is added to the project or a new version of the AWS CDK core is released.

It is also important to notice that the usage of some resources might require the addition of some dependencies, as the case of AWS CodePipeline, which may require features present in the aws-cdk/aws-codepipeline-actions. Being aware of those cases might be helpful to prevent issues and delays in the stack development.

Development of an AWS CodePipeline Stack with AWS CDK

AWS CodePipeline is a cloud resource that provides CI/CD services in the AWS environment. In this section, a walkthrough on how to create a CodePipeline using AWS CDK in TypeScript is going to be provided, as well as solving some of the issues that may be presented while doing so. For this example, a pipeline that will automate the deployment of a ReactJS application present in a GitHub repository, which will be hosted on a Amazon S3 bucket is going to be used.

CodePipelines consist of stages, which represent actions that are going to be performed on the artifacts used as source. The pipeline that is used as example for this article will have three stages:

Source: in this stage, the ReactJS application code will be gathered via webhook to be used as input for the pipeline;
Build: this stage will be responsible to build the artifacts coming from the previous stage in a CodeBuild instance;
Deploy: the last stage of this example pipeline, it will be responsible for deploying the S3 hosted website in the web.

Initializing the CodePipeline environment

To define a standardization of all the resources existent in the cloud environment, it is a good practice to set the resources name with a prefix indicating the stack they belong to. To do so, a property named environment is going to be set in the cdk.json file and imported in a context file with other environment variables the application may require. This is how the JSON file should look like after setting the property:

{
    "app": "npx ts-node bin/aws-cdk-example.ts",
    "context": {
        "@aws-cdk/core:enableStackNameDuplicates": "true",
        "aws-cdk:enableDiffNoFail": "true",
        "environment": "aws-cdk-example"
    }
}

Besides the property just set, the entire file stays the same as it was created using the init command. An issue that may happen when modifying this file or the project structure is the Cannot find module error, being triggered when the file set in the app property is not present in the given path, usually happening after the file has been renamed or moved to better suit the development team's pattern. To solve it, change the value of the property with the proper path to the file where the stacks are being synthesized.

To get those values, a context function is recommended, importing all the context variables used in the application. The following snippet is the function and its interface requiring the variable from the JSON file and returning it when called:

import { Construct } from '@aws-cdk/core';

interface IContext {
    environment: string
};

function getContext(app: Construct): IContext {
    return {
        environment: app.node.tryGetContext('environment')
    }
}

export default getContext;

It is important to point out that the string inside the tryGetContext call must match the key from the JSON object, which otherwise will result in an undefined value and possible error generation, depending on the usage of the variable.

Initializing the hosting bucket

This bucket is going to serve as the host in which the ReactJS application is going to be stored and served in the web. For this example, a scenario where all users will be able to access the hosted website is going to be used, using CORS rules and public read access to allow its usage. The following snippet demonstrates how to define an S3 bucket to host a ReactJS application, using the aws-s3 module from AWS CDK:

const corsRules: [CorsRule] = [{
    allowedOrigins: ['*'],
    allowedMethods: [HttpMethods.GET]
}];

const bucketName = `${environment}-bucket`
const bucket = new Bucket(this, bucketName, {
    bucketName: bucketName,
    publicReadAccess: true,
    cors: corsRules,
    websiteIndexDocument: "index.html",
    websiteErrorDocument: "index.html",
    removalPolicy: RemovalPolicy.DESTROY
});

Note that the environment present in the code represents the context variable previously set in the cdk.json file, allowing the cloud resources to have names following the same pattern. Issues that may be presented when creating such S3 buckets are:

Forbidden status when entering the website: This issue happens when not setting the publicReadAccess property to the S3 bucket, as for safety purposes, the default value for this field is set as false. To solve this issue, the publicReadAccess property must be set as true, granting read access for everyone in the web accessing the bucket URL;
Page not found: This issue, usually generated when creating websites with ReactJS and similar frameworks, is generated due to the fact the websiteErrorDocument is pointing to a nonexistent file. since ReactJS builds do not generate an error.html file to act as a redirect page when a route is not found. To solve this issue, both websiteErrorDocument and websiteIndexDocument must be set as index.html as parameters when creating the resource Construct;
Bucket name already taken: Amazon S3 buckets have one rule for their naming: they must be unique globally. This means that the bucket name created must be well chosen and very specific, preventing the error BucketAlreadyExists to be generated when deploying the CDK.

As for the removalPolicy property in the bucket creation, it is set to destroy to allow the removal of this bucket when running the cdk destroy command, overriding the default RETAIN value. This allows the deletion of the given bucket if the same is empty when the command is used, although it will still need manual clean up and removal if the bucket contains any kind of data on it.

Building the website with AWS CodeBuild

The next step after creating the bucket where the website is going to be hosted is creating the CodeBuild project that will build the website with the code coming from the GitHub repository. The first step to achieve this goal is creating the AWS IAM Role the CodeBuild project will have, granting it permissions to perform actions on other AWS cloud resources, such as the website bucket. The following code snippet shows how to create this role:

const codebuildRoleName = `${environment}-codebuild-role`;

const codebuildRole: Role = new Role(this, codebuildRoleName, {
    roleName: codebuildRoleName,
    assumedBy: new ServicePrincipal('codebuild.amazonaws.com')
});

codebuildRole.addToPolicy(new PolicyStatement({
    effect: Effect.ALLOW,
    actions: [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "s3:*"
    ],
    resources: [artifactsBucket.bucketArn]
}));

The definition of the role has one important property: assumedBy. This property is responsible to tell the AWS environment which service this role is going to work for, being here assigned to codebuild.amazonaws.com, which represents AWS CodeBuild. It is important to assure that the proper service principal name is specified, as it is going to create the Trusted Entity AWS IAM will use to give the resource the basic permissions to operate. If the value is not properly set, an error like this will be given when running the pipeline: Error calling startBuild: CodeBuild is not authorized to perform: sts:AssumeRole. To solve it, simply set the ServicePrincipal to the proper value of the desired AWS cloud resource.

As for the next code section, it is handling the policies that are granted to the previously created role. IAM policies allow AWS cloud resources to perform actions on other resources in the environment. It is a PolicyStatement that usually contains effect, actions, resources and conditions, although this CodeBuild project needs no conditions to be set, therefore, this property is not being used. It is very common to have issues in this section of CDK applications, as there is no easy method to define which properties a resource will need to have to run. With time and experience, architecting AWS projects will facilitate the definition of what permissions each resource will require, reducing the time spent on trial and error methods to create resources.

To solve policy issues, tailing the logs when the stack is being created and when the resource runs is the best method, as the console will specify which permission is missing in the policy set and which resource it needs to be accessed.

The next step on creating a CodeBuild resource is to create the resource itself, using the aws-codebuild module from AWS CDK. The following snippet demonstrates how to declare the CodeBuild construct:

const codebuildProjectName = `${environment}-codebuild`;

const codebuildProject = new PipelineProject(this, codebuildProjectName, {
    environment: {
        buildImage: LinuxBuildImage.STANDARD_2_0,
        computeType: ComputeType.SMALL
    },
    role: codebuildRole,
    projectName: codebuildProjectName
});

The CodeBuild method used to instantiate this resource is by using the PipelineProject construct, which facilitates the usage of the resource when it is used inside a CodePipeline project, as used in this example. This construct is composed of a large number of properties, but just some of those are needed to be set, and for this project environment, role and projectName are used. The environment property sets the specifications of the CodeBuild instance used to build the given project, and it needs to support in its environment the language that is used in the project that is going to be built. This CodeBuild reference tells about all images and its specificities, which will prevent CodeBuild to generate an error informing that the runtime version is not supported by the selected build image.

Another property, not used in this project due to the fact its default value is correct, is the buildSpec. The buildspec file contains the information that is going to be used by the resource to build the source code, with step-by-step instructions to CodeBuild on how the compilation should proceed. The lack of a file named buildspec.yml in the root of the project to be built, or the custom if a value is set to the property, will result in an error labeled as YAML_FILE_ERROR Message: YAML file does not exist. To solve it, this file must be created, containing the steps to build the application, following the pattern present in the aws docs.

Creating the AWS CodePipeline

The CodePipeline is where everything that has been created until now comes together. As CodeBuild also required, the pipeline will also need to have its own IAM Role to have the necessary permissions to operate successfully, and its definition, which will use the Pipeline construct from the aws-codepipeline module present on AWS CDK. The definition of the pipeline will follow the pattern as the snippet below:

const codepipelineName = `${environment}-pipeline`;
const codepipeline: Pipeline = new Pipeline(this, codepipelineName, {
    artifactBucket: artifactsBucket,
    pipelineName: codepipelineName,
    role: pipelineRole,
});

const outputSource = new Artifact();
const outputBuild = new Artifact();

That short snippet is necessary to declare the pipeline. The only parameter that wasn't stated yet in this article is the artifactBucket, which needs to receive a S3 bucket that is going to be used to store the artifacts that are going to be passed from stage to stage. It is an optional parameter, that was set with the goal to standardize the bucket names, when not setting it would result in the creation of a bucket with a default name. Also, the Artifact items created are going to serve as the artifacts holding the files that are going to be passed on the pipeline from a stage to another.

After everything is set up, all that is left to do is declare the stages themselves to the pipeline, where all the action will happen. As previously stated, three stages are going to be created: Source, Build and Deploy, and the following sections will state how to create those stages, using the aws-codepipeline-actions module from AWS CDK.

Adding stages: Source

This stage is responsible for gathering the code from the GitHub repository that is going to be used as source for the build using CodeBuild. This stage can be added using the snippet below:

const { repo, owner, oauthToken } = github;
codepipeline.addStage({
    stageName: 'Source',
    actions: [
        new GitHubSourceAction({
            actionName: 'Source',
            oauthToken: new SecretValue(oauthToken),
            output: outputSource,
            owner,
            repo,
        })
    ]
});

The github object will be set in the cdk.json file, and is selected the same way as the environment was previously done. It is important to note that the object containing this information should be identical as the object defined in the context.ts interface, allowing tryGetContext to get its value without issues. If the pattern is not followed, an error will be triggered as one or more properties will have their values as undefined due to the fact the values will not be present in the JSON file.

Basically, each stage will contain a stageName and the actions to be performed. In this case, its name is going to be defined as Source and it will perform a GitHubSourceAction, which will collect the code in the GitHub repository specified in its parameters. Some issues may be generated when creating this stage:

Authentication fails with GitHub oauthToken: GitHub provides to developers a token that needs to be passed to the pipeline to grant access to GitHub repositories. To solve this issue, an oauthToken must be generated in the repository owner's profile containing the following permissions: admin:repo_hook and repo. This generated token needs to be passed to the pipeline as a new SecretValue, which represents a secure way to store the Secret value created in the AWS SecretsManager, in the oathToken property;
Invalid repository/owner: This issue usually happens when the repository name and/or the owner are mistyped in the context file, therefore generating a incorrect link that CodePipeline can't find, or if the provided oathToken does not have the necessary permissions to visualize the repository. This issue is labeled on CodePipeline as Either the GitHub repository "repo-name" does not exist, or the GitHub access token provided has insufficient permissions to access the repository.

Adding stages: Build

This stage is responsible for using the previously defined AWS CodeBuild resource to build the code coming from the previous stage. To define this stage, the example snippet below can be used:

codepipeline.addStage({
    stageName: 'Build',
    actions: [
        new CodeBuildAction({
            actionName: 'Build',
            project: codebuildProject,
            outputs: [outputBuild],
            input: outputSource
        })
    ]
});

This stage is far simpler than the Source stage, as the CodeBuild resource was already created in this application. It is going to use the outputSource artifact, which contains the source code coming from the repository, as shown in the Source stage snippet, to create the build of the application. In this stage, all the CodeBuild issues will appear, as this is when the resource is being put to use, so to debug those possible issues, it is needed to open the CodeBuild project in the AWS Console and check the logs of the building operation. This building process, if successful, will then generate the compiled application that will be sent to the outputBuild artifact to be used in the next stage.

Adding stages: Deploy

This stage is responsible for delivering the website via Amazon S3, using the bucket previously created to do so. It will require the usage of the S3DeployAction from the pipeline actions module, as shown in the snippet below:

codepipeline.addStage({
    stageName: 'Deploy',
    actions: [
        new S3DeployAction({
            actionName: 'Deploy',
            bucket: bucket,
            input: outputBuild
        })
    ]
});

This last stage will require just a few parameters, being the only one not described yet, the bucket, which refers to the bucket the application is going to be deployed, to serve hosting the built website. Most of the common issues that may happen in this stage are being covered in the definition of the bucket, so at this point the pipeline should work just fine.

Instantiating the artifactsBucket and the CodePipeline

Now, working in a direct class that extends a CDK Stack, the pipeline and its artifacts bucket are going to be created, as the last step before deploying the pipeline. The following code snippet represents this creation:

const artifactsBucketName = `${environment}-artifacts-bucket`;

const artifactsBucket: Bucket = new Bucket(this, artifactsBucketName, {
    removalPolicy: RemovalPolicy.DESTROY,
    bucketName: artifactsBucketName
});

new CDKExamplePipeline(this, `${environment}-stack`, {
    artifactsBucket
});

This is a quite simple step, considering a S3 bucket has already been created, and the artifactsBucket is a much less complex resource, as it does not need to host a website. As previously mentioned, the usage of this bucket described in this snippet is optional, since the CodePipeline already creates a bucket by default, but be mindful that this default bucket will most certainly not follow the patterns used in the stack. As for the pipeline itself, the bucket is being passed as a parameter, taking in consideration that the CodePipeline class just created has an interface like the snippet below:

interface ICDKExamplePipelineProps {
    artifactsBucket: Bucket
}

This interface is used as the type of the props value in the constructor of the class, allowing the developers to create custom interfaces, passing all the parameters that they may want to.

Post-development issues

The development of the application might be the trickiest part, but issues might happen even after the code is completely right. Issues that happen following the development of the application may include:

Bootstrap required: When the issue Template too large to deploy ("cdk bootstrap" is required) appears, it means your CDK application generated a CloudFormation template larger than the maximum accepted, which is 50 KiB. This issue is quite simple to solve, since all that is needed to do is run the bootstrap command given in the terminal, containing the bucket ARN in which the CDK application is going to be uploaded and imported in AWS CloudFormation once the deploy command is used again;
Exceeding resource limit: Since AWS CDK applications are converted to CloudFormation templates, they have the same limitations. One of those limitations is the hard cap on the resource quantity present in a single stack: 200. While this may seem a lot, CDK constructs usually generate more than one resource in the stack to get created. To solve this problem, separating the application in multiple stacks is the recommended option, allowing the developers to organize the cloud environment in multiple parts that are connected when deployed;
Resources not being deleted after cdk destroy: The cdk destroy command has the objective of deleting a given stack and all of its resources. Although, AWS blocks the removal of some resources that may contain data, such as Amazon DynamoDB and Amazon S3, leaving the given resource in the cloud environment even after the entire stack has been destroyed. Specifying RemovalPolicy.DESTROY in the Construct definition will allow CDK to destroy all empty resources created. For resources that are not empty, running cdk destroy will generate an exception for the non-empty resources, and those resources will then have to be cleared and deleted manually via AWS console.

Conclusion
This article pointed out the most common issues that may happen while developing cloud environments using AWS CDK and how to easily fix them, is a complimentary article for “How AWS CDK facilitates the development process of AWS Cloud Stacks”, which introduces the tool and gives an overview in how it can be utilized. As the framework evolves, those issues will be addressed by AWS and the community, improving the facilitating tool and the lives of every AWS developer.

Mark Avdi

CTO | WestPoint.io | Lover of all things Serverless

How AWS CDK facilitates the development process of AWS Cloud Stacks

M Avdi — Sun, 28 Jun 2020 17:03:21 +0000

Working with AWS can be quite a complex task at times, due to the fact that well composed architectures and solid infrastructures might be troublesome to deploy and maintain in the long run. A main software development goal is to always optimize the development flow by making processes as simple as possible, from the programming language to each and every framework to be used in the project. In AWS it is no different. Even though CloudFormation was already a hugely beneficial tool, the launch of SAM helped even more developers across the world to architect their infrastructures with a smooth efficiency, reducing the time to plan infrastructures and increase productive development time.

Last year, AWS took Cloudformation one step further and released CDK (Cloud Development Kit). AWS CDK is one of the most recent releases from Amazon AWS to improve the capability of creating and keeping control of infrastructures with your preferred programming language. Although this technology is quite recent, and may present issues while compared to SAM or even raw CloudFormation, it is undeniable that it eases the whole process of creating and setting up AWS resources. This article will present the advantages as well as some issues you might encounter while using this tool.

Defining AWS CDK

In a nutshell, the AWS Cloud Development Kit is an open-source framework that aims to make an easier and faster way to create AWS Cloud resources that will be transformed into AWS CloudFormation templates. With CDK, the cloud infrastructure development can use all the perks provided by the desired programming languages, such as TypeScript, JavaScript, Python, Java and C#. This can drastically reduce the time spent on architecture, along with solid API reference and a very useful CLI that allows the interaction with CDK applications.

CDK integrations and known issues

One of the benefits that makes using AWS CDK so tempting is that although the tool itself has some complexities, an integration with a SAM project can be easily achieved. But, due to being a new framework, some of the cloud components are not very stable yet, which can be the case for APIs with Lambda functions because it can negatively affect the infrastructure scalability. In those cases, SAM templates, which are rock stable by now, can do just the trick, and those can be homogeneously incorporated into CDK applications.

Another common issue is that as the framework is relatively new, updates are constantly being made on the packages, which may result in compatibility issues when installing CDK modules.

The ability to overcome issues like those above described, as well as the fact that there are AWS resources that currently lack Constructs, such as Pinpoint and Athena, makes this framework a solid option for development teams facilitating the development of solid cloud architectures. As the tool is improved, it is expected that those issues will be solved, allowing an even faster and consistent development process.

Small learning curve

Besides the programming language that is going to be used to create the cloud resources, which most of the time is already background knowledge, there are a few factors that make the learning curve relatively small. Not having to know all the basics and background information of each construct may be one of the biggest factors. When instantiating a resource, its basic roles and sets are already predefined, allowing the developer to focus only on elements they may need to customize. This allows developers that are starting in the cloud environment to acquire knowledge about the resources while still being productive and delivering projects. There may be times where the basics won’t be enough, but by the time the development process is complete, all the time previously saved by using the framework will be available to research in how to architect solutions for those problems.

Faster development process

The development process is a balance of using the frameworks that will make the development process faster while maintaining its quality. Spending time creating enormous CloudFormation templates can be quite hard and time consuming, but it offers solid results and the cloud stacks created with it are solid. When SAM was launched, it made the developer’s life much easier, as its templates are quite smaller, while not losing its capabilities as it is transformed into CloudFormation templates.

The same can be said for CDK: it brings the comfort of defining components programmatically while still having a compilation that allows the stack to have all the perks provided by CloudFormation, such as rollback in case of failures, safe deployment and drift detection.

The usage of CDK constructs allows an acceleration of the development process, as the constructs come with predefined configurations for each AWS cloud resource they create, including its basic roles and properties.

As an example of how the creation of cloud resources using CDK can speed up the development of cloud architectures, a definition of a bucket that allows get requests from specific domains is going to be demonstrated in both an AWS CloudFormation template and a AWS CDK application. This policy in a CloudFormation template should look like this:

"westpointBucket": {
  "Type": "AWS::S3::Bucket",
  "Properties": {
    "BucketName": "westpoint-bucket",
    "CorsConfiguration": {
      "CorsRules": [
        {
          "AllowedMethods": [
            "GET"
          ],
          "AllowedOrigins": [
            "http://westpoint.io/*"
          ]
        }
      ]
    },
    "WebsiteConfiguration": {
      "ErrorDocument": "index.html",
      "IndexDocument": "index.html"
    }
  },
  "UpdateReplacePolicy": "Delete",
  "DeletionPolicy": "Delete"
},
"westpointBucketPolicy": {
  "Type": "AWS::S3::BucketPolicy",
  "Properties": {
    "Bucket": {
      "Ref": "westpointBucket"
    },
    "PolicyDocument": {
      "Statement": [
        {
          "Action": "s3:GetObject",
          "Effect": "Allow",
          "Principal": "*",
          "Resource": {
            "Fn::Join": [
              "",
              [
                {
                  "Fn::GetAtt": [
                    "westpointBucket",
                    "Arn"
                  ]
                },
                "/*"
              ]
            ]
          }
        }
      ],
      "Version": "2012-10-17"
    }
  }
}

import * as cdk from '@aws-cdk/core';
import * as s3 from '@aws-cdk/aws-s3';const cors_rule: [s3.CorsRule] = [{
    allowedOrigins: ['http://westpoint.io/*'],
    allowedMethods: [s3.HttpMethods.GET]
}];

const westpointBucket = new s3.Bucket(this, 'westpoint-bucket', {
    bucketName: 'westpoint-bucket',
    cors: cors_rule,
    publicReadAccess: true,
    websiteIndexDocument: "index.html",
    websiteErrorDocument: "index.html",
    removalPolicy: cdk.RemovalPolicy.DESTROY
});

As demonstrated above, defining this kind of resource on CDK applications is much faster and more compact compared to the same definition in CloudFormation. Although some issues may exist, as pointed out before, it is undeniable that this tool improves the productivity of the development teams, allowing them to focus more on what is important: the product itself.

Constructs: the base for each application

Constructs are the pieces that will come together when creating applications with AWS CDK. They are the representation of cloud components, such as a simple S3 bucket, or a DynamoDB table, as well as composite components, such as an AWS CodePipeline, which will be composed of multiple resources to accomplish its purpose.

Defining resources using constructs in a CDK application is a quite simple task compared to what needs to be done on a CloudFormation template.

import * as dynamodb from '@aws-cdk/aws-dynamodb';

const westpointTable = new dynamodb.Table(
    this, 
    'westpoint-table', { 
        partitionKey: {
            name: 'id', 
            type: dynamodb.AttributeType.STRING
        }, 
        tableName: 'WestpointTable'
});

The code snippet above represents the definition of an Amazon DynamoDB table using TypeScript. Each AWS resource has its own dependency, allowing the developers to import only what is needed for the application, reducing the size of the application by not importing packages that are not going to be used. As of the table itself, it accepts three attributes: scope, id and props.

Scope: defines which construct the new construct is present within. When creating CDK stacks, each construct should be inside another construct, creating a hierarchy of constructs starting from Stacks all the way to smaller resources, such as a DynamoDB table. In almost every case, this is going to be passed as the parameter.
Id: defines the id of the construct, which must be unique within the scope. It is important to notice that the id does not represent the resource name, its purpose is to separate each cloud resource within the scope.
Props: an object that defines all the parameters that are going to be passed to customize the cloud resource. They are divided in two types: required and optional. Required props are the sets of parameters that the developers must set to create the desired cloud resource, while the optional props are non-mandatory parameters that can be passed to better suit the projects needs, usually overwriting predefined settings.

For the previously defined DynamoDB table, which the id ‘westpoint-table’ was set, the set of properties passed to it were the partition key, which is a required parameter to the creation of the resource, and the table name, which optionally nominates the table that is going to be created in the AWS infrastructure. Not defining the table name would result in the creation of the resource with the default table name, which is a concatenation of all the constructs present within the current stack.

CDK constructs are divided in three types: those being low-level constructs, higher-level constructs, and patterns. They represent multiple complexities of constructs that can be used in the cloud stack definition.

Low-level constructs represent the smaller constructs, also called Cfn resources. They are all the resources that are available on CloudFormation templates, and require explicit declaration of all its properties, without any kind of basic resource creation. For its usage, deep knowledge about the AWS service is required, as the developer needs to specify all the models of the resource.

Higher-level components also represent AWS services, but as an API that handles most of the configurations. They allow the development of cloud resources without deep knowledge about the resources themselves, as it bootstraps an instance of the service, and only requires basic user configuration to suit their needs.

The last type, patterns, represent constructs that allow the simple creation of common tasks that otherwise would require some effort to be put together. They often consist of multiple AWS resources, such as the LambdaRestApi construct, which consists of a simple API Gateway resource that is backed up by a Lambda function.

AWS CDK CLI

Along with what was previously mentioned, AWS CDK has a CLI that is the main tool to interact with CDK applications. It is responsible for commands such as verifying the defined stacks, generating the CloudFormation templates and deploying your application to the AWS infrastructure.

These perks allow the developers to validate their stacks much faster than it would be to deploy CloudFormation stacks to the cloud, in which case you would have to wait for the entire process to finish to then realize there was some kind of issue in the templates. As some commands are vital for the usage of CDK, they are going to be presented here to show an overview of what the CLI is capable of.

cdk init

The basic command to quick start CDK projects. It generates a folder with the necessary files and dependencies to create a CDK application. It comes with options to select the language, list available templates to start your stack and possibility to auto setup a git repository for it.

cdk synthesize
cdk synth

This command is responsible for generating the CloudFormation stack that will be created when deploying your CDK application. It can be used to verify if the current template definition in your code represents a valid AWS CloudFormation template, reducing the time needed to discover issues. It comes with an option to synthesize only the requested stacks, leaving behind all their dependencies.

cdk deploy

This is the most important command present in the CLI. It allows the deployment of your application into the AWS cloud environment. Running this command will result in the creation of the CloudFormation templates for the defined stacks present in the code, and then uploading those templates in the cloud. It comes with multiple options, such as passing parameters to the stack, selecting the output file path, tags that may be added to the stack, and more.

cdk bootstrap

There might be situations where the template created by the deploy command can’t be directly uploaded to the cloud due to its size. When this happens, the bootstrap of your application is required. It consists of uploading the generated templates into AWS buckets for them to be deployed again using the previous command. This command comes with many options, such as selecting the bucket the templates will be uploaded to, selecting the AWS KMS master key for encryption, as well as adding tags to the stack, and more.

cdk destroy

This command is used to remove deployed CDK stacks. It removes from the cloud all the resources created by your CDK application, besides some special cases. One of those cases is S3 buckets: the destroy command will never delete a bucket that is not empty, which most of the time it will not be, requiring manual deletion after the destroy process is finished. It comes with options to not destroy dependencies and force exclusions, not requiring confirmations afterwards.

As we can see, the AWS CDK CLI is one of the biggest friends of the developer when defining cloud resource stacks, having its multiple perks that facilitate the process of creating and deploying AWS infrastructures.

Conclusion

As described in this article, AWS CDK and its CLI facilitate the development of AWS infrastructures, as it allows developers to use programming languages rather than using notation languages such as YAML or JSON. The creation and deployment of each and every stack is a lot easier when making usage of elements such as the synthesize command to validate stacks. Following this article I will write a complimentary article tackling the most common issues of using CDK and how to solve them, allowing a quick understanding of some of the issues that may occur and allowing an even easier and faster development. I hope you found this article useful.

Mark Avdi

CTO | WestPoint.io | Lover of all things Serverless