gem-hunterThe CloudFormation Provider Development Toolkit allows you to author your own resource providers and modules that can be used by CloudFormation.
The CloudFormation CLI (cfn) allows you to author your own resource providers, hooks, and modules that can be used by CloudFormation.
Primary documentation for the CloudFormation CLI can be found at the AWS Documentation site.
This tool can be installed using pip from the Python Package Index (PyPI). It requires Python 3. For resource and hook types, the tool requires at least one language plugin. Language plugins are not needed to create a module type. The language plugins are also available on PyPI and as such can be installed all at once:
pip install cloudformation-cli cloudformation-cli-java-plugin cloudformation-cli-go-plugin cloudformation-cli-python-plugin cloudformation-cli-typescript-plugin
To create a project in the current directory, use the init command. A wizard will guide you through the creation.
cfn init
To refresh auto-generated code, use the generate command. Usually, plugins try to integrate this command in the native build flow, so please consult a plugin's README to see if this is necessary.
In a module project, this will regenerate the module schema.
cfn generate
To register a resource provider, module, or hook in your account, use the submit command.
cfn submit cfn submit --dry-run #prepares schema handler package without submitting for registration cfn submit --set-default # if successfully registered, set submitted version to be the new default version
This is to create a schema handler package without submitting equivalent to cfn submit --dry-run
cfn package
To run the contract tests for a resource type, use the test command.
cfn test cfn test -- -k contract_delete_update # to run a single test cfn test -- --tb=long # exhaustive, informative traceback formatting cfn test --enforce-timeout 60 # Read/List handler timeout (Create/Update/Delete handler timeout is twice the Read/List handler timeout) cfn test --enforce-timeout 60 -- -k contract_delete_update # combine arguments cfn test --log-group-name cw_log_group --log-role-arn log_delivery_role_arn # Handler logs generated by contract tests will be delivered to the specified cw_log_group using the credentials from log_delivery_role_arn
Note:
To use your type configuration in contract tests, you will need to save your type configuration json file in ~/.cfn-cli/typeConfiguration.json or specify the file you would like to use
--typeconfig ./myResourceTypeConfig.json--typeconfig /test/myresource/config1.json--typeconfig C:\MyResource\typeconf.jsonTo use propertyTransform in schema, you will need to install PYJQ. This feature will not be available to use with contract tests on Windows OS
Install PYJQ for Linux system
yum install autoconf automake libtool pip install pyjq
Install PYJQ for macOS system
brew install autoconf automake libtool brew install jq pip install pyjq
Install PYJQ for Ubuntu system
pip install pyjq
cfn test --v2 is an opt-in flag that runs the contract tests through the RQTS (CTv2) executor in a Docker container instead of the default pytest-based suite. Without --v2, the existing behavior is unchanged.
cfn test --v2 cfn test --v2 --region us-west-2 --profile my-profile cfn test --v2 --typeconfig ./myResourceTypeConfig.json # type configuration is passed through to the executor cfn test --v2 --rqts-image my-registry/my-executor:my-tag # override the CLI-pinned executor image
The runner checks all of the following before starting the container, and reports every unmet requirement at once:
<hyphenated-type-name>.zip exists in the project root. Run cfn generate and your language plugin's build first.sts:GetCallerIdentity.Notes:
-- -k contract_delete_update are silently ignored on the --v2 path. Test inputs are read from the ones packaged inside the artifact zip.rqts-output/ in the project root, and per-scenario results are streamed to the console as the container runs.latest tag on ECR Public, matching what the cloud contract-test path runs. The CLI attempts a pull on each run and falls back to a locally cached image when the registry is unreachable.To validate the schema, use the validate command.
This command is automatically run whenever one attempts to submit a resource, module, or hook. Errors will prevent you from submitting your resource/module. Module fragments will additionally be validated via cfn-lint (but resulting warnings will not cause this step to fail).
cfn validate
To build an image for a resource type. This image provides a minimalistic execution environment for the resource handler that does not depend on AWS Lambda in anyway. This image can be used during cfn invoke and cfn test instead of using sam cli.
cfn build-image cfn build-image --image-name my-handler --executable target/myjar.jar
The resulting image can be run in a container by executing the following command:
docker run IMAGE_NAME HANDLER_ENTRYPOINT PAYLOAD
docker run my-test-resource com.my.test.resource.ExecutableHandlerWrapper PAYLOAD_JSON # Example for a java based-project
For developing, it's strongly suggested to install the development dependencies inside a virtual environment. (This isn't required if you just want to use this tool.)
python3 -m venv env source env/bin/activate pip install -e . -r requirements.txt pre-commit install
If you're creating a resource or hook type, you will also need to install a language plugin, such as the Java language plugin, also via pip install. For example, assuming the plugin is checked out in the same parent directory as this repository:
pip install -e ../cloudformation-cli-java-plugin
# run all hooks on all files, mirrors what the CI runs pre-commit run --all-files # run unit tests only. can also be used for other hooks, e.g. black, flake8, pylint-local pre-commit run pytest-local
If you want to generate an HTML coverage report afterwards, run coverage html. The report is output to htmlcov/index.html.
New language plugins can be independently developed. As long as they declare the appropriate entry point and are installed in the same environment, they can even be completely separate codebases. For example, a plugin for Groovy might have the following entry point:
entry_points={ "rpdk.v1.languages": ["groovy = rpdk.groovy:GroovyLanguagePlugin"], },
Plugins must provide the same interface as LanguagePlugin (in plugin_base.py). And they may inherit from LanguagePlugin for the helper methods - but this is not necessary. As long as the class has the same methods, it will work as a plugin.
| Language | Status | Github | PyPI |
|---|---|---|---|
| Java | Available | cloudformation-cli-java-plugin | cloudformation-cli-java-plugin |
| Go | Available | cloudformation-cli-go-plugin | cloudformation-cli-go-plugin |
| Python | Available | cloudformation-cli-python-plugin | cloudformation-cli-python-plugin |
| TypeScript | Available | cloudformation-cli-typescript-plugin | cloudformation-cli-typescript-plugin |
| Language | Status | Github | PyPI |
|---|---|---|---|
| Java | Available | cloudformation-cli-java-plugin | cloudformation-cli-java-plugin |
| Python | Available | cloudformation-cli-python-plugin | cloudformation-cli-python-plugin |
This library is licensed under the Apache 2.0 License.
Join us on Discord! Connect & interact with CloudFormation developers & experts, find channels to discuss and get help for our CLI, cfn-lint, CloudFormation registry, StackSets, Guard and more: