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 that 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 that uses 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 database instance.

Important

AWS CloudFormation is free, but the AWS resources that AWS CloudFormation creates are 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 that contains the configuration information about the AWS resources you want to create in the stack. In this particular sample template, it includes six top-level sections: AWSTemplateFormatVersion, Description, Parameters, Mappings, Resources, and Outputs; however, only the Resources section is required.

The Resources section contains the definitions of the AWS resources you want to create with the template. Each resource is listed separately and specifies the properties that are necessary for creating that particular resource. The following resource declaration is the configuration for the Amazon RDS database 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 database instances before, you can recognize properties, such as Engine, DBInstanceClass, and AllocatedStorage, that determine the configuration of the database 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 create a new stack that uses the same template.

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 section 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 might 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 before you create the stack.

The following parameters are used in the template to specify values that are used in properties of the Amazon RDS database 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, 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 database security groups. The Ref function has an input of DBSecurityGroup, which is the logical name of a database security group in the template, and adds the name of DBSecurityGroup to the DBSecurityGroups property.

In the template, you'll also find a Mappings section. You use mappings to declare conditional values that are evaluated in a similar manner as a lookup table 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 CloudFormation console 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 that was created in the template. We 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 fails.

The example WordPress template contains an input parameter, KeyName, that specifies the key pair used for the Amazon 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 Amazon EC2 key pair for the KeyName parameter. If you supply a valid key pair name, the stack creates successfully. If you don't supply a valid key pair name, the stack is rolled back.

Make sure you have a valid Amazon EC2 key pair and record 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 Amazon EC2 key pair, 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 RDS database instance and an Amazon EC2 instance.

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 field, type a stack name. For this example, use MyWPTestStack. The stack name cannot contain spaces.

  4. Select Provide an S3 URL to template to 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 field, 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 section of the template.

  6. Click Next Step.

  7. In this scenario, we won't add any tags. Click Next. 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 that are 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 stack details pane, 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:

2013-04-24 18:54 UTC-7 CREATE_IN_PROGRESS AWS::CloudFormation::Stack MyWPTestStack User initiated

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 CREATE_COMPLETE AWS::RDS::DBSecurityGroup...

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

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:

2013-04-24 19:17 UTC-7 CREATE_COMPLETE AWS::CloudFormation::Stack MyWPTestStack

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

2013-04-24 19:21 UTC-7 CREATE_FAILED AWS::RDS::DBInstance DBInstance 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 WebsiteURL row, click the link in the Value column.

    The WebsiteURL 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.

    After you complete the installation and log in, you are directed to the dashboard where you can set additional options for your WordPress blog. Then, you can start writing posts for your blog that you successfully created by 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. From 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 by 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.