Using the old AWS CloudFormation Designer to create templates

Designer provides the following benefits: it allows you to see graphic representations of the resources in your template, it simplifies template authoring, and it simplifies template editing.

Visualize template resources

Parsing JSON- or YAML-formatted text files to see the resources that are in your template and their relationships can be difficult. In Designer, you can see a graphic representation of the resources that are included in a template and how they relate to each other.

Designer defines the information about your resources, such as their size and relative position, in template metadata. When you open a template, Designer automatically adds this metadata so that the current layout is preserved when you save your template. When you reopen a template in Designer, it displays the diagram exactly as it appeared when you last saved the template.

All layout information is defined in the AWS::CloudFormation::Designer metadata key, which is used only by Designer and won't interfere with creating AWS CloudFormation stacks. The following example of template metadata shows the layout information that Designer adds to a template as metadata:

JSON

"Metadata": {
  "AWS::CloudFormation::Designer": {
    "6b56eaae-0bb6-4215-aad6-12345EXAMPLE": {
      "size": {
        "width": 60,
        "height": 60
      },
      "position": {
        "x": 340,
        "y": 430
      },
      "z": 2,
      "parent": "21ccc9b0-29e9-4a86-9cf2-12345EXAMPLE",
      "embeds": [],
      "ismemberof": [
        "c3eead73-6a76-4532-9268-12345EXAMPLE"
      ]
    },
...

YAML

Metadata:
  'AWS::CloudFormation::Designer':
    6b56eaae-0bb6-4215-aad6-12345EXAMPLE:
      size:
        width: 60
        height: 60
      position:
        x: 340
        'y': 430
      z: 2
      parent: 21ccc9b0-29e9-4a86-9cf2-12345EXAMPLE
      embeds: []
      ismemberof:
        - c3eead73-6a76-4532-9268-12345EXAMPLE
...

Simplify template authoring

When you author template resources in a text editor, you must manually edit JSON or YAML, which can be tedious and error-prone. By using Designer, you spend less time manually coding your templates and more time designing your AWS infrastructure. In Designer, you drag and drop new resources to add them to your template, and you drag connections between resources to establish relationships. Designer automatically modifies the JSON or YAML.

When you create templates, Designer enforces some basic relationships between resources to help you create valid templates. For example, you can't add an EC2 instance directly inside a VPC; you must add the instance inside a subnet in the VPC.

You can also validate a template directly in Designer. It provides the same level of validation as the ValidateTemplate API call, which checks that the JSON or YAML syntax is valid, that all referenced parameters are declared, and that there are no circular dependencies.

Simplify editing with the integrated JSON and YAML editor

With the integrated editor, you can make your template modifications in the AWS CloudFormation console. You don't need to use a separate text editor to modify and save your templates. The integrated editor also provides an auto-complete feature that lists all property names for a resource, so you don't need to look them up or memorize them. In addition, you can use the integrated editor to convert JSON templates to YAML and vice versa.

Designer has four panes. The canvas pane shows a diagram of your template resources so that you can see them and their relationships at a glance. To add resources to your template, you drag them from the Resources types pane onto the canvas pane. Use the Integrated JSON and YAML editor pane to specify template details, such as resource properties or template parameters. After you've modified the template, you can save it to a local file or to an Amazon S3 bucket. When you convert a valid template from JSON to YAML or vice-versa, the Messages pane displays a success or failure message. When you open or validate an invalid template, the Messages pane displays validation errors.

The following figure illustrates the Designer panes and its main components.

Designer panes and components

Canvas pane

Designer displays your template resources as a diagram in the canvas pane. You can modify the diagram's layout, add or remove resources, and add or remove connections between resources in this pane. For example, you can add an Auto Scaling group and a launch configuration from the Resource types pane to the canvas pane. To connect these related resources, drag a connection between them.

How does Designer model resources?

When you drag a resource from the Resource types pane to the canvas pane, Designer models it as a container or as a square object.

Connecting resources

You connect resources to create associations between related resources. For example, when you add an Internet gateway and a VPC to the canvas pane, they have no relationship. To attach the gateway to the VPC, you must connect them. The method for connecting resources depends on the resource type and how Designer models the resource. The following descriptions and figures explain each method.

Accessing common resource actions with the resource menu

The Resource menu provides easy access to common resource actions: editing resource properties, duplicating a resource, deleting a resource, or viewing the documentation for the resource. To view the Resource menu, right-click on a resource in the canvas pane. The documentation link goes to the template reference, which describes the properties and syntax for that resource.

Resource menu

Defining explicit dependencies

To specify the order in which AWS CloudFormation creates and deletes resources, you can create explicit dependencies. Explicit dependencies are useful for overriding parallel resource creation and deletion. AWS CloudFormation automatically determines which resources in a template can be processed in parallel and which can't. When you specify a property that references an attribute from another source (using the Ref intrinsic function) or gets an attribute from another resource (with the Fn::GetAtt intrinsic function) in the same template, this implies a dependency and AWS CloudFormation builds them in the correct order.

However, in some cases, you must explicitly define dependencies. For example, a routing rule can't use an Internet gateway until the gateway has been attached to the VPC. Normally, AWS CloudFormation creates the routing rule immediately after it creates the Internet gateway due to an implicit dependency. But, AWS CloudFormation might create the rule before the Internet gateway has attached to the VPC, which causes an error. Therefore, you must explicitly define a dependency on the gateway-VPC attachment.

To create an explicit dependency, drag a line from the DependsOn (*) dot on the route to the gateway-VPC attachment.

For more information about when you might need to create an explicit dependency, see DependsOn attribute.

JSON

In JSON, these explicit dependencies are represented as a DependsOn attribute on a resource, as shown in the following example:

"PublicRoute": {
  "Type": "AWS::EC2::Route",
  "DependsOn": "VPCGatewayAttachment",
  "Properties": {
      "DestinationCidrBlock": "0.0.0.0/0",
      "RouteTableId": {
          "Ref": "PublicRouteTable"
      },
      "GatewayId": {
          "Ref": "InternetGateway"
      }
  }

YAML

In YAML, these explicit dependencies are represented as a DependsOn attribute on a resource, as shown in the following example:

PublicRoute:
  Type: 'AWS::EC2::Route'
  DependsOn:
    - VPCGatewayAttachment
  Properties:
    DestinationCidrBlock: 0.0.0.0/0
    RouteTableId: !Ref PublicRouteTable
    GatewayId: !Ref InternetGateway

Integrated JSON and YAML editor

Use Designer's integrated JSON and YAML editor to view and edit template details. For example, you can use the integrated editor to define the properties of a resource or to change a template parameter. The integrated editor has two views: a Components view and a Template view.

To make minor changes to a specific section of a template, use the Components view. In the Components view, the components that you can edit are divided into tabs. These tabs change depending on whether you have a resource selected.

For example, if you select a resource, Designer provides tabs to edit the resource's properties and attributes, such as an update policy or creation policy. If you haven't selected anything, Designer provides tabs for editing the template parameters, mappings, conditions, metadata, and outputs. Any changes that you make in the Components view must be valid JSON or YAML markup. If you introduce invalid JSON or YAML, Designer reverts the invalid markup to the valid markup when you leave the Components view.

To make broad changes to your template, use the Template view. In the Template view, the integrated JSON and YAML editor shows you the raw JSON or YAML of your entire template. When you want to make changes to a resource, select it in the canvas pane Designer automatically highlights that resource in the integrated JSON and YAML editor.

AWS CloudFormation Designer integrated JSON and YAML editor

Converting templates into YAML or JSON

You can convert a valid template back and forth between JSON and YAML by selecting the appropriate radio button in Choose template language. Designer can only convert valid YAML or valid JSON templates. If the conversion succeeds, the Messages pane displays a message like: Successfully converted the template to YAML.

Once you choose a template language, any new resources you drag onto the canvas will be created in the language you have selected. To change back to another language, make sure your template is valid and then select YAML or JSON where it says Choose template language.

Auto-complete

The integrated JSON and YAML editor includes an auto-complete feature that helps you specify resource properties, so you don't have to remember property names. To see a list of valid properties in a JSON template, press Ctrl+Space within the Properties curly braces ({}), as shown in the following example:

For a YAML template, you can first delete the opening and closing curly braces and press Enter to go to a new line. To see a list of valid properties, press Ctrl+Space on the new line after Properties, as shown in the following example:

Keyboard shortcuts

Designer's integrated JSON and YAML editor provides the following keyboard shortcuts: