taskcat

Installation

Usage

Migrating from v0.8.x

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 QuickStart 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

Note: taskcat has changed significantly in the 0.9.0 release, for details see Migrating from v0.8.x

Support

Installation

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

Requirements

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

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 General configuration settings.
  • auth AWS authentication section
    • <AUTH_NAME>
  • parameters Parameter key-values to pass to CloudFormation, parameters provided in global config take precedence
    • <PARAMETER_NAME>
  • 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>

Project config

<PROJECT_ROOT>/.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:

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-global-ec2-keypair
    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-ec2-keypair
    parameters:
      KeyPair: my-global-ec2-keypair

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

Migrating from 0.8.x

taskcat 0.9.0 is a major re-write of the project and the opportunity was taken to modernise the cli interface update the config file format based on learnings from the previous releases.

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:

v0.8.x

taskcat -c ./quickstart-aws-vpc/ci/taskcat.yml

in v0.9.x you can cd into the project root for a very simple cli experience:

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

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.

---

GitHub:

PyPi: