This section is intended to ensure that you use consistent naming standards for parameters and labels. Following these guidelines will help you provide clear, self-explanatory prompts and instructions in the AWS CloudFormation console.

General guidelines

  • Use simple and easy-to-understand labels and descriptions.
  • Check labels and descriptions for typographical errors.
  • Use correct branding for both AWS services and for your own products.
  • Use the following standards for group labels, parameter names, and parameter labels: Standard parameters for Quick Starts

  • When you use VPC and bastion host templates as building blocks, use the parameter names and labels that are already defined in those templates—don’t change these.

Ordering parameters and groups

  • Use a logical order that moves from general to specific and from simple to advanced.

    Network configuration before workload configuration, VPC parameters before subnet parameters

  • The Quick Start configuration section is always last:

    Network configuration

    Bastion host configuration

    All other groups, in a logical order

    AWS Quick Start configuration

Naming parameters

For parameter names (logical IDs), follow these guidelines:

  • Use Pascal case and begin with an uppercase letter.

    keypairname, vpcTenancy

    KeyPairName, VPCTenancy

  • Keep names short and specific.

    Version

    BitBucketVersion

  • It’s acceptable to abbreviate service names.

    EMRClusterSize

  • It’s acceptable to abbreviate “Availability Zone” as “AZ.”

    ThirdAZ

  • Identify subnets as public or private.

    Subnet1ID

    PublicSubnet1ID

  • For entities, the parameter number should directly follow the entity name.

    WSFCNode1, WSFCNode2

  • If a feature attaches, extends, or complements the entity, its name should follow the entity name.

    ADServer2PrivateIP, WSFCNode2PrivateIP3

Crafting parameter labels

Labels are friendly names that the AWS CloudFormation console displays instead of the logical IDs. Ensure that you add a label) for each parameter, following these guidelines:

  • Keep the label short, but ensure it’s descriptive.

    API key that the firewall will use to authenticate API calls

    API key for firewall

  • Use sentence case (only capitalize the first word and proper nouns).

    SAP HANA Instance Type

    SAP HANA instance type

  • Use correct AWS service names, but use their abbreviated form.

    Amazon Elastic Block Store volume size

    Amazon EBS volume size

  • Spell out “AZ” (except for “Multi-AZ” and “Single-AZ”).

    Number of AZs

    Number of Availability Zones

  • Don’t include too much information (e.g., values, units, examples, optional/required designations) in the label—instead, specify those details in the parameter description. Avoid adding details to parameter labels

    SAP HANA Server host name (i.e., saphanaqs)

    SAP HANA server host name

  • Don’t terminate labels with punctuation (e.g., periods). Don't add punctuation to the end of parameter labels

    CIDR range for your VPC:

    CIDR range for your VPC

  • Don’t phrase labels as questions or instructions because it’s distracting.
    Don't phrase parameter labels as questions or instructions

    Would you like to turn on automatic recovery?

    Automatic recovery

  • Add spaces between words and numbers.

    Private subnet1 CIDR

    Private subnet 1 CIDR

Crafting parameter descriptions

A parameter description is a string of up to 4,000 characters. For effective guidance to others, provide a description for each parameter using these guidelines:

  • Provide useful information, including minimum and maximum values, syntax standards, requirements, and examples.

    A CIDR block that’s allowed external access to the Remote Desktop gateways. We recommend that you use a constrained CIDR range to reduce the potential of inbound attacks from unknown IP addresses.

  • For Boolean parameters (true/false or yes/no settings), start with “Choose” and explain what happens if they change the default. Describe the effects of the non-default value for Booleans

    Choose Yes to enable server-side encryption in Amazon S3.

    Choose No to disable server-side encryption in Amazon S3.

  • For descriptions of non-Boolean parameters, start with a noun phrase.

    Enter the name of the S3 bucket that stores your backup data.

    The name of the S3 bucket that stores your backup data.

  • Don’t specify the default value in the description because it already appears in the value field. Don't specify the default value

  • Specify both the minimum and maximum values allowed. Specify minimum and maximum allowed values

  • Specify the unit if it isn’t obvious. Add it to the description, not to the label. Specify the unit

  • Explain syntax requirements and provide examples in the description, not in the value field. Otherwise, the user might overlook the parameters and break the deployment. Don't use the value field to display syntax

Crafting parameter group labels

AWS CloudFormation parameter groups enable you to intuitively display parameters. For example, you could place all the network-related parameters in a Network configuration category and your database configuration parameters in a Database configuration category. For instructions on setting up groups, see the AWS::CloudFormation::Interface resource. Follow these guidelines to label groups:

  • Use sentence case.

  • Keep names short and descriptive.

  • Include the word “configuration” (in lowercase).

    Syntax for group labels

  • Don’t use punctuation.

    Don't include punctuation in group labels

Specifying optional parameters

  • For optional parameters, include “(Optional)” at the beginning of the parameter description for best visibility. If you add it to the end of the description or as a sentence (e.g., “This parameter is optional.”) within the description, it won’t stand out as well.

    Best placement for optional designation in a description

  • Don’t include the optional designation in the parameter label.

    Don't include optional designation in parameter labels

  • If all the parameters in a group are optional, include “(Optional)” at the beginning of the group label.

    Include "(Optional)" at the beginning of a group label—the table title—if all parameters in that group are optional.