nn-cfnctl 0.2.0

CLI Tool for deploying CloudFormation using a YAML based config file for stack and parameter settings.

CloudFormation Control

About The Project

Cloud Formation Control (cfnctl) is a commandline utility based of the AWS CLI Deploy features. On top of existing deployment capabilities it adds the ability to specify a configuration file to easily supply the following parameters to your CloudFormation deployment:

• StackName
• AwsRegion
• StackParameters
• StackTags

Supplying your CloudFormation template with a config containing the above parameters, and a set of commandline arguments or environment variables, it makes it easier to deploy CloudFormation templates both from your local development machine as well as a pipeline using the same pipelines and configurations.

Built With

This project is build using the following tools and frameworks:

• Python
• Boto3
• Typer
• Poetry

Getting Started

In order to get started with developing and contributing to this project, follow the steps below.

Prerequisites

pipx (Optional)

This project is build and managed by poetry, the easiest way to install poetry in an isolated environment is using pipx.

python -m pip install --user pipx
python -m pipx ensurepath

Poetry

If you installed pipx, you can simply install poetry using the command below:

pipx install poetry

If you did not install pipx, see Poetry documentation for installation method for your system.

Installation

1. Clone the repository

   git clone https://[e-mail]/novonordiskit/GITO-HS/_git/aws-cfnctl
   

2. Change directory into the cloned repository

   cd aws-cfnctl
   

3. Install dependencies into a virtual environment with poetry

   poetry install
   

4. Activate virtual environment with poetry

   poetry shell
   

Usage

When installed somewhere on the system included in the systems PATH, the application can be called with cfnctl.
To see all available options for the CLI run:

cfnctl --help  

The cfnctl command has two primary subcommands:

• cfnctl plan
• cfnctl apply

cfnctl plan

cfnctl plan creates a new stack plan, or if the stack already exists, a change set plan for AWS CloudFormation. The resulting plan can then be used with cfnctl apply to execute the stack / change set and provision it in AWS.

If you wish to execute the plan immediately, set the --auto-apply commandline flag or use the CFNCTL_AUTO_APPLY = $TRUE.

The cfnctl plan command requires the following options:

• --name "CloudFormation change set name."
• --description "CloudFormation change set description."
• --template "Relative or absolute filepath pointing to CloudFormation template file."
• --config "Relative or absolute filepath pointing to CloudFormation template config file."
• --output "Relative or absolute filepath for resulting change set file."

The following settings can be set optionally:

• --export-stack "Export the Stack ID as an Azure DevOps pipeline variable with this name."
• --export-changeset "Export the change set ID as an Azure DevOps pipeline variable with this name."
• --export-outputs "Exports the stack output as Azure DevOps pipeline variables."
• --auto-apply "If set to true, changeset will be created then executed"

cfnctl apply

cfnctl apply executes a stack plan, or if the stack already exists, executes a change set with AWS CloudFormation. The command requires a plan file created with the cfnctl plan command.

The cfnctl plan command requires the following options:

• --name "CloudFormation change set name."
• --description "CloudFormation change set description."
• --template "Relative or absolute filepath pointing to CloudFormation template file."
• --config "Relative or absolute filepath pointing to CloudFormation template config file."
• --output "Relative or absolute filepath for incoming change set file."

The following settings can be set optionally:

• --export-stack "Export the Stack ID as an Azure DevOps pipeline variable with this name."
• --export-changeset "Export the change set ID as an Azure DevOps pipeline variable with this name."
• --export-outputs "Exports the stack output as Azure DevOps pipeline variables."

Environment variables

Instead of using commandline parameters, it is possible to configure the cfnctl plan and cfnctl apply commands using environment variables.

PowerShell environment variables

Setting environment variables in PowerShell:

$env:CFNCTL_CHANGESET_NAME = "MyChangeSet"
$env:CFNCTL_CHANGESET_DESCRIPTION = "Change Set for my stack"
$env:CFNCTL_TEMPLATE_PATH = "my-cfn-template-file.yml"
$env:CFNCTL_STACK_CONFIG_PATH = "my-cfnctl-config-file.yml"
$env:CFNCTL_PLAN_OUTPUT_PATH = "cfn-output-file.yml"

# Optional
$env:CFNCTL_STACK_ID_EXPORT_VAR = "CFNCTL_STACK_ID"
$env:CFNCTL_CHANGESET_ID_EXPORT_VAR = "CFNCTL_CHANGESET_ID"
$env:CFNCTL_EXPORT_STACK_OUTPUT = $TRUE
$env:CFNCTL_AUTO_APPLY = $TRUE

You can validate the values is set correctly in your shell with:

Get-Item -Path Env:* | Where-Object {$_.name -like "CFNCTL_*"}

Bash environment variables

Setting Environment variables in Bash:

export CFNCTL_CHANGESET_NAME = "MyChangeSet"
export CFNCTL_CHANGESET_DESCRIPTION = "Change Set for my stack"
export CFNCTL_TEMPLATE_PATH = "my-cfn-template-file.yml"
export CFNCTL_STACK_CONFIG_PATH = "my-cfnctl-config-file.yml"
export CFNCTL_PLAN_OUTPUT_PATH = "cfn-output-file.yml"

# Optional
export CFNCTL_STACK_ID_EXPORT_VAR = "CFNCTL_STACK_ID"
export CFNCTL_CHANGESET_ID_EXPORT_VAR = "CFNCTL_CHANGESET_ID"
export CFNCTL_EXPORT_STACK_OUTPUT = true
export CFNCTL_AUTO_APPLY = true

You can validate the values is set correctly in your shell with:

env | grep 'CFNCTL_'