Skip to content

logo https://aws-ia.github.io

Build Status PyPI version License

Installation

Usage

Support

What is taskcat?

taskcat is a tool that tests AWS CloudFormation templates. It deploys your AWS CloudFormation template in multiple AWS Regions and generates a report with a pass/fail grade for each region. You can specify the regions and number of Availability Zones you want to include in the test, and pass in parameter values from your AWS CloudFormation template. taskcat is implemented as a Python class that you import, instantiate, and run.

taskcat was developed by the aws-ia team to test AWS CloudFormation templates that automatically deploy workloads on AWS. We’re pleased to make the tool available to all developers who want to validate their custom AWS CloudFormation templates across AWS Regions

Support

Feature Request Report Bugs

Installation

Currently only installation via pip is supported. Installation via docker coming soon.

Requirements

Python pip PyPI - Python Version Python pip

The host taskcat is run on requires access to an AWS account, this can be done by any of the following mechanisms:

  1. Environment variables
  2. Shared credential file (~/.aws/credentials)
  3. AWS config file (~/.aws/config)
  4. Assume Role provider
  5. Boto2 config file (/etc/boto.cfg and ~/.boto)
  6. Instance metadata service on an Amazon EC2 instance that has an IAM role configured.

for more info see the boto3 credential configuration documentation.

Note: docker is only required if building lambda functions using a Dockerfile

Installing via pip3

pip3 install taskcat

Installing via pip3 --user

will install taskcat into homedir, useful if you get permissions errors with the regular method

pip3 install taskcat --user

Note: the user install dir is platform specific

For Example: (On Mac: ~/Library/Python/3.x/bin/taskcat)

For Example: (On Linux: ~/.local/bin)

Warning: Be sure to add the python bin dir to your $PATH

Windows

taskcat on Windows is not supported.

If you are running Windows 10 we recommend that you install Windows Subsystem for Linux (WSL) and then install taskcat inside the WSL environment using the steps above.

Usage

CLI

The cli is self documenting by using --help. The most common use of taskcat is for executing function tests of CloudFormation templates. The command for this is:

taskcat test run

add --help to see the supported flags and arguments

Python

Taskcat can be imported into Python and used in the testing framework of your choice.

from taskcat.testing import CFNTest

test = CFNTest.from_file(project_root='./template_dir')

with test as stacks:
    # Calling 'with' or 'test.run()' will deploy the stacks.
    for stack in stacks:
        print(f"Testing {stack.name}")

        bucket_name = ""

        for output in stack.outputs:

            if output.key == "LogsBucketName":
                bucket_name = output.value
                break

        assert "logs" in bucket_name

        assert stack.region.name in bucket_name

        print(f"Created bucket: {bucket_name}")

The example used here is very simple, you would most likely leverage other python modules like boto3 to do more advanced testing. The CFNTest object can be passed the same arguments as taskcat test run. See the docs for more details.

Config files

taskcat has several configuration files which can be used to set behaviors in a flexible way.

Global config

~/.taskcat.yml provides global settings that become defaults for all projects.

 # General configuration settings
 general                 
   auth # AWS authentication section
      <AUTH_NAME>
   parameters: # Parameter key-values to pass to cfn  (global parameters take precedence) 
      <PARAMETER_NAME>    

   s3_bucket: # Name of S3 bucket to upload project to (if left out a bucket will be auto-generated)
   s3_regional_buckets: # Boolean flag to upload the project to a bucket (generated in each region specified)
   tags: # Tags to apply to CloudFormation template
      TAG_NAME

Project config

File location: /.taskcat.yml` provides project specific configuration.

project         # Project specific configuration section
  auth          # AWS authentication section
    <AUTH_NAME>
  az_blacklist  # List of Availability Zones ID's to exclude when generating availability zones
  build_submodules # Build Lambda zips recursively for submodules, set to false to disable
  lambda_source_path # Path relative to the project root containing Lambda zip files, default is 'lambda_functions/source'
  lambda_zip_path    # Path relative to the project root to place Lambda zip files, default is 'lambda_functions/zips'
  name               # Project name, used as s3 key prefix when uploading objects
  owner              # Email address for project owner (not used at present)
  package_lambda     # Package Lambda functions into zips before uploading to s3, set to false to disable
  parameters         # Parameter key-values to pass to CloudFormation, parameters provided in global config take precedence
    <PARAMETER_NAME>
  regions            # List of AWS regions
  s3_bucket          # Name of S3 bucket to upload project to, if left out a bucket will be auto-generated
  s3_enable_sig_v2   # Enable (deprecated) sigv2 access to auto-generated buckets
  s3_object_acl      # ACL for uploaded s3 objects, defaults to 'private'
  tags               # Tags to apply to CloudFormation template
    <TAG_NAME>
  template           # path to template file relative to the project config file path

tests:
    auth            # AWS authentication section
      <AUTH_NAME>
    az_blacklist    # List of Availability Zones ID's to exclude when generating availability zones
    parameters      # Parameter key-values to pass to CloudFormation, parameters provided in global config take precedence
      <PARAMETER_NAME>
    regions         # List of AWS regions
    s3_bucket       # Name of S3 bucket to upload project to, if left out a bucket will be auto-generated
    tags            # Tags to apply to CloudFormation template
      <TAG_NAME>
    template        # Path to template file relative to the project config file path

> At minimum it must provide a project name, list of regions, template name and one test.

Minimal example:

```yaml
project:
  name: my-cfn-project
  regions:
  - us-west-2
  - eu-north-1
tests:
  default:
    template: ./templates/my-template.yaml

Complete example with comments: tests/data/config_full_example/.taskcat.yml

Parameter overrides

a parameter override file can be created in <PROJECT_ROOT>/.taskcat_overrides.yml. Parameter Keys/Values specified in this file take precedence over values defined in all other configuration files. For example:

KeyPair: my-overriden-keypair
VpcId: vpc-1234abcd

Warning: it is recommended to add .taskcat_overrides.yml to .gitignore to ensure it is not accidentally checked into source control

Precedence

With the exception of the parameters section, more specific config with the same key takes precedence.

The rationale behind having parameters function this way is so that values can be overridden at a system level outside of a project, that is likely committed to source control. parameters that define account specific things like VPC details, Key Pairs, or secrets like API keys can be defined per host outside of source control.

For example, consider this global config:

~/.taskcat.yml

general:
  s3_bucket: my-globally-defined-bucket
  parameters:
    KeyPair: my-global-ec2-keypair

Given a simple project config:

project:
  name: my-project
  regions:
  - us-east-2
tests:
  default:
    template: ./template.yaml

The effective test configuration would become:

tests:
  default:
    template: ./template.yaml
    s3_bucket: my-globally-defined-bucket
    parameters:
      KeyPair: my-global-ec2-keypair

If any item is re-defined in a project it takes precedence over the global value. Anything defined in a test takes precedence over what is defined in the project or global configuration. with the exception of the parameters section which works in reverse. For example, using the same global config as above, given this project config:

project:
  name: my-project
  regions:
  - us-east-2
  s3_bucket: my-project-s3-bucket
tests:
  default:
    template: ./template.yaml
    parameters:
      KeyPair: my-test-ec2-keypair

Would result in this effective test configuration:

tests:
  default:
    template: ./template.yaml
    s3_bucket: my-project-s3-bucket
    parameters:
      KeyPair: my-global-ec2-keypair

Notice that s3_bucket took the most specific value and KeyPair the most general.

CLI interface

taskcat adopts a similar cli command structure to git with a taskcat command subcommand --flag style. The cli is also designed to be simplest if run from the root of a project. Let's have a look at equivalent command to run a test:

cd into the project root and type test run:

cd ./quickstart-aws-vpc
taskcat test run

or run it from anywhere by providing the path to the project root

taskcat test run -p ./quickstart-aws-vpc

Non-standard credentials

taskcat leverages the credential mechanisms of the AWS CLI, with the exception of environment variables. To integrate advanced credential handling (such as AWS SSO), please see issue #596 for an example

Configuration files

The configuration files required for taskcat have changed, to ease migration, if taskcat is run and legacy config files are found, they are converted and written to new file locations. For more information on the new format, see the config file docs.

Dynamic values

The example below shows an input file for a stack that requires six parameters ,InstanceType, AvailablityZones, RandomString, RandomNumbers, GenerateUUID and Password

Note: Value that matches the following pattern will be replaced: * All runtime injection parameters must start with $[ * Parameters must end with]

(see examples below)

From: (defined in taskcat.yaml')

     InstanceType: t2.small
     AvailablityZones: $[taskcat_genaz_2]
     RandomString: $[taskcat_random-string]
     RandomNumbers: $[taskcat_random-numbers]
     GenerateUUID: $[taskcat_genuuid]
     Password: $[taskcat_genpass_8A]
     PasswordConfirm: $[taskcat_getval_Password]

To: (At runtime passed to cloudformation API)

     InstanceType: t2.small
     AvailablityZones: us-east-1a: us-east1b
     RandomString: yysuawpwubvotiqgwjcu
     RandomNumbers: 56188163597280820763
     GenerateUUID: 1c2e3483-2c99-45bb-801d-8af68a3b907b
     Password: tI8zN3iX8
     PasswordConfirm: tI8zN3iX8

Gen Passwords

More info on Passwords Generation

To generate a random 8 character alpha-numeric password for testing use $[taskcat_genpass_8] as the value in the json input file * The number (8) in the injection string tells taskcat you want a password that character long. * Changing the 8 to 12 would result in a 12 character string

(Optionally - you can specify the type of password by adding A or S)

  • A alpha-numeric passwords
  • S passwords with special characters

Example: $[taskcat_genpass_8A]

Generates: tI8zN3iX8

Example: $[taskcat_genpass_8S]

Generates: mA5@cB5!

(Retrieve previously generated value based on parameter name)

UseCase: Need to confirm a dynamically generated password

Example MyAppPassword $[taskcat_genpass_8A]

Generates: pI8zN4iX8

Example ConfirmMyAppPassword: $[taskcat_getval_MyAppPassword]

Generates: pI8zN4iX8

Auto input AvailablityZones

More info on passsing in AvailablityZones based on test region Value that matches the following pattern will be replaced

  • Parameters must end with ]
  • genaz in invoked when taskcat_genaz_X is found
  • A number of AZ's will be selected from the region the stack is attempting to launch

Example: $[taskcat_genaz_2]

Generates: us-east-1a, us-east-2b

(if the region is us-east-1)

Auto generated s3 bucket

Example: $[taskcat_autobucket]

Generates: evaluates to auto generated bucket name (taskcat-tag-sample-taskcat-project-5fba6597)

Auto generate UUID String

Example: $[taskcat_genuuid]

Generates: 1c2e3483-2c99-45bb-801d-8af68a3b907b

A generate Random Values

String:

Example: $[taskcat_random-string]

Generates: yysuawpwubvotiqgwjcu

Numbers:

Example: $[taskcat_random-numbers]

Generates: 56188163597280820763

GitHub

GitHub stars GitHub issues GitHub closed issues GitHub pull requests GitHub closed pull requests

PyPi

PyPI - Downloads PyPI - Downloads