# AWS CloudFormation CLI Hooks Extension
The CloudFormation CLI (cfn) allows you to author your own CFN extension providers that can be used by CloudFormation.
This extension library provides more commands for managing and configuring your Resource Hooks.
### 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
If you are using this package to build hook providers for CloudFormation, install the [CloudFormation CLI Hooks Extension](https://github.com/aws-cloudformation/cloudformation-cli-hooks-extension) - this will automatically install the the [CloudFormation CLI](https://github.com/aws-cloudformation/cloudformation-cli)! A Python virtual environment is recommended.
```shell
pip3 install cloudformation-cli-hooks-extension
```
### Usage
All of these commands are meant to be run from inside your pre-initialized Hooks project directory. You can initialize a new project by using the `cfn init` command from the [CloudFormation CLI](https://github.com/aws-cloudformation/cloudformation-cli?tab=readme-ov-file#command-init). All of the commands use the `cfn hook` prefix, ex. `cfn hook describe`.
#### Command: describe
To get more details about hook versions registered in your account, use the `describe` command. This will return the following properties:
- Description
- Created at
- Last updated at
- Default version
- Failure mode
- Target stacks
- Stack filters (if any)
- Configured properties
- Target types
- Testing status
The details for the default version will be returned by default. Optionally, the `--version-id` can be passed to describe a specific version.
```bash
cfn hook describe
```
Sample output:
```
No version specified, using default version
Selected AWS::CloudFormation::SampleHook version 00000001
Description: Example hook
Version 00000001 Created at: 2023-09-28 04:44:14.402000+00:00
Version 00000001 Last updated at: 2023-09-28 04:44:14.402000+00:00
Current configuration (only applies to default version):
Default version: 00000001
Configured behavior:
Failure mode: WARN
Target stacks: ALL
Stack Filters:
Filtering Criteria: ANY
StackNames:
Include: ['stack-name-0', 'stack-name-1', 'stack-name-2']
Exclude: ['stack-name-3', 'stack-name-4', 'stack-name-5']
StackRoles:
Exclude: ['arn:aws:iam::000000000000:role/stack-role-0', 'arn:aws:iam::000000000000:role/stack-role-1', 'arn:aws:iam::000000000000:role/stack-role-2']
No configured properties.
This Hook is configured to target:
preCreate:
AWS::S3::Bucket
Testing status: NOT_TESTED
Warning: This Type version hasn't been tested yet. Run TestType to test it.
```
### Command: set-default-version
To set a specific version of your hooks as the default version, use the `set-default-version` command.
```bash
cfn hook set-default-version --version-id 1
```
This command return nothings, but you can then use `cfn hook describe` to check the default version set in your account.
### Command: configure
To set the type configuration of your hook, use the `configure` command.
You will first need to save your type configuration as a json file and then specify the file path in the command.
```bash
cfn hook configure --configuration-path ./myHookTypeConfig.json
```
Sample output:
```
ConfigurationArn: arn:aws:cloudformation:us-east-1:000000000000:type-configuration/hook/AWS-CloudFormation-SampleHook/default
```
## Experimental Commands
To enable experimental commands: you will need to set the environment variable `CFN_CLI_HOOKS_EXPERIMENTAL` to `enabled`. Example for the Bash shell: `export CFN_CLI_HOOKS_EXPERIMENTAL=enabled`.
### Command: enable-lambda-function-invoker
To activate and set the type configuration of the `AWSSamples::LambdaFunctionInvoker::Hook`third-party [hook](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/lambda-function-invoker) in your AWS account, use the `enable-lambda-function-invoker` command.
This hook will use the IAM role that you pass to `--execution-role-arn` to invoke the Lambda function that you pass to the `--lambda-function-arn` argument. Make sure the Lambda function is in the same region as the hook that you're activating; the Lambda function can also be in another account (but still, it needs to be in the same region as the hook). Ensure that the execution role IAM policy and the Lambda resource policy have been configured accordingly.
Optionally, `--failure-mode`, `--alias`, and `--include-targets` can all be specified with the following behavior:
- `--failure-mode` changes the failure mode to either `FAIL` or `WARN` (Default is `FAIL`).
- `--alias` changes the type name for this hook in your account. For example, this can be used to change `AWSSamples::LambdaFunctionInvoker::Hook` to `MyCompany::MyOrganization::S3BucketCheckHook`.
- `--include-targets` filters the targets (resource types) for which this hook will be invoked. This can be passed as a comma-separated string (for example, `--include-targets "AWS::S3::*,AWS::DynamoDB::Table"`) (Default is ALL resource types).
Note: Unlike the others, you do not need to run this command from inside an existing Hooks project directory.
See the following example of how to run the `enable-lambda-function-invoker` command; note that the `--region` argument needs to be passed here if the default region configured in your AWS CLI is **not** set to `us-east-2` (the same region in which the Lambda function exists).
```bash
cfn hook enable-lambda-function-invoker \
--lambda-function-arn arn:aws:lambda:us-east-2:123456789012:function:my-function:1 \
--execution-role-arn arn:aws:iam::123456789012:role/ExampleRole
```
Sample output:
```
Success: AWSSamples::LambdaFunctionInvoker::Hook will now be invoked for CloudFormation deployments for ALL resources in FAIL mode.
```
## 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
pip3 install -e /path/to/cloudformation-cli-hooks-extension
```
Install `pytest-cov`, used when running unit tests for this plugin:
```shell
pip3 install pytest-cov
```
You may also want to check out the [CloudFormation CLI](https://github.com/aws-cloudformation/cloudformation-cli) if you wish to make edits to that. In this case, installing them in one operation works well:
```shell
pip3 install \
-e /path/to/cloudformation-cli \
-e /path/to/cloudformation-cli-hooks-extension
```
That ensures neither is accidentally installed from PyPI.
## Security
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
## License
This project is licensed under the Apache-2.0 License.
Raw data
{
"_id": null,
"home_page": "https://github.com/aws-cloudformation/cloudformation-cli-hooks-extension",
"name": "cloudformation-cli-hooks-extension",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "Amazon Web Services AWS CloudFormation",
"author": "Amazon Web Services",
"author_email": "aws-cloudformation-developers@amazon.com",
"download_url": "https://files.pythonhosted.org/packages/f5/ea/0d78214212e9d140d19b3551f90c465f9dd6db43a50c3fcc73acc2adf549/cloudformation-cli-hooks-extension-0.2.0.tar.gz",
"platform": null,
"description": "# AWS CloudFormation CLI Hooks Extension\n\nThe CloudFormation CLI (cfn) allows you to author your own CFN extension providers that can be used by CloudFormation.\n\nThis extension library provides more commands for managing and configuring your Resource Hooks.\n\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\nIf you are using this package to build hook providers for CloudFormation, install the [CloudFormation CLI Hooks Extension](https://github.com/aws-cloudformation/cloudformation-cli-hooks-extension) - this will automatically install the the [CloudFormation CLI](https://github.com/aws-cloudformation/cloudformation-cli)! A Python virtual environment is recommended.\n\n```shell\npip3 install cloudformation-cli-hooks-extension\n```\n\n### Usage\n\nAll of these commands are meant to be run from inside your pre-initialized Hooks project directory. You can initialize a new project by using the `cfn init` command from the [CloudFormation CLI](https://github.com/aws-cloudformation/cloudformation-cli?tab=readme-ov-file#command-init). All of the commands use the `cfn hook` prefix, ex. `cfn hook describe`.\n\n#### Command: describe\n\nTo get more details about hook versions registered in your account, use the `describe` command. This will return the following properties:\n\n- Description\n- Created at\n- Last updated at\n- Default version\n- Failure mode\n- Target stacks\n- Stack filters (if any)\n- Configured properties\n- Target types\n- Testing status\n\nThe details for the default version will be returned by default. Optionally, the `--version-id` can be passed to describe a specific version.\n\n```bash\ncfn hook describe\n```\n\nSample output:\n\n```\nNo version specified, using default version\n\nSelected AWS::CloudFormation::SampleHook version 00000001\n\nDescription: Example hook\nVersion 00000001 Created at: 2023-09-28 04:44:14.402000+00:00\nVersion 00000001 Last updated at: 2023-09-28 04:44:14.402000+00:00\n\nCurrent configuration (only applies to default version):\n Default version: 00000001\n Configured behavior:\n Failure mode: WARN\n Target stacks: ALL\n Stack Filters:\n Filtering Criteria: ANY\n StackNames:\n Include: ['stack-name-0', 'stack-name-1', 'stack-name-2']\n Exclude: ['stack-name-3', 'stack-name-4', 'stack-name-5']\n StackRoles:\n Exclude: ['arn:aws:iam::000000000000:role/stack-role-0', 'arn:aws:iam::000000000000:role/stack-role-1', 'arn:aws:iam::000000000000:role/stack-role-2']\n\n No configured properties.\n\nThis Hook is configured to target:\n preCreate:\n AWS::S3::Bucket\n\nTesting status: NOT_TESTED\n Warning: This Type version hasn't been tested yet. Run TestType to test it.\n```\n\n### Command: set-default-version\n\nTo set a specific version of your hooks as the default version, use the `set-default-version` command.\n\n```bash\ncfn hook set-default-version --version-id 1\n```\n\nThis command return nothings, but you can then use `cfn hook describe` to check the default version set in your account.\n\n### Command: configure\n\nTo set the type configuration of your hook, use the `configure` command.\n\nYou will first need to save your type configuration as a json file and then specify the file path in the command.\n\n\n```bash\ncfn hook configure --configuration-path ./myHookTypeConfig.json\n```\n\nSample output:\n\n```\nConfigurationArn: arn:aws:cloudformation:us-east-1:000000000000:type-configuration/hook/AWS-CloudFormation-SampleHook/default\n```\n\n## Experimental Commands\n\nTo enable experimental commands: you will need to set the environment variable `CFN_CLI_HOOKS_EXPERIMENTAL` to `enabled`. Example for the Bash shell: `export CFN_CLI_HOOKS_EXPERIMENTAL=enabled`.\n\n### Command: enable-lambda-function-invoker\n\nTo activate and set the type configuration of the `AWSSamples::LambdaFunctionInvoker::Hook`third-party [hook](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/lambda-function-invoker) in your AWS account, use the `enable-lambda-function-invoker` command.\n\nThis hook will use the IAM role that you pass to `--execution-role-arn` to invoke the Lambda function that you pass to the `--lambda-function-arn` argument. Make sure the Lambda function is in the same region as the hook that you're activating; the Lambda function can also be in another account (but still, it needs to be in the same region as the hook). Ensure that the execution role IAM policy and the Lambda resource policy have been configured accordingly.\n\nOptionally, `--failure-mode`, `--alias`, and `--include-targets` can all be specified with the following behavior:\n\n- `--failure-mode` changes the failure mode to either `FAIL` or `WARN` (Default is `FAIL`).\n- `--alias` changes the type name for this hook in your account. For example, this can be used to change `AWSSamples::LambdaFunctionInvoker::Hook` to `MyCompany::MyOrganization::S3BucketCheckHook`.\n- `--include-targets` filters the targets (resource types) for which this hook will be invoked. This can be passed as a comma-separated string (for example, `--include-targets \"AWS::S3::*,AWS::DynamoDB::Table\"`) (Default is ALL resource types).\n\nNote: Unlike the others, you do not need to run this command from inside an existing Hooks project directory.\n\nSee the following example of how to run the `enable-lambda-function-invoker` command; note that the `--region` argument needs to be passed here if the default region configured in your AWS CLI is **not** set to `us-east-2` (the same region in which the Lambda function exists).\n\n```bash\ncfn hook enable-lambda-function-invoker \\\n--lambda-function-arn arn:aws:lambda:us-east-2:123456789012:function:my-function:1 \\\n--execution-role-arn arn:aws:iam::123456789012:role/ExampleRole\n```\n\nSample output:\n```\nSuccess: AWSSamples::LambdaFunctionInvoker::Hook will now be invoked for CloudFormation deployments for ALL resources in FAIL mode.\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\npip3 install -e /path/to/cloudformation-cli-hooks-extension\n```\n\nInstall `pytest-cov`, used when running unit tests for this plugin:\n\n```shell\npip3 install pytest-cov\n```\n\nYou may also want to check out the [CloudFormation CLI](https://github.com/aws-cloudformation/cloudformation-cli) if you wish to make edits to that. In this case, installing them in one operation works well:\n\n```shell\npip3 install \\\n -e /path/to/cloudformation-cli \\\n -e /path/to/cloudformation-cli-hooks-extension\n```\n\nThat ensures neither is accidentally installed from PyPI.\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Hook extension for the CloudFormation CLI",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/aws-cloudformation/cloudformation-cli-hooks-extension"
},
"split_keywords": [
"amazon",
"web",
"services",
"aws",
"cloudformation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cc2b84f56a61bae8ba105f844e641203baca7f9634d82bf2eed147dab6d23439",
"md5": "d6f9748417f905506798c8da5a9c6eda",
"sha256": "d3d5ae4fba972598383acbb0fbadbbac8977fabbce12d0f8d307f64bfd3acce8"
},
"downloads": -1,
"filename": "cloudformation_cli_hooks_extension-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d6f9748417f905506798c8da5a9c6eda",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 19336,
"upload_time": "2024-03-21T14:30:47",
"upload_time_iso_8601": "2024-03-21T14:30:47.796251Z",
"url": "https://files.pythonhosted.org/packages/cc/2b/84f56a61bae8ba105f844e641203baca7f9634d82bf2eed147dab6d23439/cloudformation_cli_hooks_extension-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f5ea0d78214212e9d140d19b3551f90c465f9dd6db43a50c3fcc73acc2adf549",
"md5": "a052dfd7f1fef42605121b2da89ebac7",
"sha256": "39e27ce3419a4ce3c9e78e865cf7cbf23214376bfbe682a170169c89b33cfe5f"
},
"downloads": -1,
"filename": "cloudformation-cli-hooks-extension-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "a052dfd7f1fef42605121b2da89ebac7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15480,
"upload_time": "2024-03-21T14:30:49",
"upload_time_iso_8601": "2024-03-21T14:30:49.613738Z",
"url": "https://files.pythonhosted.org/packages/f5/ea/0d78214212e9d140d19b3551f90c465f9dd6db43a50c3fcc73acc2adf549/cloudformation-cli-hooks-extension-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-21 14:30:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws-cloudformation",
"github_project": "cloudformation-cli-hooks-extension",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cloudformation-cli-hooks-extension"
}
JSON
