Using the old AWS CloudFormation Designer to create templates - AWS CloudFormation

Using the old AWS CloudFormation Designer to create templates

Note

Infrastructure Composer in CloudFormation console mode is an improvement from AWS CloudFormation Designer. We recommend that you use Infrastructure Composer instead of Designer whenever possible. For more information, see Create templates visually with Infrastructure Composer.

Designer is a graphic tool for creating, viewing, and modifying AWS CloudFormation templates. With Designer, you can diagram your template resources using a drag-and-drop interface, and then edit their details using the integrated JSON and YAML editor. Whether you are a new or an experienced AWS CloudFormation user, AWS CloudFormation Designer can help you quickly see the interrelationship between a template's resources and easily modify templates.

Designer is part of the AWS CloudFormation console. To use it, open Designer at https://console.aws.amazon.com/cloudformation/designer and sign in with your AWS credentials.

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.

Note

Designer can't show or modify running resources in your stacks; use it only for creating, modifying, and saving templates.

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

Designer panes and components

A screenshot of the Designer with its panes and components numbered.
1. Toolbar

The toolbar provides quick access to commands for common actions, such as opening and saving templates, undoing or redoing changes, creating a stack, and validating your template. You can also download the diagram as an image, get help, or refresh the diagram in the canvas pane.

2. Resource types pane

The Resource types pane lists all the template resources that you can add to your template, categorized by their AWS service name. You add resources by dragging them from the Resource types pane to the canvas. Most of the supported resources are listed in the AWS resource and property types reference. The Resource types pane doesn't list connecting resources, such as the AWS::EC2::SubnetRouteTableAssociation resource. You create these resources when you connect the relevant resources, such as when you connect a route table to a subnet. For more information, see Canvas pane.

Note

Designer can display only AWS CloudFormation-supported resource types. It cannot display other entities, such as Availability Zones (AZs) or the resources of a nested stack.

3. Canvas pane

The canvas pane displays your template resources as a diagram. You use it to add or remove resources, create relationships between resources, and arrange their layout. The changes that you make in the canvas automatically modify the template's JSON or YAML. For more information, see Canvas pane.

4. Fit to window button

A button that resizes the canvas pane to fit your template's diagram.

5. Full screen and Split screen buttons

Buttons to select different views of Designer. You can select a full-screen view of the canvas, a full-screen view of the Integrated JSON and YAML editor, or a split-screen view of the canvas and editor.

6. Integrated JSON and YAML editor pane

In the integrated editor, you specify the details of your template, such as resource properties or template parameters. When you select an item in the canvas, Designer highlights the related JSON or YAML in the editor. After editing the JSON or YAML, you must choose Refresh Diagram (the refresh icon) to update the diagram. You can convert a valid template 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. AWS CloudFormation Designer doesn't preserve formatting when converting a template.

Important

We recommend that you do not add # YAML comments to your templates in Designer. If your YAML template has # comments, Designer doesn't preserve those comments when editing the YAML or converting to JSON. If you edit or modify your template in Designer (for example, if you drag a resource on the canvas), your comments are lost.

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.

7. Messages pane

When you convert a template from JSON to YAML or vice-versa, the Messages pane displays a success or failure message. When you open, validate, or attempt to create a stack with an invalid template, the Messages pane displays validation errors.

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.

Containers

Container resources are resizable rectangles that can contain other resources. For example, Designer models the AWS::EC2::VPC resource type as a container. You can drag resources, such as a subnet, into the VPC.

Container resource

Example of a container resource.
Square objects

Square objects resources can't be resized or contain other resources. For example, Designer models the AWS::EC2::Instance resource type as a square object.

Square object

Example of 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.

Adding resources to containers

When you drag valid resource into containers, Designer automatically creates associations between the resource and the container. For example, VPCs are container resources; you can drag a subnet into a VPC, and Designer automatically associates the two resources.

A subnet resource inside a VPC container.

These associations are represented in your template as a Ref intrinsic function, as shown in the following example:

JSON

"PublicSubnet": { "Type": "AWS::EC2::Subnet", "Properties": { "VpcId": { "Ref": "VPC" }, "CidrBlock": "10.0.0.0/24" }

YAML

PublicSubnet: Type: 'AWS::EC2::Subnet' Properties: VpcId: !Ref VPC CidrBlock: 10.0.0.0/24

In some cases, dropping a resource into a container doesn't create an association; you must drag a connection between the resources (see the next method for information about dragging connections between resources). To see if Designer associates resources, use the integrated JSON and YAML editor to look for a Ref from one resource to the other. For example, when you add an Auto Scaling group in a subnet container, Designer doesn't specify the group's VPCZoneIdentifier (subnet) property. To associate the two resources, you must drag a connection from the Auto Scaling group to the subnet.

Dragging connections between resources

The edge of each square and container resource has one or more dots, which represent the resources that you can create connections with. To create a connection, drag a connector line from the dot to the corresponding resource type. For example, to attach an Internet gateway to a VPC, drag a line from the VPC gateway attachment dot to anywhere on the VPC.

Dragging a connector line to create a connection (shown as an arrow).

These associations are represented in your template as a Ref intrinsic function or as a separate resource type. For example, when you connect an Internet gateway with a VPC, Designer creates an AWS::EC2::VPCGatewayAttachment resource type in your template to associate them. Resources like these aren't listed in the Resource types pane.

JSON

"VPCGatewayAttachment": { "Type": "AWS::EC2::VPCGatewayAttachment", "Properties": { "InternetGatewayId": { "Ref": "InternetGateway" }, "VpcId": { "Ref": "VPC" } }

YAML

VPCGatewayAttachment: Type: 'AWS::EC2::VPCGatewayAttachment' Properties: InternetGatewayId: !Ref InternetGateway VpcId: !Ref VPC
Coding connections between resources

In some cases, you must edit the template's JSON or YAML to create connections, such as when you connect two security groups. When you must edit the JSON or YAML to create connections, you create hard-coded connections (dashed-line connections). You cannot create or edit these connections in the canvas pane.

Two resources connected with a dashed-line connection.

Typically, when you embed references (Ref) within a resource's property, you create hard-coded connections. For example, you can define a connection between two security groups where one security group has an embedded ingress rule that permits traffic from the other. The following WebServerSecurityGroup resource has an ingress rule with a reference to the PublicLoadBalancerSecurityGroup resource.

JSON

"WebServerSecurityGroup": { "Type": "AWS::EC2::SecurityGroup", "Properties": { "VpcId": { "Ref": "VPC" }, "GroupDescription": "Allow access from HTTP and SSH traffic", "SecurityGroupIngress": [ { "IpProtocol": "tcp", "FromPort": 80, "ToPort": 80, "CidrIp": "0.0.0.0/0" }, { "IpProtocol": "tcp", "FromPort": 22, "ToPort": 22, "CidrIp": { "Ref": "SSHLocation" } } ] } ...

YAML

WebServerSecurityGroup: Type: 'AWS::EC2::SecurityGroup' Properties: VpcId: !Ref VPC GroupDescription: Allow access from HTTP and SSH traffic SecurityGroupIngress: - IpProtocol: tcp FromPort: 80 ToPort: 80 CidrIp: 0.0.0.0/0 - IpProtocol: tcp FromPort: 22 ToPort: 22 CidrIp: !Ref SSHLocation

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

The resource menu with its four buttons.

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.

Dragging the DependsOn dot to create a dependency.

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

Screen shot of the integrated JSON and YAML editor with raw JSON.

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.

Important

We recommend that you don't add # YAML comments to your templates in Designer. If your YAML template has # comments, Designer doesn't preserve those comments when editing the YAML or converting to JSON. If you edit or modify your template in Designer (for example, if you drag a resource on the canvas), your comments are lost.

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.

Note

When you convert a template to YAML, Designer uses short form notation for functions. For example, - !GetAtt. In addition, any visual links that you draw will use short form notation in YAML mode. For more information about intrinsic functions, see Ref.

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:

Auto-complete options in a JSON 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:

Auto-complete options in a YAML example.

Keyboard shortcuts

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

Ctrl+Space

Within the Properties key of a resource, lists all the available properties for the resource.

Ctrl+F

Searches for a specified value.

To highlight everything that matches the specified value, press Alt+Enter.

For examples of how to use AWS CloudFormation Designer to create and update templates, see the following walkthroughs: