Label and describe your parameters

This section is intended to ensure that you use consistent naming standards for parameters and labels. Following these guidelines helps 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 standard parameter names and 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

• Always put the AWS Partner Solution configuration section last:

  Network configuration
  …
  Bastion host configuration
  …
  All other groups, in a logical order
  …
  AWS Partner Solution 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. Add a label) for each parameter, following these guidelines:

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

  API key that the firewall uses 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?

  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 customer might overlook the parameters and break the deployment.

Crafting parameter group labels

AWS CloudFormation parameter groups enable you to display related parameters together. For example, you could put all your network-related parameters in a Network configuration category and your database-configuration parameters in a Database configuration category. For instructions on setting up groups, refer to the AWS::CloudFormation::Interface documentation. 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.