There are several ways that infrastructure can be deployed to AWS, from creating things by hand in the AWS console to using the AWS SDK for your programming language of choice AWS provides multiple options for creating resources. One great option that is a hybrid of IaC and programming is AWS CDK. CDK is an IaC tool that allows users to create and manage infrastructure stacks easily and to define resources using their preferred programming language. We discussed CDK in depth in a previous post. If you’d like to know more about CDK, you should check out the About AWS CDK post: https://blog.cleanslatetg.cloud/about-aws-cdk/. For this example, we will create our Jekyll static site in AWS using CDK with Python.

Tech Stack

Source Control

• GitHub
  • Users will need to create and host a repo on GitHub
  • The provided example code is hosted on GitHub
    • https://github.com/cleanslate-technology-group/indyaws-cdk-python-jekyll-blog
  • GitHub was chosen for this project for several reasons. Users can create free accounts and private repos, a large community of users already using GitHub, and GitHub integrations work well with AWS CodePipeline.
  • This application can be hosted using another source control service but be aware that if you choose to use a different source control, you may need to modify the CDK code to use an external CI/CD system other than CodePipeline.

Blog Infrastructure

• Route 53
  • Route 53 is where you will purchase and host the domain for your blog
  • The domain will need to be purchased and available before running CDK
• Amazon Certificate Manager (ACM)
  • AWS provides free SSL certificates that, if integrated with AWS Route 53, can be automatically renewed without any intervention by the user
  • ACM will be used to create the necessary SSL certs that will be used for HTTPS traffic to the static site CloudFront distribution.
• S3
  • Two S3 buckets will be required to host the static site and static media. This could be one single bucket; however, splitting out the media files from the static site makes it a little easier to perform CloudFront invalidations, and some Jekyll templates expect media files to be separate from the site content.
  • Static Site files
    • Public bucket configured as a static website
  • Media Files
    • A private bucket that uses a CloudFront OAI for access
• CloudFront
  • Distribution for the static site
    • Hosts the static Jekyll files
    • Uses the Route 53 domains and ACM certs to handle web traffic
  • Distribution for the media files
    • Hosts files with the CloudFront URL

CI/CD

• CodeStar Connection (GitHub)
  • A connection that allows for AWS CodePipeline to connect to the user’s GitHub repo. This connection allows CodePipeline to deploy on check-in to a specified branch.
• CodeBuild
  • CodeBuild is a build system that allows for the Jekyll site files to be created and to perform the invalidation of a CloudFront distribution. The Jeykll static site files are passed to different stages in CodePipeline as artifacts.
• CodePipeline
  • A CI/CD Pipeline is used to orchestrate the generation of static blog files, deployment of files to S3 and invalidation of CloudFront resources.

Creating your Blog

Prerequisites

• Create an AWS account to host the blog
• Purchase a domain using Route 53 for the Blog URL
• Install the AWS CLI
• Create an AWS CLI profile
• Install AWS CDK
• Install Python 3

Steps

1. Create a private GitHub repository for your blog
2. Clone the repo https://github.com/cleanslate-technology-group/indyaws-cdk-python-jekyll-blog into your repo
3. Find a Jekyll theme you’d like to use (if you don’t want to use the theme provided in the cloned repo)
   • For more info about Jekyll themes, see the Jekyll docs https://jekyllrb.com/docs/themes/
4. (Optional) - In the blog folder, delete all of the files and replace them with the desired Jekyll template files

5. In the infrastructure folder, activate the Python virtual environment

    # Mac or Linux 
    source .venv/bin/activate
       
    # Windows
    # .venv\Scripts\activate.bat
   

6. Install the requirements in the requirements.txt file

    pip install -r requirements.txt
   

7. Bootstrap the AWS Account & Region

    cdk bootstrap --profile <profileName>
   

8. At the root of your repository, create .env file. This file will be used to provide environment variables to the CDK script

    touch .env
   

9. Populate the .env file with the following values

    AWS_ACCOUNT_NUMBER=<AWS_ACCOUNT_NUMBER>
    AWS_REGION=<AWS_REGION>
    DOMAIN_NAME=<DOMAIN_NAME>
    BASE_DOMAIN=<BASE_DOMAIN>
    REPO_OWNER=<REPO_OWNER>
    REPO_NAME=<REPO_NAME>
    REPO_BRANCH=<REPO_BRANCH>
   

   • AWS_ACCOUNT_NUMBER - This is the account number of the AWS account used to host the blog. This will be used to create an environment in CDK
   • AWS_REGION - The region in the AWS account that the blog will be deployed to. This will be used to create an environment in CDK
   • DOMAIN_NAME - This is the domain name that you want your blog to have (excluding www. The www record will be added automatically). Example: blog.supercoolsite.com
   • BASE_DOMAIN - This is the root domain you purchased on Route 53. This should not contain any subdomains. If you are not using subdomains for your blog, then the value of the DOMAIN_NAME and BASE_DOMAIN will be the same. Example: supercoolsite.com
   • REPO_OWNER - Name of the owner of your repository. It will either be your GitHub username if you are hosting the repo from your GitHub user or will be the name of the GitHub organization that owns the repository.
   • REPO_NAME - Name of your repository
   • REPO_BRANCH - Branch that will be used by CI/CD to detect commits and deploy from. I would recommend using the main branch.
10. Commit and publish the changes to your repository up to your remote main branch

11. Deploy the CDK stack using the deploy command

    cdk deploy --profile <profileName>
    

12. After the deployment has finished, login to your AWS accounts management console, then select the region that you deployed the blog into
13. Using the search bar at the top of the management console, search for and select “CodePipeline”
14. Once in the CodePipline service, you will see the pipeline that was created by CDK for the blog. This is where you can see the progress of your blog deployments in the future. The first run of the CodePipeline will fail because you have to finish configuring the link between your AWS account and GitHub.
15. In the left-hand menu, under CodePipeline, select Setting —> Connections
16. On the connections, click on the pending connection named jekyll-static-site
17. Once on the jekyll-static-site connection page, click the button to finish setting up the connection. Walk through the prompts to complete the setup.
18. After the connection setup has been completed, you can return to CodePipeline. Select the pipeline for the blog and press the Release Changes button to force a new deployment.
19. After the deployment has been completed, you should be able to see your blog at the domain name you provided in the .env file.
20. Your blog is now published. You can post new articles to your blog by following the steps specified by your Jekyll theme. Once your new article is ready to be published, you can automatically deploy it by simply checking in your changes to the branch specified for the REPO_BRANCH variable in the .env file.

Happy Blogging!

Basic Concepts

• Constructs
  • Constructs are the building block of CDK.
  • Constructs can range from single resources provided by AWS to complicated custom collections of resources created to work together.
  • The constructs created by AWS are defined in the AWS Construct Library.
  • There are 3 levels of constructs
    • L1
      • Low-level construct with a 1-to-1 mapping to the corresponding CloudFormation resource
      • L1 resource names start with Cfn
    • L2
      • Higher-level construct that allows for resource creation with enhanced functionality
      • Assists with resource creation by providing defaults and boilerplates
    • L3
      • High-level construct that allows for common tasks that require multiple resources to be easily completed
  • For more information about constructs, check out the docs https://docs.aws.amazon.com/cdk/v2/guide/constructs.html
• Stacks
  • Deployable collection of resources
  • CDK stacks get synthesized into CloudFormation stacks using the cdk synth command
  • Stacks can be nested using the NestedStack construct
  • For more information about stacks, check out the docs https://docs.aws.amazon.com/cdk/v2/guide/stacks.html
• App
  • Container for one or many stacks
  • Stacks inside of the same app can reference resources in one another
  • Stacks can be deployed individually within an app. This is helpful when defining multiple environments
  • For more information about the app, check out the docs https://docs.aws.amazon.com/cdk/v2/guide/apps.html
• Environments
  • Environments specify the AWS account and region that a stack should be associated to
  • Environments are not required for stacks; however, if it’s not explicitly provided, then a stack is considered environment-agnostic
  • For more information about environments, check out the docs https://docs.aws.amazon.com/cdk/v2/guide/environments.html
• Bootstrapping
  • Bootstrapping is the process of configuring an account and region to use CDK
  • Bootstrapping must be run the first time that that CDK is used in an account and environment; however, subsequent cdk runs do not need to bootstrap
  • Bootstrapping is account and region-specific, so it must be run in all regions in a particular account you wish to use CDK with
  • CDK creates a CloudFormation script in the specific region to deploy the CDKToolkit
  • For more information about bootstrapping, check out the docs https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html

Commands

There are many commands available using the cdk cli tool. To use the cdk tool you must first install it on your machine. Additionally, you will need an AWS account, the aws cli and a profile already set up on the local machine. For information about the aws cli please see the aws cli documentation https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html. For information about how to install the cdk cli tool and additional information about the following commands, see the cdk documentation https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html.

• list - Lists the stacks in the App

    cdk list --profile <profileName>
  

• synth - Synthesizes cdk code into CloudFormation scripts in the cdk.out folder

    cdk synth <stackName> --profile <profileName>
  

• bootstrap - Bootstraps an account and region by using cloudformation to deploy the CDKToolkit

    cdk bootstrap --profile <profileName>
  

• deploy - Synthesizes and deploys cdk stacks to AWS

    cdk deploy <stackName> --profile <profileName>
  

• destroy - Destroys the specified cdk stack

    cdk destroy <stackName> --profile <profileName>
  

• diff - Checks the state of the current configuration against the configuration hosted in the account

    cdk diff <stackName> --profile <profileName>
  

• init - Initializes a new cdk app

    cdk init --language <languageName> --profile <profileName>
  

CDK is a powerful tool with a lot more features than have been covered in this post. I highly recommend you read through the docs and work through some examples to get hands-on with CDK. The CDK workshop provides some great examples to get you hands-on with CDK (https://cdkworkshop.com/).

CDK is a great option for DevOps engineers who would need more functionality out of their IaC tooling and developers who would feel more comfortable keeping their IaC stacks closer to their code. IaC is extremely important for running applications in the cloud, and AWS CDK is a great option to have in your tech stack.

Like anything new, starting a blog can be tough. It’s hard to know how to get started. At a high level, there are a couple of things to consider when starting a blog, how you want to host it and where you want to host it. Let’s first start with how you want to host it. There are many options for creating a blog. Typically, they fall into the category of an off-the-shelf application such as WordPress, a static-generated site, or a custom site.

How to Host

Applications such as WordPress can be great options for hosting a blog or other types of sites. WordPress is one of if not the most popular website platforms on the market today. It’s easy to use, has many third-party plugins, and has a strong support community. While WordPress is a strong option, it also comes with some trade-offs. WordPress uses PHP and server-side code to host your website, which means it must be run on a server. Since the site needs to run on a server, there is typically a cost to host the site. Often the cost to host a WordPress site is minimal for smaller sites, but the costs can quickly add up after adding redundancy to the site and extra plugins. The site running on a server also means that it needs to have security patching and maintenance performed on it to ensure the safety of your site. If the WordPress blog is hosted on a platform that manages your site for you, it will typically contribute to your overall cost. Finally, solutions such as WordPress typically offer many features that are overkill for a simple blog. Most blogs don’t need advanced features and, therefore, can make using these tools more complicated for users.

Static site generators are a great option for hosting a simple blog. They are frameworks created using popular programming languages such as Ruby, Javascript, and Go. These frameworks allow users to create content by writing posts in markdown and then generate all of the code required to create the blog. Since there is no server-side code, these sites can be hosted on platforms such as AWS for a very low cost, if not free. Many of these frameworks also have templates that can be used for the site layout and aesthetics. An additional benefit of static sites is the reduced overhead. Since servers are not required to run the sites, you don’t have to worry about patching and maintenance on servers. One of my personal favorite static site generators is Jeykll. It’s an easy-to-use framework written in Ruby. It has many great, free templates available for users, and it has a large community that can help address any issues or questions.

A custom site could also be an option for individuals with the skill and desire to create their site. WordPress and static site generators do not require development skills from users. Users can choose from tons of different templates. The benefit of creating a custom site is that it allows you to create the site exactly the way you want it. It’s a good option if you have the required skills, but for someone like myself who does not come from a front-end development background, the learning curve is more than I’d want to take on for a simple blog.

Where to Host

Now that you understand how to host your blog better, it’s important to understand where to host it. There are a lot of companies on the market today that host websites. WordPress.com, Squarespace, and Wix are well-known options for off-the-shelf applications. They offer a variety of different options and pricing to choose from. If you would like to use an off-the-shelf solution such as WordPress and don’t want to have to manage the underlying resources yourself, then you should consider one of these providers.

If you would rather host your site yourself, or a static or custom site, then other platforms should be considered. For static sites, platforms such as Netlify can be good options. Netlify and other similar platforms offer entry-level starter tiers for free for users to get their blogs published globally. These platforms require very little to no knowledge of the underlying infrastructure required to host your site, and you can get your site up and running quickly.

Platforms like Netlify can be great for getting started but are very limited in what they offer. To expand your options, you should consider using a cloud platform such as AWS. AWS is a great option for hosting any of the discussed types of blogs. You can host off-the-shelf solutions along with static and custom sites. Using AWS gives you access to a wide array of services for not just your blog but any other applications you may want to use in the future. AWS always only charges for the resources you use, so hosting a static blog globally can be done for a very low cost, if not free.

There is a wide array of options to choose from when hosting a blog. There is not a one size fits all option either. You need to pick the right application and hosting provider to meet your individual needs. Personally, I chose to go with Jeykll and AWS but if WordPress with a managed provider works better for you, then do that. What’s most important at the end of the day is that you are sharing your knowledge and passion with the world.