What is the CloudFormation Command Line Interface (CFN-CLI)?
The CloudFormation Command Line Interface (CFN-CLI) is an open-source tool that enables you to develop and test Amazon and third-party extensions, such as resource types or modules, and register them for use in Amazon CloudFormation. The CloudFormation CLI provides a consistent way to model and provision both Amazon and third-party extensions through CloudFormation. The CloudFormation CLI includes commands to manage each step of creating your extensions. For more information about CloudFormation CLI commands see, CloudFormation CLI reference.
An extension is an artifact, registered in the CloudFormation registry, which augments the functionality of CloudFormation in a native manner. Extensions are registered by Amazon, Amazon Partner Network, Amazon Web Services Marketplace sellers, and the developer community.
You can use the CloudFormation CLI to register extensions – both those you create yourself, in addition to ones shared with you – with the CloudFormation registry. Extensions enable CloudFormation capabilities to create, provision, and manage these custom types in a safe and repeatable manner, just as you would any Amazon resource. For more information about the CloudFormation registry, see Using the CloudFormation registry in the CloudFormation User Guide.
Set up your environment for extension development and install the CLI
Before you can develop extensions, you'll need to set up your developer environment, including the CloudFormation CLI.
Currently, plugins are available for the following languages:
-
Go
-
Java
-
Python
-
TypeScript
Or, if you're using another language, you can install the CloudFormation CLI directly.
Setting up your environment
Prerequisites
-
Python version 3.6 or above.
-
CloudFormation CLI command reference
for access to aws cloudformation
commands. -
Your choice of IDE.
The Walkthrough: Develop a resource type walkthrough uses the Community Edition of the IntelliJ IDEA
. -
Amazon Serverless Application Model Command Line Interface (Amazon SAM CLI).
Note
Installing the Amazon SAM CLI requires Docker as a prerequisite for testing your resource type locally.
Installing the CloudFormation CLI
The CloudFormation CLI can be installed using pip from the Python Package Index (PyPI)
Resource – Requires at least one language plugin.
Module – Language plugins aren't required.
-
Hook – Requires at least one language plugin.
The language plugins are also available on PyPI. Use the following command to install all the language plugins at once.
$
pip install cloudformation-cli cloudformation-cli-java-plugin cloudformation-cli-go-plugin cloudformation-cli-python-plugin cloudformation-cli-typescript-plugin
(macOS) Installing CloudFormation CLI
Install Homebrew
-
Install Homebrew
, an open-source package manager for macOS. You'll use Homebrew to install additional development requirements. -
Use Homebrew to install Python and the CloudFormation Command Line Interface (CFN-CLI).
$
brew update$
brew install cloudformation-cli
Installing the CloudFormation CLI and plugins
Use the Python Package Index (PyPI) to install the development plugin for the language of your choice. Installing any of the plugins listed below also installs the CloudFormation CLI. For full installation instructions, refer to the appropriate plugin repository.
Language |
Plugin status |
GitHub location |
PyPI installation |
---|---|---|---|
Go |
General availability |
|
|
Java |
General availability |
|
|
Python |
General availability |
|
|
TypeScript |
General availability |
|
Upgrading to CFN-CLI 2.0
If you have developed resource types using the CFN-CLI 1.0, we suggest you update to CFN-CLI 2.0 and rebuild those types. Upgrading involves updating the CloudFormation CLI, in addition to any language plugins you are using, but doesn't require any changes to your resource type solution itself.
Enhancements in CFN-CLI 2.0 include:
-
Increased resource payload limit, from 8 KB to 6 MB.
-
Increased resource stabilization time, from 12 hours to 36 hours, or 48 hours if you are using a stack role to consume the resource.
-
Improved resource stability, with improved retry strategy and fail-fast.
To upgrade CFN-CLI 2.0 and the CloudFormation Provider Development Toolkit Go Plugin
-
Upgrade the Go Plugin using the following command:
$
pip3 install --upgrade cloudformation-cli-go-plugin -
Update the Go plugin in the
go.mod
file.$
go get -u github.com/aws-cloudformation/cloudformation-cli-go-plugin -
To update a resource type to use the CFN-CLI 2.0, build and register a new version of the resource using the following command:
$
make$
cfn submit --set-default
To upgrade CFN-CLI 2.0 and the CloudFormation Provider Development Toolkit Java Plugin
-
Upgrade the Java Plugin using the following command:
$
pip3 install --upgrade cloudformation-cli-java-plugin -
Update Java plugin in maven pom.xml to 2.0.0.
<dependency> <groupId>software.amazon.cloudformation</groupId> <artifactId>aws-cloudformation-rpdk-java-plugin</artifactId> <version>2.0.0</version> </dependency>
-
To update a resource type to use the CFN-CLI 2.0, build and register a new version of the resource using the following command:
$
mvn package$
cfn submit --set-default
To upgrade CFN-CLI 2.0 and the CloudFormation Provider Development Toolkit Python Plugin
-
Upgrade the Python Plugin using the following command:
$
pip3 install cloudformation-cli-python-plugin -
To update a resource type to use the CFN-CLI 2.0, build and register a new version of the resource using the following command:
$
cfn submit --set-default