To remove some of the guesswork involved in crafting parameter names and labels, and to ensure consistency, we’ve developed the guidelines described in this section. Following these guidelines will help you provide clear, consistent, self-explanatory prompts and instructions in the AWS CloudFormation console for users who are deploying your Quick Start.
- Use clear, accurate, easy to understand labels and descriptions. (See the following sections for details.)
- Check labels and descriptions for typographical errors, and fix them.
- Use correct branding for AWS services and for your own product references.
Use the following standards for group labels, parameter names, and parameter labels where they apply:
- When you use the 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.
For parameter names (logical IDs), follow these guidelines:
Use Pascal case, beginning with an uppercase letter.
Keep names short but specific.
It’s OK to abbreviate service names.
It’s OK to abbreviate “Availability Zone.”
Identify subnets as public or private.
For items that are entities, the parameter number should directly follow the entity name.
If a feature is attached, 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. Make sure to add a label) for each parameter, and follow these guidelines:
Keep the label short if possible, but make sure it’s descriptive.
API key that the firewall will use to authenticate API calls
API key for firewall
Use sentence case (capitalize only the first word and proper nouns).
SAP HANA Instance Type
SAP HANA instance type
Use correct AWS service names, but don’t spell them out.
Amazon Elastic Block Store volume size
Amazon EBS volume size
Spell out “AZ” (only exceptions are “Multi-AZ” and “Single-AZ”).
Number of AZs
Number of Availability Zones
Don’t include too much information (such as values, units, examples, optional/required designations) in the label—specify those details in the parameter description.
SAP HANA Server host name (e.g., saphanaqs)
SAP HANA server host name
Don’t add punctuation (such as periods or colons) to the end of the label.
CIDR range for your VPC:
CIDR range for your VPC
Don’t phrase the label as a question or instruction. This draws attention away from the important information.
Would you like to turn on automatic recovery?
Turn on automatic recovery
Add spaces between words and numbers.
Private subnet1 CIDR
Private subnet 1 CIDR
Crafting parameter descriptions
The parameter description is a string of up to 4000 characters. Add a description for each parameter to provide guidance for using the parameter effectively. Follow these guidelines:
Provide useful information, including minimum/maximum values, syntax, 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. It’s already displayed in the value field.
Specify both minimum and maximum allowed values.
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 these parameters, and the defaults might break the deployment.
Crafting parameter group labels
AWS CloudFormation parameter groups enable you to display parameters in an intuitive way. For example, you could place all the network-related parameters in a category called Network configuration and your database configuration parameters in a category called Database configuration. For instructions on setting up groups, see the AWS::CloudFormation::Interface resource. To label groups, follow these guidelines:
Use sentence case.
Keep short but descriptive.
Include the word “configuration” (in lowercase).
Don’t include 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.
Don’t include the optional designation in the group label, unless all the parameters in that group are optional. If they are, add “(optional)” to the end of the group label.
Ordering parameters and groups
Follow an order that makes sense, from general to specific, 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