An OpenSource Cloudformation Deployment Framework
Project description
taskcat
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:
- Environment variables
- Shared credential file (~/.aws/credentials)
- AWS config file (~/.aws/config)
- Assume Role provider
- Boto2 config file (/etc/boto.cfg and ~/.boto)
- 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-generatedtags
Tags to apply to CloudFormation template<TAG_NAME>
Project config
<PROJECT_ROOT>/.taskcat.yml
provides project specific configuration.
-
project
Project specific configuration sectionauth
AWS authentication section<AUTH_NAME>
az_blacklist
List of Availability Zones ID's to exclude when generating availability zonesbuild_submodules
Build Lambda zips recursively for submodules, set to false to disablelambda_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 objectsowner
email address for project owner (not used at present)package_lambda
Package Lambda functions into zips before uploading to s3, set to false to disableparameters
Parameter key-values to pass to CloudFormation, parameters provided in global config take precedence<PARAMETER_NAME>
regions
List of AWS regionss3_bucket
Name of S3 bucket to upload project to, if left out a bucket will be auto-generateds3_enable_sig_v2
Enable (deprecated) sigv2 access to auto-generated bucketss3_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 zonesparameters
Parameter key-values to pass to CloudFormation, parameters provided in global config take precedence<PARAMETER_NAME>
regions
List of AWS regionss3_bucket
Name of S3 bucket to upload project to, if left out a bucket will be auto-generatedtags
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:
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file taskcat-0.9.18.dev3.tar.gz
.
File metadata
- Download URL: taskcat-0.9.18.dev3.tar.gz
- Upload date:
- Size: 66.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.1.3 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.6.7
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | d8424b1049a809b7b653b9691cfd90c50a974803101d920f9f1e2447d026bd0a |
|
MD5 | 8498838c5e2aa84822756668724ec9a1 |
|
BLAKE2b-256 | 0d63058efba95ffa8c1c3f63d7888ef44e34047405f0deca01d90410332f147f |