AWS EC2 Provisioner

This is the repository for a container based AWS EC2 Provisioner, which can provision EC2 instances based on a provided configuration.

Preparations

AWS CDK

You need to have an AWS account and your AWS CDK setup.

See Getting started with AWS CDK Tutorial for help how to setup AWS CDK.

Provide the configuration

The configuration for the AWS infrastructure is provided via a json file named configuration.json which is located in the mapped /config directory and contains the following configuration parameters.

• id
  A unique id string, which is added as a tag to all created resources

• account
  The account which provisions the AWS infrastructure, must correlate to the provided aws credentials

• region
  The region to the deploy the AWS infrastructure to

• ami
  The ami-id of the Linux EC2 image to use

• count
  The count of the EC2 instances to create, for same instance configuration only

• class
  The class of the EC2 instances to create. (case-insensitive)

• size
  The size of the EC2 instances to create. (case-insensitive)

The following configuration is useful when you want to provision multiple EC2 instances of the same type and configuration.

Configuration same instance configuration n-times

{
  "id": "Ec2Environment",
  "account": "***",
  "region": "eu-central-1",
  "instance": {
    "ami": "ami-0dc2fd10d56160b0f",
    "count": 1
  }
}

The following configuration is useful when you want to provision multiple EC2 instances of different type and configuration.

Configuration different instance configurations

{
  "id": "Ec2Environment",
  "account": "***",
  "region": "eu-central-1",
  "instances": [
    {
      "ami": "ami-0dc2fd10d56160b0f",
      "class": "T4G",
      "size": "MEDIUM"
    },
    {
      "ami": "ami-0a074964af44a2b26",
      "class": "T4G",
      "size": "MEDIUM"
    }
  ]
}

Important

Don’t change the id after a AWS infrastructure has been provisioned, because otherwise it cannot be destroyed anymore. You always can destroy the AWS Stack via the AWS Management Console.

Tip	See the AWS documentation EC2 instance types about the EC2 instance types. See the Available AMIs per region you can choose from. Also the note the relation between the class and AMI cpu architecture!!

Provision an environment

How to use the container image

podman run \
  -v ./out:/out:rw \
  -v $(echo ~)/.aws:/root/.aws:ro \
  -v ./config:/provision/config:ro \
  ghcr.io/cchet/aws-ec2-provisioner:[latest | <BRANCH_OR_TAG_NAME>] \
  [synth | deploy | destroy]

The following mounts are necessary.

• ./out:/out
  This is where the ssh-key pairs are created as well as the info.json file where the ip addresses and domain names of the provisioned AWS EC2 instances can be found.

• $(echo ~)/.aws:/root/.aws:ro
  This is the directory where your AWS credentials are stored and which are used by the AWS CDK CLI.

• ./config:/provision/config:ro
  This is where the configuration such as configuration.json and bootstrap.sh and/or callback.h scripts are located.

The following commands are available.

• synth
  Synthesizes the infrastructure definition.
  This is also the default command.

• deploy
  Deploys the infrastructure.

• destroy
  Destroys the provisioned the infrastructure.

How to bootstrap your environment

You can configure your environment with a bootstrap script file named bootstrap.sh located in the mapped /config directory.

Important

The script must be executable on the used Linux distribution you defined via the ami configuration parameter.

How to provide callbacks

You can provide a callback script callback.sh located in the mapped /config directory, which gets executed after the deploy step has been finished.

Important

This script must use the shebang #!/bin/sh

The following resources are available after a deploy of an environment callback.sh script.

• /out/id_rsa<IDX>

• /out/id_rsa<IDX>.pub

• /out/info.json`

The following environment variables are available during the execution of the callback.sh script.

• CONFIGURATION_DIR

• OUT_DIR

• EXECUTION_DIR`

Useful commands in the callback.sh script.

• jq '.EC2Stack<ID>.instance[IP | URI]<INSTANCE_IDX>' ${OUT_DIR}/info.json
  Extracts the instance ip or uri where the instance can be addressed

• jq '.instance.count' ${CONFIGURATION_DIR}/configuration.json
  Gets the configured instance count for a single instance configuration

• jq '.instances | length' ${CONFIGURATION_DIR}/configuration.json
  Gets the configured instance count for a array instance configuration

Important

Be aware that all commands of the callback.sh script are executed within the container! But it can generate resources to the OUT_DIR directory, which is mapped to the host.

Local Development

You need to following software for the local development.

• NodeJS 21.2.0

• Docker or Podman

• aws-cdk (NodeJS, Brew, …​)

The shell you use need to have the environment variables set as defined in the .env file, which can be set via source .env.

You can build the container image locally with podman build -t <IMAGE_TAG> -f Containerfile ..

The AWS infrastructure can be synthesized, deployed and destroyed via the AWS CDK.