|« PreviousNext »|
|Did this page help you? Yes | No | Tell us about it...|
This guide is based on Mac OS X Lion (10.7.4). Other versions of Mac OS X may require adjustments to these instructions.
The CloudFormation CLI tools must be installed on Mac OS X version 10.4 (Leopard) or greater, as Java runtime 1.5 is not supported on earlier versions of Mac OS X.
The Java Runtime Environment is installed automatically on Mac OS X, so you don't need to install it yourself. However, you can check it by opening a terminal window and typing:
If you're on Mac OS X 1.4 or greater, this should report a Java version of at least 1.5.
Before setting anything up on your system, you'll need to download the AWS CloudFormation CLI tools. To download them, go to the AWS CloudFormation Command Line Tools page, and then click Download.
The downloaded file is named
You can install the CLI Tools in any directory you choose, though for simplicity, it's good to install them
in a location within your home directory (/Users/name, where name is
your Mac OS X user name). Once you begin using CloudFormation, you'll likely want to install command-line tools
for other AWS services, so we'll install the CloudFormation CLI tools within a directory designed to house all
of these toolsets, called
A directory with an initial period (.) will be hidden by default to the file manager and to the
ls command. We hide the directory so that it won't clutter the view of your home directory. If you
don't want it hidden, name it simply
awstools or anything else you choose. It won't affect how
the tools work as long as you consistently substitute your chosen location for the
directory that we'll use throughout this guide.
To prepare the install location
Open a Terminal window by doing one of the following:
Open the Launchpad (on Mac OS X Lion), open the Utilities folder, and click Terminal.
Open Finder, navigate to Applications / Utilities, and double-click Terminal.
In your terminal window, create the installation directory by typing:
$ mkdir ~/.awstools
This will create a hidden directory (if it doesn't already exist) called ".awstools" in your home directory.
You can use
~/.awstools as the base directory for all AWS toolsets you want to install.
Here, we'll just concern ourselves with installing the CloudFormation CLI tools.
To install the CLI tools
Change your working directory to ~/.awstools. You can do this on the command-line with:
$ cd ~/.awstools
Unzip the downloaded AWSCloudFormation-cli.zip file in the install location, by typing:
$ unzip ~/Downloads/AWSCloudFormation-cli.zip
This will create a directory called AWSCloudFormation-#.#.#, where each # represents part of the version number.
(Optional) Link to the install directory, by typing:
$ ln -s AWSCloudFormation-#.#.# cfn
Again, the three # characters represent part of the version number, so to make the link to version 1.0.11 of the tools, type:
$ ln -s AWSCloudFormation-1.0.11 cfn
This enables you to easily install and switch to a new version of the tools, while allowing you to switch back to an older version just as easily. Simply overwrite the link with a new one.
Within the install directory (which can be accessed by typing
cd ~/.awstools/cfn on the
command-line prompt if you followed the optional step for installing the CLI tools) you will find a file named
credential-file-path.template. This file can be used to supply your AWS credentials to
the tools automatically so you won't need to pass these credentials to the tools on the command-line every time
you run them.
Adding your credentials to this file can save you time, but can also present a security risk if your system is used by others, since your security key will be stored as plain text on your system.
If you don't have your AWS credentials handy, you can view them by logging into the AWS console and selecting Security Credentials from the My Account / Console menu at the top of the screen. On the page, click Access Credentials to see your access key under the Access Key ID heading. Your secret key can also be viewed here by clicking the show button under the Secret Access Key heading.
Do not share your secret access key with anyone! With your secret access key, anyone would be able to use AWS services and charge usage fees to your account.
If you don't want to keep your credentials in a file on your system, you can skip the next procedure, and
instead pass your credentials directly to the AWS CloudFormation CLI tools with the
--S SECRETKEY arguments, replacing
ACCESSKEY and SECRETKEY with your AWS credentials. You will need
to do this every time you use the CLI tools.
To add your AWS credentials to the AWS credential file
Go to the AWS CloudFormation CLI tools install directory from the command-line, using:
$ cd ~/.awstools/cfn
This assumes that you installed the CLI tools into
~/.awstools and either linked or
renamed the AWSCloudFormation-#.#.# directory to
~/.awstools/cfn. If you did not,
replace this location in the example above with the pathname to the location where you installed the CLI
Copy or rename the credential-file-path.template file to a filename of your choosing (you can even use credential-file-path.template as the filename, but I prefer something that better describes its purpose). For the purposes of this article, we'll use "myAWSCredentials.txt":
$ cp credential-file-path.template myAWSCredentials.txt
Edit the file with your favorite text editor, enter your AWS credentials, then save and close the file. The file should contain two lines in it, like this:
Note: These are example values, and won't work for an actual connection to AWS. Instead, use your own AWS security credentials here.
Finally, you'll need to add a few environment variables to your system. Since you'll be using the
CloudFormation CLI tools from the command-line, you can simply add these to your
To add the CloudFormation CLI tools environment variables:
~/.profile in your favorite editor. If it does not exist yet, create it.
~/.profile, add the following lines:
# CloudFormation CLI tools setup export JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Home/" export AWS_CLOUDFORMATION_HOME="$HOME/.awstools/cfn" export AWS_CREDENTIAL_FILE="$AWS_CLOUDFORMATION_HOME/myAWSCredentials.txt" export PATH="$PATH:$AWS_CLOUDFORMATION_HOME/bin"
This assumes that you installed the CLI tools into
~/.awstools and have either
linked or renamed the AWSCloudFormation-#.#.# directory to
~/.awstools/cfn. If you did
not, replace this location (where $HOME represents "~") with the pathname to the location where
you installed the CLI tools.
If you did not add your AWS access keys to an external file (such as the
myAWSCredentials.txt file specified above), you should not
AWS_CREDENTIAL_FILE environment variable. Instead, remove or comment-out
To load your environment variables, either quit and restart Terminal or, at the command-line prompt, type:
$ source ~/.profile
Test your installation by running cfn-cmd:
This will list all of the available CloudFormation CLI tools, their usage, and the available options
cfn-cmd itself (there are two options: