Adding and Customizing Elastic Beanstalk Environment Resources

You may also want to customize your environment resources that are part of your Elastic Beanstalk environment. For example, you may want to add an Amazon SQS queue and an alarm on queue depth, or you might want to add an Amazon ElastiCache cluster. You can easily customize your environment at the same time that you deploy your application version by including a configuration file with your source bundle.

You can use the Resources key in a configuration file to create and customize AWS resources in your environment. Resources defined in configuration files are added to the AWS CloudFormation template used to launch your environment. All AWS CloudFormation resources types are supported.

For example, the following configuration file adds an Auto Scaling lifecycle hook to the default Auto Scaling group created by Elastic Beanstalk:

~/my-app/.ebextensions/as-hook.config

Resources:
  hookrole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument: {
               "Version" : "2012-10-17",
               "Statement": [ {
                  "Effect": "Allow",
                  "Principal": {
                     "Service": [ "autoscaling.amazonaws.com" ]
                  },
                  "Action": [ "sts:AssumeRole" ]
               } ]
            }
      Policies: [ {
               "PolicyName": "SNS",
               "PolicyDocument": {
                      "Version": "2012-10-17",
                      "Statement": [{
                          "Effect": "Allow",
                          "Resource": "*",
                          "Action": [
                              "sqs:SendMessage",
                              "sqs:GetQueueUrl",
                              "sns:Publish"
                          ]
                        }
                      ]
                  }
               } ]
  hooktopic:
    Type: AWS::SNS::Topic
    Properties:
      Subscription:
        - Endpoint: "my-email@example.com"
          Protocol: email
  lifecyclehook:
    Type: AWS::AutoScaling::LifecycleHook
    Properties:
      AutoScalingGroupName: { "Ref" : "AWSEBAutoScalingGroup" }
      LifecycleTransition: autoscaling:EC2_INSTANCE_TERMINATING
      NotificationTargetARN: { "Ref" : "hooktopic" }
      RoleARN: { "Fn::GetAtt" : [ "hookrole", "Arn"] }

This example defines three resources, hookrole, hooktopic and lifecyclehook. The first two resources are an IAM role, which grants Auto Scaling permission to publish messages to Amazon SNS, and an SNS topic, which relays messages from the Auto Scaling group to an email address. Elastic Beanstalk creates these resources with the specified properties and types.

The final resource, lifecyclehook, is the lifecycle hook itself:

  lifecyclehook:
    Type: AWS::AutoScaling::LifecycleHook
    Properties:
      AutoScalingGroupName: { "Ref" : "AWSEBAutoScalingGroup" }
      LifecycleTransition: autoscaling:EC2_INSTANCE_TERMINATING
      NotificationTargetARN: { "Ref" : "hooktopic" }
      RoleARN: { "Fn::GetAtt" : [ "hookrole", "Arn"] }

The lifecycle hook definition uses a few intrinsic functions to populate values for the hook's properties. { "Ref" : "AWSEBAutoScalingGroup" } retrieves the name of the Auto Scaling group created by Elastic Beanstalk for the environment. AWSEBAutoScalingGroup is one of the standard resource names provided by Elastic Beanstalk.

For AWS::IAM::Role, Ref only returns the name of the role, not the ARN. To get the ARN for the RoleARN parameter, you use another intrinsic function, Fn::GetAtt instead, which can get any attribute from a resource. RoleARN: { "Fn::GetAtt" : [ "hookrole", "Arn"] } gets the Arn attribute from the hookrole resource.

{ "Ref" : "hooktopic" } gets the ARN of the Amazon SNS topic created earlier in the configuration file. The value returned by Ref varies per resource type and can be found in the AWS CloudFormation User Guide topic for the AWS::SNS::Topic resource type.

Syntax

When defining the values for the properties for your resource, there are three different methods you can use to define the values for the properties for a resource:

Pass the value
Pass a list of values
Pass the option name and the value

There are two different functions you can use to retrieve the values for the properties:

Use Fn::GetAtt to return the value of an attribute from a resource. For more information, see Fn::GetAtt.
Use Ref to return the value of a specified parameter or resource. For more information, see Ref.

Resources: 
  <name of resource>:
    Type: <resource type identifier> 
    Properties: 
      # Example syntax of a property that takes in the actual value
      <property name>: <literal string> 
      
      # Example syntax of a property that takes a list of strings
      <property name>: ["<literal string>", "<literal string>"]
      
      # Example syntax of a property that takes the option name and the value
       <property name>: 
         - Name: <option name>
           Value: <literal string> 
      
      # Example syntax showing how to use Fn::GetAtt to return the value of an attribute from a resource in the configuration file
      <property name>: 
         - Name: <option name>
           Value : { "Fn::GetAtt" : [ "<logicalNameOfResource>", "<attributeName>"] }  

      # Example syntax showing how to use Ref to return the value of a specified parameter or resource. You can use Ref for single property values and lists.
      <property name>: 
          Ref: <parameter reference>

Options

This table shows the available keys and descriptions for the Resources key.

Key	Description
`<name of resource>`	The name for what you want to create your resource. Each resource must have a logical name unique within the configuration file. This is the name you use elsewhere in the configuration file to reference the resource.

This table shows the available keys and descriptions for each resource name you provide.

Key	Description
`Type`	This is the resource type identifier. For a list of resource type identifiers, see AWS Resource Types Reference.
`Properties`	Optional. A `Properties` section is declared for each resource immediately after the resource `Type` declaration. Property values can be literal strings, lists of strings, parameter references, pseudo references, or the value returned by a function. If a resource does not require any properties to be declared, you can omit the `Properties` section of that resource.

Elastic Beanstalk Resource Names

Elastic Beanstalk provides fixed resource names for the AWS resources that it creates for you when you deploy your application. You will need to know these resource names when you reference them in your configuration file. You can use Ref and Fn::GetAtt to retrieve information about these resources in your configuration files. The value of Ref and the attributes available are determined by the type of the resource in CloudFormation.

Resource Name	Description
`AWSEBAutoScalingGroup`	The Auto Scaling group attached to your environment. Type: AWS::AutoScaling::AutoScalingGroup
`AWSEBAutoScalingLaunchConfiguration`	The launch configuration attached to your environment's Auto Scaling group. Type: AWS::AutoScaling::LaunchConfiguration
`AWSEBEnvironmentName`	Your environment. Type: AWS::ElasticBeanstalk::Environment
`AWSEBLoadBalancer`	Your environment's load balancer (if applicable). Type: AWS::ElasticLoadBalancing::LoadBalancer
`AWSEBLoadBalancerSecurityGroup`	In a custom VPC only, the name of the security group that Elastic Beanstalk creates for the load balancer. In a default VPC or EC2 classic, Elastic Load Balancing assigns a default security group to the load balancer. Type: AWS::EC2::SecurityGroup
`AWSEBRDSDatabase`	The Amazon RDS DB instance attached to your environment (if applicable). Type: AWS::RDS::DBInstance
`AWSEBSecurityGroup`	The security group attached to your Auto Scaling group. Type: AWS::EC2::SecurityGroup
`AWSEBWorkerQueue`	In a worker environment, the Amazon SQS queue from which the daemon pulls requests that need to be processed. Type: AWS::SQS::Queue
`AWSEBWorkerDeadLetterQueue`	In a worker environment, the Amazon SQS queue that stores messages that cannot be delivered or otherwise were not successfully processed by the daemon. Type: AWS::SQS::Queue
`AWSEBWorkerCronLeaderRegistry`	In a worker environment, the Amazon DynamoDB table that is the internal registry used by the daemon for periodic tasks. Type: AWS::DynamoDB::Table

Example Snippets

The following is a list of example configuration files that you can use to customize your Elastic Beanstalk environments:

Document Conventions

« Previous Next »