[](https://github.com/aws-cloudformation/cloudformation-cli/actions/workflows/pr-ci.yaml)
# AWS CloudFormation CLI
The CloudFormation CLI (cfn) allows you to author your own resource providers, hooks, and modules that can be used by CloudFormation.
## Usage
### Documentation
Primary documentation for the CloudFormation CLI can be found at the [AWS Documentation](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/what-is-cloudformation-cli.html) site.
### Installation
This tool can be installed using [pip](https://pypi.org/project/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:
```bash
pip install cloudformation-cli cloudformation-cli-java-plugin cloudformation-cli-go-plugin cloudformation-cli-python-plugin cloudformation-cli-typescript-plugin
```
### Command: init
To create a project in the current directory, use the `init` command. A wizard will guide you through the creation.
```bash
cfn init
```
### Command: generate
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.
```bash
cfn generate
```
### Command: submit
To register a resource provider, module, or hook in your account, use the `submit` command.
```bash
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
```
### Command: package
This is to create a schema handler package without submitting equivalent to `cfn submit --dry-run`
```bash
cfn package
```
### Command: test
To run the contract tests for a resource type, use the `test` command.
```bash
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.json`
* To use `propertyTransform` in schema, you will need to install [PYJQ](https://pypi.org/project/pyjq/). This feature will not be available to use with contract tests on Windows OS
Install PYJQ for Linux system
```bash
yum install autoconf automake libtool
pip install pyjq
```
Install PYJQ for macOS system
```bash
brew install autoconf automake libtool
brew install jq
pip install pyjq
```
Install PYJQ for Ubuntu system
```bash
pip install pyjq
```
### Command: validate
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`](https://github.com/aws-cloudformation/cfn-python-lint/) (but resulting warnings will not cause this step to fail).
```bash
cfn validate
```
### Command: build-image
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.
```bash
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
```
## Development
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.)
```bash
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](https://github.com/aws-cloudformation/cloudformation-cli-java-plugin), also via `pip install`. For example, assuming the plugin is checked out in the same parent directory as this repository:
```bash
pip install -e ../cloudformation-cli-java-plugin
```
```bash
# 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`.
## Plugin system
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:
```python
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.
### Supported plugins
#### Resource Types Supported Plugins
| Language | Status | Github | PyPI |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Java | Available | [cloudformation-cli-java-plugin](https://github.com/aws-cloudformation/cloudformation-cli-java-plugin/) | [cloudformation-cli-java-plugin](https://pypi.org/project/cloudformation-cli-java-plugin/) |
| Go | Available | [cloudformation-cli-go-plugin](https://github.com/aws-cloudformation/cloudformation-cli-go-plugin/) | [cloudformation-cli-go-plugin](https://pypi.org/project/cloudformation-cli-go-plugin/) |
| Python | Available | [cloudformation-cli-python-plugin](https://github.com/aws-cloudformation/cloudformation-cli-python-plugin/) | [cloudformation-cli-python-plugin](https://pypi.org/project/cloudformation-cli-python-plugin/) |
| TypeScript| Available | [cloudformation-cli-typescript-plugin](https://github.com/aws-cloudformation/cloudformation-cli-typescript-plugin/) | [cloudformation-cli-typescript-plugin](https://pypi.org/project/cloudformation-cli-typescript-plugin/) |
#### Hook Types Supported Plugins
| Language | Status | Github | PyPI |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Java | Available | [cloudformation-cli-java-plugin](https://github.com/aws-cloudformation/cloudformation-cli-java-plugin/) | [cloudformation-cli-java-plugin](https://pypi.org/project/cloudformation-cli-java-plugin/) |
| Python | Available | [cloudformation-cli-python-plugin](https://github.com/aws-cloudformation/cloudformation-cli-python-plugin/) | [cloudformation-cli-python-plugin](https://pypi.org/project/cloudformation-cli-python-plugin/) |
## License
This library is licensed under the Apache 2.0 License.
## Community
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:
[](https://discord.gg/9zpd7TTRwq)
Raw data
{
"_id": null,
"home_page": "https://github.com/aws-cloudformation/aws-cloudformation-rpdk/",
"name": "cloudformation-cli",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "Amazon Web Services AWS CloudFormation",
"author": "Amazon Web Services",
"author_email": "aws-cloudformation-developers@amazon.com",
"download_url": "https://files.pythonhosted.org/packages/a3/e0/78dd797afac3715d25151be5ad7aa54c24e0bcb3110b3b20f6192d43cf08/cloudformation-cli-0.2.36.tar.gz",
"platform": null,
"description": "[](https://github.com/aws-cloudformation/cloudformation-cli/actions/workflows/pr-ci.yaml)\n\n# AWS CloudFormation CLI\n\nThe CloudFormation CLI (cfn) allows you to author your own resource providers, hooks, and modules that can be used by CloudFormation.\n\n## Usage\n\n### Documentation\n\nPrimary documentation for the CloudFormation CLI can be found at the [AWS Documentation](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/what-is-cloudformation-cli.html) site.\n\n### Installation\n\nThis tool can be installed using [pip](https://pypi.org/project/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:\n\n```bash\npip install cloudformation-cli cloudformation-cli-java-plugin cloudformation-cli-go-plugin cloudformation-cli-python-plugin cloudformation-cli-typescript-plugin\n```\n\n\n### Command: init\n\nTo create a project in the current directory, use the `init` command. A wizard will guide you through the creation.\n\n```bash\ncfn init\n```\n\n### Command: generate\n\nTo 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.\nIn a module project, this will regenerate the module schema.\n\n```bash\ncfn generate\n```\n\n### Command: submit\n\nTo register a resource provider, module, or hook in your account, use the `submit` command.\n\n```bash\ncfn submit\ncfn submit --dry-run #prepares schema handler package without submitting for registration\ncfn submit --set-default # if successfully registered, set submitted version to be the new default version\n```\n\n### Command: package\n\nThis is to create a schema handler package without submitting equivalent to `cfn submit --dry-run`\n\n```bash\ncfn package\n```\n\n### Command: test\n\nTo run the contract tests for a resource type, use the `test` command.\n\n```bash\ncfn test\ncfn test -- -k contract_delete_update # to run a single test\ncfn test -- --tb=long # exhaustive, informative traceback formatting\ncfn test --enforce-timeout 60 # Read/List handler timeout (Create/Update/Delete handler timeout is twice the Read/List handler timeout)\ncfn test --enforce-timeout 60 -- -k contract_delete_update # combine arguments\ncfn 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\n```\n\nNote:\n* 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\n * `--typeconfig ./myResourceTypeConfig.json`\n * `--typeconfig /test/myresource/config1.json`\n * `--typeconfig C:\\MyResource\\typeconf.json`\n\n* To use `propertyTransform` in schema, you will need to install [PYJQ](https://pypi.org/project/pyjq/). This feature will not be available to use with contract tests on Windows OS\n\nInstall PYJQ for Linux system\n\n```bash\nyum install autoconf automake libtool\npip install pyjq\n```\n\nInstall PYJQ for macOS system\n\n```bash\nbrew install autoconf automake libtool\nbrew install jq\npip install pyjq\n```\n\nInstall PYJQ for Ubuntu system\n\n```bash\npip install pyjq\n```\n\n### Command: validate\n\nTo validate the schema, use the `validate` command.\n\nThis 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`](https://github.com/aws-cloudformation/cfn-python-lint/) (but resulting warnings will not cause this step to fail).\n\n```bash\ncfn validate\n```\n\n### Command: build-image\n\nTo 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.\n\n```bash\ncfn build-image\ncfn build-image --image-name my-handler --executable target/myjar.jar\n```\n\nThe resulting image can be run in a container by executing the following command:\n\n```\ndocker run IMAGE_NAME HANDLER_ENTRYPOINT PAYLOAD\ndocker run my-test-resource com.my.test.resource.ExecutableHandlerWrapper PAYLOAD_JSON # Example for a java based-project\n```\n\n\n## Development\n\nFor 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.)\n\n```bash\npython3 -m venv env\nsource env/bin/activate\npip install -e . -r requirements.txt\npre-commit install\n```\n\nIf you're creating a resource or hook type, you will also need to install a language plugin, such as [the Java language plugin](https://github.com/aws-cloudformation/cloudformation-cli-java-plugin), also via `pip install`. For example, assuming the plugin is checked out in the same parent directory as this repository:\n\n```bash\npip install -e ../cloudformation-cli-java-plugin\n```\n\n```bash\n# run all hooks on all files, mirrors what the CI runs\npre-commit run --all-files\n# run unit tests only. can also be used for other hooks, e.g. black, flake8, pylint-local\npre-commit run pytest-local\n```\n\nIf you want to generate an HTML coverage report afterwards, run `coverage html`. The report is output to `htmlcov/index.html`.\n\n## Plugin system\n\nNew 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:\n\n```python\nentry_points={\n \"rpdk.v1.languages\": [\"groovy = rpdk.groovy:GroovyLanguagePlugin\"],\n},\n```\n\nPlugins 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.\n\n### Supported plugins\n\n#### Resource Types Supported Plugins\n| Language | Status | Github | PyPI |\n| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| Java | Available | [cloudformation-cli-java-plugin](https://github.com/aws-cloudformation/cloudformation-cli-java-plugin/) | [cloudformation-cli-java-plugin](https://pypi.org/project/cloudformation-cli-java-plugin/) |\n| Go | Available | [cloudformation-cli-go-plugin](https://github.com/aws-cloudformation/cloudformation-cli-go-plugin/) | [cloudformation-cli-go-plugin](https://pypi.org/project/cloudformation-cli-go-plugin/) |\n| Python | Available | [cloudformation-cli-python-plugin](https://github.com/aws-cloudformation/cloudformation-cli-python-plugin/) | [cloudformation-cli-python-plugin](https://pypi.org/project/cloudformation-cli-python-plugin/) |\n| TypeScript| Available | [cloudformation-cli-typescript-plugin](https://github.com/aws-cloudformation/cloudformation-cli-typescript-plugin/) | [cloudformation-cli-typescript-plugin](https://pypi.org/project/cloudformation-cli-typescript-plugin/) |\n\n#### Hook Types Supported Plugins\n| Language | Status | Github | PyPI |\n| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| Java | Available | [cloudformation-cli-java-plugin](https://github.com/aws-cloudformation/cloudformation-cli-java-plugin/) | [cloudformation-cli-java-plugin](https://pypi.org/project/cloudformation-cli-java-plugin/) |\n| Python | Available | [cloudformation-cli-python-plugin](https://github.com/aws-cloudformation/cloudformation-cli-python-plugin/) | [cloudformation-cli-python-plugin](https://pypi.org/project/cloudformation-cli-python-plugin/) |\n\n## License\n\nThis library is licensed under the Apache 2.0 License.\n\n## Community\n\nJoin us on Discord! Connect & interact with CloudFormation developers &\nexperts, find channels to discuss and get help for our CLI, cfn-lint, CloudFormation registry, StackSets,\nGuard and more:\n\n[](https://discord.gg/9zpd7TTRwq)\n\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "",
"version": "0.2.36",
"project_urls": {
"Homepage": "https://github.com/aws-cloudformation/aws-cloudformation-rpdk/"
},
"split_keywords": [
"amazon",
"web",
"services",
"aws",
"cloudformation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50ebeacf44c57a6bdcafff1f826fbd40339499a3f648ad4ab118b85c81683991",
"md5": "481e04b78a4e30a3121a18ca4b642644",
"sha256": "b0f5a8464e3338ce51631e345e19aed71a5074488872e4847c1d31823942b70b"
},
"downloads": -1,
"filename": "cloudformation_cli-0.2.36-py3-none-any.whl",
"has_sig": false,
"md5_digest": "481e04b78a4e30a3121a18ca4b642644",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 134998,
"upload_time": "2024-03-19T21:48:29",
"upload_time_iso_8601": "2024-03-19T21:48:29.864674Z",
"url": "https://files.pythonhosted.org/packages/50/eb/eacf44c57a6bdcafff1f826fbd40339499a3f648ad4ab118b85c81683991/cloudformation_cli-0.2.36-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a3e078dd797afac3715d25151be5ad7aa54c24e0bcb3110b3b20f6192d43cf08",
"md5": "146dfdd0596ed6ed22fcf5d577951328",
"sha256": "8b5fd65f7ce4ddc8c89b440921c8c0749612ef0c88710f17d44d675f5728f88a"
},
"downloads": -1,
"filename": "cloudformation-cli-0.2.36.tar.gz",
"has_sig": false,
"md5_digest": "146dfdd0596ed6ed22fcf5d577951328",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 103072,
"upload_time": "2024-03-19T21:48:32",
"upload_time_iso_8601": "2024-03-19T21:48:32.339416Z",
"url": "https://files.pythonhosted.org/packages/a3/e0/78dd797afac3715d25151be5ad7aa54c24e0bcb3110b3b20f6192d43cf08/cloudformation-cli-0.2.36.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-19 21:48:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws-cloudformation",
"github_project": "aws-cloudformation-rpdk",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "ipython",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "ipdb",
"specs": [
[
">=",
"0.13"
]
]
},
{
"name": "pylint",
"specs": [
[
"==",
"3.0.1"
]
]
},
{
"name": "coverage",
"specs": [
[
">=",
"7.3.2"
]
]
},
{
"name": "pytest",
"specs": [
[
"<",
"8.0.0"
],
[
">=",
"7.4.2"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.1.0"
]
]
},
{
"name": "pytest-random-order",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "hypothesis",
"specs": [
[
">=",
"6.87.1"
]
]
},
{
"name": "pytest-localserver",
"specs": [
[
">=",
"0.8.0"
]
]
},
{
"name": "pre-commit",
"specs": [
[
">=",
"3.4.0"
]
]
},
{
"name": "twine",
"specs": [
[
">=",
"4.0.2"
]
]
}
],
"lcname": "cloudformation-cli"
}
JSON
