AWS CloudFormation
User Guide (API Version 2010-05-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

AWS::ElasticLoadBalancing::LoadBalancer

The AWS::ElasticLoadBalancing::LoadBalancer type creates a LoadBalancer.

Note

If this resource has a public IP address and is also in a VPC that is defined in the same template, you must use the DependsOn attribute to declare a dependency on the VPC-gateway attachment. For more information, see DependsOn Attribute.

Syntax

{
   "Type": "AWS::ElasticLoadBalancing::LoadBalancer",
   "Properties": {
      "AccessLoggingPolicy" : AccessLoggingPolicy,
      "AppCookieStickinessPolicy" : [ AppCookieStickinessPolicy, ... ],
      "AvailabilityZones" : [ String, ... ],
      "ConnectionDrainingPolicy" : ConnectionDrainingPolicy,
      "CrossZone" : Boolean,
      "HealthCheck" : HealthCheck,
      "Instances" : [ String, ... ],
      "LBCookieStickinessPolicy" : [ LBCookieStickinessPolicy, ... ],
      "LoadBalancerName" : String,
      "Listeners" : [ Listener, ... ],
      "Policies" : [ ElasticLoadBalancing Policy, ... ],
      "Scheme" : String,
      "SecurityGroups" : [ Security Group, ... ],
      "Subnets" : [ String, ... ],
      "Tags" : [ Resource Tag, ... ]
   }
}

Properties

AccessLoggingPolicy

Captures detailed information for all requests made to your load balancer, such as the time a request was received, client’s IP address, latencies, request path, and server responses.

Required: No

Type: Elastic Load Balancing AccessLoggingPolicy

Update requires: No interruption

AppCookieStickinessPolicy

Generates one or more stickiness policies with sticky session lifetimes that follow that of an application-generated cookie. These policies can be associated only with HTTP/HTTPS listeners.

Required: No

Type: A list of AppCookieStickinessPolicy objects.

Update requires: No interruption

AvailabilityZones

The Availability Zones in which to create the load balancer. You can specify either AvailabilityZones or Subnets, but not both.

Required: No

Type: A list of strings

Update requires: Replacement if you did not have an Availability Zone specified and you are adding one or if you are removing all Availability Zones. Otherwise, update requires no interruption.

ConnectionDrainingPolicy

Whether deregistered or unhealthy instances can complete all in-flight requests.

Required: No

Type: Elastic Load Balancing ConnectionDrainingPolicy

Update requires: No interruption

CrossZone

Whether cross-zone load balancing is enabled for the load balancer. With cross-zone load balancing, your load balancer nodes route traffic to the back-end instances across all Availability Zones. By default the CrossZone property is false.

Required: No

Type: Boolean

Update requires: No interruption

HealthCheck

Application health check for the instances.

Required: No

Type: ElasticLoadBalancing HealthCheck Type.

Update requires: Replacement if you did not have a health check specified and you are adding one or if you are removing a health check. Otherwise, update requires no interruption.

Instances

A list of EC2 instance IDs for the load balancer.

Required: No

Type: A list of strings

Update requires: No interruption

LBCookieStickinessPolicy

Generates a stickiness policy with sticky session lifetimes controlled by the lifetime of the browser (user-agent), or by a specified expiration period. This policy can be associated only with HTTP/HTTPS listeners.

Required: No

Type: A list of LBCookieStickinessPolicy objects.

Update requires: No interruption

LoadBalancerName

A name for the load balancer. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the load balancer. The name must be unique within your set of load balancers. For more information, see Name Type.

Important

If you specify a name, you cannot do updates that require this resource to be replaced. You can still do updates to this resource if the update requires no or some interruption.

Required: No

Type: String

Update requires: Replacement

Listeners

One or more listeners for this load balancer. Each listener must be registered for a specific port, and you cannot have more than one listener for a given port.

Important

If you update the property values for a listener specified by the Listeners property, AWS CloudFormation will delete the existing listener and create a new one with the updated properties. During the time that AWS CloudFormation is performing this action, clients will not be able to connect to the load balancer.

Required: Yes

Type: A list of ElasticLoadBalancing Listener Property Type objects.

Update requires: No interruption

Policies

A list of elastic load balancing policies to apply to this elastic load balancer.

Required: No

Type: A list of ElasticLoadBalancing policy objects.

Update requires: No interruption

Scheme

For load balancers attached to an Amazon VPC, this parameter can be used to specify the type of load balancer to use. Specify "internal" to create an internal load balancer with a DNS name that resolves to private IP addresses.

Required: No

Type: String

Update requires: Replacement

SecurityGroups

Required: No

Type: A list of security groups assigned to your load balancer within your virtual private cloud (VPC).

Update requires: No interruption

Subnets

A list of subnet IDs in your virtual private cloud (VPC) to attach to your load balancer. You can specify either AvailabilityZones or Subnets, but not both.

For more information about using Elastic Load Balancing in a VPC, see How Do I Use Elastic Load Balancing in Amazon VPC in the Elastic Load Balancing Developer Guide.

Required: No

Type: A list of strings

Update requires: Replacement if you did not have an subnet specified and you are adding one or if you are removing all subnets. Otherwise, update requires no interruption.

Tags

An arbitrary set of tags (key-value pairs) for this load balancer.

Required: No

Type: AWS CloudFormation Resource Tags

Update requires: No interruption

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, it returns the resource name. For example, mystack-myelb-1WQN7BJGDB5YQ.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. This section lists the available attributes and corresponding return values.

CanonicalHostedZoneName

The name of the Amazon Route 53 hosted zone that is associated with the load balancer.

Important

If you specify internal for the Elastic Load Balancing scheme, use DNSName instead. For an internal scheme, the load balancer doesn't have a CanonicalHostedZoneName value.

Example: mystack-myelb-15HMABG9ZCN57-1013119603.us-east-1.elb.amazonaws.com

CanonicalHostedZoneNameID

The ID of the Amazon Route 53 hosted zone name that is associated with the load balancer.

Example: Z3DZXE0Q79N41H

DNSName

The DNS name for the load balancer.

Example: mystack-myelb-15HMABG9ZCN57-1013119603.us-east-1.elb.amazonaws.com

SourceSecurityGroup.GroupName

The security group that you can use as part of your inbound rules for your load balancer's back-end Amazon EC2 application instances.

Example: amazon-elb

SourceSecurityGroup.OwnerAlias

The owner of the source security group.

Example: amazon-elb-sg

For more information about using Fn:GetAtt, see Fn::GetAtt.

Examples

A load balancer with a health check and access logs

"ElasticLoadBalancer" : {
  "Type" : "AWS::ElasticLoadBalancing::LoadBalancer",
  "Properties" : {
    "AvailabilityZones" : { "Fn::GetAZs" : "" },
    "Instances" : [ { "Ref" : "Ec2Instance1" },{ "Ref" : "Ec2Instance2" } ],
    "Listeners" : [ {
      "LoadBalancerPort" : "80",
      "InstancePort" : { "Ref" : "WebServerPort" },
      "Protocol" : "HTTP"
    } ],
    "HealthCheck" : {
      "Target" : {
        "Fn::Join" : [ "", [ "HTTP:", { "Ref" : "WebServerPort" }, "/" ] ]
      },
      "HealthyThreshold" : "3",
      "UnhealthyThreshold" : "5",
      "Interval" : "30",
      "Timeout" : "5"
    },
    "AccessLoggingPolicy": {
      "S3BucketName": {
        "Ref": "S3LoggingBucket"
      },
      "S3BucketPrefix": "MyELBLogs",
      "Enabled": "true",
      "EmitInterval" : "60"
    },
  "DependsOn": "S3LoggingBucketPolicy"
  }
}

A load balancer with access logging enabled

The following sample snippet creates an Amazon S3 bucket with a bucket policy that allows the load balancer to store information in the Logs/AWSLogs/AWS account number/ folder. The load balancer also includes an explicit dependency on the bucket policy, which is required before the load balancer can write to the bucket.

"S3LoggingBucket": {
  "Type": "AWS::S3::Bucket"
},
"S3LoggingBucketPolicy": {
  "Type": "AWS::S3::BucketPolicy",
  "Properties": {
    "Bucket": {
      "Ref": "S3LoggingBucket"
    },
    "PolicyDocument": {
      "Version": "2008-10-17",
      "Statement": [ {
        "Sid": "ELBAccessLogs20130930",
        "Effect": "Allow",
        "Resource": {
          "Fn::Join": [
            "",
            [
              "arn:aws:s3:::",
              { "Ref": "S3LoggingBucket" },
              "/",
              "Logs",
              "/AWSLogs/",
              { "Ref": "AWS::AccountId" },
              "/*"
            ]
          ]
        },
        "Principal": "*",
        "Action": [
          "s3:PutObject"
        ]
      } ]
    }
  }
},
"ElasticLoadBalancer": {
  "Type": "AWS::ElasticLoadBalancing::LoadBalancer",
  "Properties": {
    "AvailabilityZones": { "Fn::GetAZs": "" },
    "Listeners": [{
      "LoadBalancerPort": "80",
      "InstancePort": "80",
      "Protocol": "HTTP"
    }],
    "HealthCheck": {
      "Target": "HTTP:80/",
      "HealthyThreshold": "3",
      "UnhealthyThreshold": "5",
      "Interval": "30",
      "Timeout": "5"
    },
    "AccessLoggingPolicy": {
      "S3BucketName": {
        "Ref": "S3LoggingBucket"
      },
      "S3BucketPrefix": "Logs",
      "Enabled": "true",
      "EmitInterval" : "60"
    }
  },
  "DependsOn": "S3LoggingBucketPolicy"
}

A load balancer with a connection draining policy

The following snippet enables a connection draining policy that ends connections to a deregistered or unhealthy instance after 60 seconds.

"ElasticLoadBalancer" : {
  "Type" : "AWS::ElasticLoadBalancing::LoadBalancer",
  "Properties" : {
    "AvailabilityZones" : { "Fn::GetAZs" : "" },
    "Instances" : [ { "Ref" : "Ec2Instance1" },{ "Ref" : "Ec2Instance2" } ],
    "Listeners": [{
      "LoadBalancerPort": "80",
      "InstancePort": "80",
      "Protocol": "HTTP"
    }],
    "HealthCheck": {
      "Target": "HTTP:80/",
      "HealthyThreshold": "3",
      "UnhealthyThreshold": "5",
      "Interval": "30",
      "Timeout": "5"
    },
    "ConnectionDrainingPolicy": {
      "Enabled" : "true",
      "Timeout" : "60"
    }
  }
}

More examples

Examples of AWS CloudFormation templates can be viewed and downloaded from the AWS CloudFormation Sample Templates. These include:

See Also