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.
- 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:
- 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:
Bastion host configuration
All other groups, in a logical order
AWS Quick Start configuration
For parameter names (logical IDs), follow these guidelines:
Use Pascal case and begin with an uppercase letter.
Keep names short and specific.
It’s acceptable to abbreviate service names.
It’s acceptable to abbreviate “Availability Zone” as “AZ.”
Identify subnets as public or private.
For entities, the parameter number should directly follow the entity name.
If a feature attaches, extends, or complements the entity, its name should follow the entity name.
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.
SAP HANA Server host name (i.e., saphanaqs)
SAP HANA server host name
Don’t terminate labels with punctuation (e.g., periods).
CIDR range for your VPC:
CIDR range for your VPC
Don’t phrase labels as questions or instructions because it’s distracting.
Would you like to turn on 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.
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.
Specify both the minimum and maximum values allowed.
Specify the unit if it isn’t obvious. Add it to the description, not to the label.
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.
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).
Don’t use punctuation.
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.
Don’t include the optional designation in the parameter label.
If all the parameters in a group are optional, include “(Optional)” at the beginning of the group label.