What is the CloudFormation Command Line Interface (CFN-CLI)? - Extension Development for CloudFormation
Set up your environment for extension development and install the CLI

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 AWS and third-party extensions, such as resource types or modules, and register them for use in AWS CloudFormation. The CloudFormation CLI provides a consistent way to model and provision both AWS 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 AWS, AWS Partner Network, AWS 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 AWS 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

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

  1. Install Homebrew, an open-source package manager for macOS. You'll use Homebrew to install additional development requirements.

  2. 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.

Available Language Plugins

Language

Plugin status

GitHub location

PyPI installation

Go

General availability

cloudformation-cli-go-plugin

pip install cloudformation-cli-go-plugin

Java

General availability

cloudformation-cli-java-plugin

pip install cloudformation-cli-java-plugin

Python

General availability

cloudformation-cli-python-plugin

pip install cloudformation-cli-python-plugin

TypeScript

General availability

cloudformation-cli-typescript-plugin

pip install cloudformation-cli-typescript-plugin

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

  1. Upgrade the Go Plugin using the following command:

    $ pip3 install --upgrade cloudformation-cli-go-plugin

  2. Update the Go plugin in the go.mod file.

    $ go get -u github.com/aws-cloudformation/cloudformation-cli-go-plugin

  3. 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

  1. Upgrade the Java Plugin using the following command:

    $ pip3 install --upgrade cloudformation-cli-java-plugin

  2. 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>

  3. 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

  1. Upgrade the Python Plugin using the following command:

    $ pip3 install cloudformation-cli-python-plugin

  2. 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