AWS CloudFormation Interface Metadata

AWS CloudFormation Metadata

Metadata section define the details about the cloudformation template. 

Syntax Template

Metadata:
  Instances:
    Description: "Instances details within dev environment"
  Applications:
    Description: "Application details for dev environment"

There are three types of AWS Cloudformation specific Metadata keys.

•   AWS::CloudFormation::Designer

It's auto generated during drag and drop of canvas within Cloudformation designer section.

•   AWS::CloudFormation::Interface

It's used for parameter grouping and labeling as per requirement

•   AWS::CloudFormation::Init

One of the most important section from Automation prospective, it's used for Application installation and configuration on our AWS EC2 instances.

So within this blog post, we will cover 

• What is Interface Metadata.
• Why and How it's used
• How to customize orders of defined parameters.
• How to group up parameters and mark them a identifying label.
• How to define labels for the parameters.

AWS::CloudFormation::Interface

So during our stack creation, you might have noticed our defined parameters appears into an alphabetical order by their Logical ids, it has nothing to do with the way or order we define in our CFN template.

Interface Metadata Syntax

Metadata:
  AWS::CloudFormation::Interface:
    ParameterGroups:
      - ParameterGroup
    ParameterLabels:
      - ParameterLabel

For this post, in order to understand more about it we will use the below CFN template as an example.

CFN Template

AWSTemplateFormatVersion: 2010-09-09
Description: |
  CFN Script to demonstrate Cloudformation Interface Metadata Usage
  Interface Metadata : AWS::CloudFormation::Interface
  Interface Metadata can be used to
           Group Parameters and it's order.
           Labels for Parameter for user friendly description input.
Parameters:
  EnvironmentName:
    Description: Select the environment.
    Type: String
    Default: dev
    AllowedValues:
      - dev
      - prd
  EC2KeyName:
    Description: Select your Key name from List.
    Type: AWS::EC2::KeyPair::KeyName
  EC2SecurityGroup:
    Description: Select your security group from List.
    Type: AWS::EC2::SecurityGroup::Id
  EC2Subnet:
    Description: Select your Subnet from List.
    Type: AWS::EC2::Subnet::Id
  EC2InstanceType:
    Type: String
    Default: t2.micro
    AllowedValues:
      - t2.micro
      - t2.small
  ApplicationType:
    Type: String
    Default: web
    AllowedValues:
      - web
      - app
  MonitoringStatus:
    Type: String
    Default: enabled
    AllowedValues:
      - enabled
      - disabled

When we will import the above template to create or update stack the console will appear something like below.

From above we can witness that irrespective of the order of allignment parameters within CFN script, it re-orders it within console alphabetically by Parameter's logical ids.

What if we want to group parameters and label them as a separate identifier, Interface metadata can help us to accomplish the goal

What are we going to do with above template ?

    Well we have two sections one relates to the  EC2 Configuration data and the other one is more specific to Application configuration, so we will define our parameter groups and label according to that only.

CFN Interface Metadata with Custom Parameter Group

AWSTemplateFormatVersion: 2010-09-09
Description: |
  CFN Script to demonstrate Cloudformation Interface Metadata Usage
  Interface Metadata : AWS::CloudFormation::Interface
  Interface Metadata can be used to
           Group Parameters and it's order.
           Labels for Parameter for user friendly description input.
Metadata:
  AWS::CloudFormation::Interface:
    ParameterGroups:
      - Label:
          default: "EC2 Configuration"
        Parameters:
          - EC2InstanceType
          - EC2KeyName
          - EC2SecurityGroup
          - EC2Subnet
      - Label:
          default: "Application Configuration"
        Parameters:
          - EnvironmentName
          - ApplicationType
          - MonitoringStatus

Once above file is imported, here is how the console screen looks likes.

We have two Parameter Groups and our parameters are ordered by the way we defined under these groups.

• EC2 Configuration
• Application Configuration.

Now, we will add some custom Labels to our Parameters to make it more user friendly and informative for user to avoid confusion.

Within our base template, we will intuit below Parameter Logical Ids with our own Label.

• EnvironmentName
• Be carefull while choosing your deployment environmnet
• EC2KeyName
• Ensure you have the keys before selecting
• MonitoringStatus
• It enables cloudwatch logs for application data

CFN Template to demonstrate Custom Labels for Parameters

Metadata:
  AWS::CloudFormation::Interface:
    ParameterGroups:
      - Label:
          default: "EC2 Configuration"
        Parameters:
          - EC2InstanceType
          - EC2KeyName
          - EC2SecurityGroup
          - EC2Subnet
      - Label:
          default: "Application Configuration"
        Parameters:
          - EnvironmentName
          - ApplicationType
          - MonitoringStatus
    ParameterLabels:
      EnvironmentName: 
        default: "Be carefull while choosing your deployment environmnet"
      EC2KeyName:
        default: "Ensure you have the keys before selecting"
      MonitoringStatus:
        default: "It enables cloudwatch logs for application data"

Once imported, this is the output in cloudformation console.

From above, we can state few things to note while using a parameter label configuration.

• ParameterLabels will substitute your logical Id for your parameter with the one we have declared as default within our ParameterLabels section.
• Only Logical Id gets substituted, description mentioned under individual parameter section persists.

AWS CFN best practice, we must use Interface metadata for large stack creation this makes things quite helpful for end user.

Feel free to comment.