AWS CloudFormation
User Guide (API Version 2010-05-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Get Started

With the right template, you can deploy at once all the AWS resources you need for an application. In this section, you'll examine a template that declares the resources for a WordPress blog, creates a WordPress blog as a stack, monitors the stack creation process, examines the resources on the stack, and then deletes the stack. You use the AWS Management Console to complete these tasks.

Step 1: Sign up for the Service

Signing up for AWS CloudFormation also automatically signs you up for other AWS products you need, such as Amazon Elastic Compute Cloud, Amazon Relational Database Service and Amazon Simple Notification Service. You're not charged for any services unless you use them.

Note

AWS CloudFormation is a free service; however, you are charged for the AWS resources you include in your stacks at the current rates for each. For more information about AWS pricing, go to the detail page for each product on http://aws.amazon.com.

To sign up for AWS CloudFormation

  1. Go to http://aws.amazon.com/cloudformation, and then click Sign Up for AWS CloudFormation.

  2. Follow the on-screen instructions.

If you don't already have an AWS account, you'll be prompted to create one when you sign up for AWS CloudFormation.

Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad.

Step 2: Pick a template

Next, you'll need a template that specifies the resources you want in your stack. For this step, you use a sample template that is already prepared. The sample template creates a basic WordPress blog using a single Amazon EC2 instance and an Amazon RDS DB Instance. The template also creates an Amazon EC2 and Amazon RDS security group to control firewall settings for the Amazon EC2 instance and the DB Instance.

Important

AWS CloudFormation is free, but the AWS resources that AWS CloudFormation creates will be live (and not running in a sandbox). You will incur the standard usage fees for these resources until you terminate them in the last task in this tutorial. The total charges will be minimal. For information about how you might minimize any charges, go to http://aws.amazon.com/free/.

To view the template

A template is a JavaScript Object Notation (JSON) text file containing the configuration information about the AWS resources you want to create in the stack. If you look through the example WordPress template, you will see six top-level objects: AWSTemplateFormatVersion, Description, Parameters, Mappings, Resources, and Outputs; however, only the Resources object is required.

The Resources object contains the definitions of the AWS resources you want to create with the template. Each resource is listed separately and specifies the properties necessary for creating that particular resource. The following resource declaration in the template contains the configuration for the Amazon RDS DB Instance, which in this example has the logical name DBInstance:

"Resources" : {
  ...    
  "DBInstance" : {
    "Type": "AWS::RDS::DBInstance",
    "Properties": {
      "DBName"            : { "Ref" : "DBName" },
      "Engine"            : "MySQL",
      "MasterUsername"    : { "Ref" : "DBUsername" },
      "DBInstanceClass"   : { "Ref" : "DBClass" },
      "DBSecurityGroups"  : [{ "Ref" : "DBSecurityGroup" }],
      "AllocatedStorage"  : { "Ref" : "DBAllocatedStorage" },
      "MasterUserPassword": { "Ref" : "DBPassword" }
    }
  },
    
  "DBSecurityGroup": {
    "Type": "AWS::RDS::DBSecurityGroup",
    "Properties": {
      "DBSecurityGroupIngress": { "EC2SecurityGroupName": { "Ref": "WebServerSecurityGroup"} },
      "GroupDescription"      : "Frontend Access"
    }        
  },
  ...    
},

If you have created DB Instances before, you'll recognize properties, such as Engine, DBInstanceClass, and AllocatedStorage, that determine the configuration of the DB Instance. Resource declarations are an efficient way to specify all these configuration settings at once. When you put resource declarations in a template, you can create and configure all the declared resources easily by using the template to create a stack. To launch the same configuration of resources, all you have to do is use the same template to create a new stack.

The resource declaration begins with a string that specifies the logical name for the resource. As you'll see, the logical name can be used to refer to resources within the template.

You use the Parameters object to declare values that can be passed to the template when you create the stack. A parameter is an effective way to specify sensitive information, such as user names and passwords, that you don't want to store in the template itself. It is also a way to specify information that may be unique to the specific application or configuration you are deploying, for example, a domain name or instance type. When you create the WordPress stack later in this section, you'll see the set of parameters declared in the template appear on the Specify Parameters page of the Create Stack wizard, where you can specify the parameters just before creating the stack.

The following parameters are used in the template to specify values used in properties in the Amazon RDS DB Instance resource:

"Parameters" : {
  ...      
  "DBName" : {
    "Default": "wordpress",
    "Description" : "The WordPress database name",
    "Type": "String",
    "MinLength": "1",
    "MaxLength": "64",
    "AllowedPattern" : "[a-zA-Z][a-zA-Z0-9]*",
    "ConstraintDescription" : "must begin with a letter and contain only alphanumeric characters."
  },
    
  "DBUsername" : {
    "Default": "admin",
    "NoEcho": "true",
    "Description" : "The WordPress database admin account user name",
    "Type": "String",
    "MinLength": "1",
    "MaxLength": "16",
    "AllowedPattern" : "[a-zA-Z][a-zA-Z0-9]*",
    "ConstraintDescription" : "must begin with a letter and contain only alphanumeric characters."
  },
    
  "DBPassword" : {
    "Default": "admin",
    "NoEcho": "true",
    "Description" : "The WordPress database admin account password",
    "Type": "String",
    "MinLength": "1",
    "MaxLength": "41",
    "AllowedPattern" : "[a-zA-Z0-9]*",
    "ConstraintDescription" : "must contain only alphanumeric characters."
  },

  "DBAllocatedStorage" : {
    "Default": "5",
    "Description" : "The size of the database (Gb)",
    "Type": "Number",
    "MinValue": "5",
    "MaxValue": "1024",
    "ConstraintDescription" : "must be between 5 and 1024Gb."
  },
  ...
},

In the DBInstance resource declaration, you see the DBName property specified with the DBName parameter:

  "DBInstance" : {
    "Type": "AWS::RDS::DBInstance",
    "Properties": {
      "DBName" : { "Ref" : "DBName" },
      ...
    }
  },

The braces contain a call to the Ref function with DBName as its input. The Ref function returns the value of the object it refers to. In this case, it's the WordPressDBName parameter, and the Ref function sets the DBName property to the value that was specified for DBName when the stack was created.

The Ref function can also set a resource's property to the value of another resource. For example, the resource declaration DBInstance contains the following property declaration:

"DBInstance" : {
  "Type": "AWS::RDS::DBInstance",
  "Properties": {
    ...
    "DBSecurityGroups"  : [{ "Ref" : "DBSecurityGroup" }],
    ...
  }
},

The DBSecurityGroups property takes a list of Amazon RDS DB Security Groups. The Ref function has an input of DBSecurityGroup, which is the logical name of a DB security group in the template, and adds the name of DBSecurityGroup to the DBSecurityGroups property.

In the template, you'll also find a Mappings object. You use mappings to declare conditional values that are evaluated in a similar manner as a switch statement. The template uses mappings to select the correct Amazon machine image (AMI) for the region and the architecture type for the instance type. Outputs define custom values that are returned by the aws cloudformation describe-stacks command and in the AWS Management Console's Outputs tab after the stack is created. You can use output values to return information from the resources in the stack, such as the URL for a website created in the template. We'll cover mappings, outputs, and other things about templates in more detail in Learn Template Basics.

That's enough about templates for now. Let's start creating a stack.

Step 3: Make sure you have prepared any required items for the stack

Before you create a stack from a template, you must ensure that all dependent resources that the template requires are available. A template can use or refer to both existing AWS resources and resources declared in the template itself. AWS CloudFormation takes care of checking references to resources in the template and also checks references to existing resources to ensure that they exist in the region where you are creating the stack. If your template refers to a dependent resource that does not exist, stack creation will fail.

The example WordPress template contains an input parameter, KeyName, that specifies the key pair used for the EC2 instance that is declared in the template. The template depends on the user who creates a stack from the template to supply a valid key pair for the KeyName parameter. If you supply a valid key pair name, the stack will be created. If you don't supply a valid key pair name, the stack will be rolled back.

Make sure you have a valid EC2 key pair, and make note of the Key Pair Name, before you create the stack.

To see your key pairs, open the Amazon EC2 console, then click Key Pairs in the navigation pane.

Note

If you don't have an EC2 key pair to use, you must create the key pair in the same region where you are creating the stack. For information about creating a key pair, see Getting an SSH Key Pair in the Amazon Elastic Compute Cloud User Guide.

Now that you have a valid key pair, let's use the WordPress template to create a stack.

Step 4: Create the stack

You will create your stack based on the WordPress-1.0.0 file discussed earlier. The template contains several AWS resources including an Amazon Relational Database Service DB Instance and a web server.

To create the WordPress stack

  1. Sign in to the AWS Management Console and open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation/.

  2. If this is a new AWS CloudFormation account, click Create New Stack. Otherwise, click Create Stack.

  3. In the Stack Name box, type a stack name. For this example, use MyWPTestStack. The stack name must not contain spaces.

  4. Select Provide an S3 URL to template. In the box below, type or paste the URL for the sample WordPress template, and then click Continue:

    https://s3.amazonaws.com/cloudformation-templates-us-east-1/WordPress_Single_Instance_With_RDS.template

    Note

    AWS CloudFormation templates that are stored in an Amazon S3 bucket must be accessible to the user who is creating the stack, and must exist in the same region as the stack being created. Therefore, if the Amazon S3 bucket exists in the us-east-1 region, the stack must also be created in us-east-1.

  5. In the KeyName box, enter the name of a valid Amazon EC2 key pair in the same region you are creating the stack.

    Note

    On the Specify Parameters page, you'll recognize the parameters from the Parameters object of the template.

  6. Click Next Step.

  7. In this scenario, we won't add any tags. Click Next Step. Tags, which are key-value pairs, can help you identify your stacks. For more information, see Adding Tags to Your AWS CloudFormation Stack.

  8. Review the information for the stack. When you're satisfied with the settings, click Create.

Your stack might take several minutes to create—but you probably don't want to just sit around waiting. If you're like us, you'll want to know how the stack creation is going.

Step 5: Monitor the progress of stack creation

After you complete the Create Stack wizard, AWS CloudFormation begins creating the resources specified in the template. Your new stack, MyWPTestStack, appears in the list at the top portion of the CloudFormation console. Its status should be CREATE_IN_PROGRESS. You can see detailed status for a stack by viewing its events.

To view the events for the stack

  1. On the AWS CloudFormation console, select the stack MyWPTestStack in the list.

  2. In the pane below the list, click the Events tab.

    The console automatically refreshes the event list with the most recent events every 60 seconds.

The Events tab displays each major step in the creation of the stack sorted by the time of each event, with latest events on top.

The first event (at the bottom of the event list) is the start of the stack creation process:

MyWPTestStack AWS::CloudFormation::Stack CREATE_IN_PROGRESS

Next are events that mark the beginning and completion of the creation of each resource. For example, creation of the DBSecurityGroup security group results in the following entries:

2013-04-24 18:59 UTC-7 | PDT AWS::RDS::DBSecurityGroup ... CREATE_COMPLETE

2013-04-24 18:54 UTC-7 | PDT AWS::RDS::DBSecurityGroup ... CREATE_IN_PROGRESS

The CREATE_IN_PROGRESS event is logged when AWS CloudFormation reports that it has begun to create the resource. The CREATE_COMPLETE event is logged when the resource is successfully created.

When AWS CloudFormation has successfully created the stack, you will see the following event at the top of the Events tab:

MyWPTestStack AWS::CloudFormation::Stack CREATE_COMPLETE

If AWS CloudFormation cannot create a resource, it reports a CREATE_FAILED event and, by default, rolls back the stack. The Reason column displays the issue that caused the failure. For example, if you specified an invalid DB password, you would see something like the following event for the AWS::RDS::DBInstance resource:

2013-04-24 19:01 UTC-7 | AWS::RDS::DBInstance | ... CREATE_FAILED | The parameter MasterUserPassword is not a valid password because it is shorter than 8 characters.

Step 6: Use your stack resources

When the stack MyWPTestStack has a status of CREATE_COMPLETE, AWS CloudFormation has finished creating the stack, and you can start using its resources.

The sample WordPress stack creates a WordPress website. You can continue with the WordPress setup by running the WordPress installation script.

To complete the WordPress installation

  1. On the Outputs tab, in the InstallURL row, click the link in the Value column.

    The InstallURL output value is the URL of the installation script for the WordPress website that you created with the stack.

  2. On the web page for the WordPress installation, follow the on-screen instructions to complete the WordPress installation. For more information about installing WordPress, see http://codex.wordpress.org/Installing_WordPress.

  3. Return to the AWS Management Console. On the Outputs tab, in the WebsiteURL row, in the Value column, click the link.

If the web page for the WordPress blog that you created with this stack appears, you have successfully created a WordPress blog using a AWS CloudFormation template.

Step 8: Clean Up

You have completed the AWS CloudFormation getting started tasks. To make sure you are not charged for any unwanted services, you can clean up by deleting the stack and its resources.

To delete the stack and its resources

  1. On the AWS CloudFormation console, select the MyWPTestStack stack.

  2. Click Delete Stack.

  3. In the confirmation message that appears, click Yes, Delete.

The status for MyWPTestStack changes to DELETE_IN_PROGRESS. In the same way you monitored the creation of the stack, you can monitor its deletion using the Event tab. When AWS CloudFormation completes the deletion of the stack, it removes the stack from the list.

Congratulations! You successfully picked a template, created a stack, viewed and used its resources, and deleted the stack and its resources. Not only that, you were able to set up a WordPress blog using a AWS CloudFormation template. You can find other templates in the AWS CloudFormation Sample Template Library.

Now it's time to learn more about templates so that you can easily modify existing templates or create your own: Learn Template Basics.