ElasticLoadBalancing/2012 06 01/elb api 2012 06 01
Elastic Load Balancing API Reference API Version 2012-06-01
Elastic Load Balancing API Reference
Elastic Load Balancing: API Reference Copyright © 2013 Amazon Web Services, Inc. and/or its affiliates. All rights reserved. The following are trademarks of Amazon Web Services, Inc.: Amazon, Amazon Web Services Design, AWS, Amazon CloudFront, Cloudfront, Amazon DevPay, DynamoDB, ElastiCache, Amazon EC2, Amazon Elastic Compute Cloud, Amazon Glacier, Kindle, Kindle Fire, AWS Marketplace Design, Mechanical Turk, Amazon Redshift, Amazon Route 53, Amazon S3, Amazon VPC. In addition, Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other countries. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.
Elastic Load Balancing API Reference
Welcome ................................................................................................................................................. 1 Actions .................................................................................................................................................... 2 ApplySecurityGroupsToLoadBalancer .................................................................................................... 3 AttachLoadBalancerToSubnets .............................................................................................................. 5 ConfigureHealthCheck ............................................................................................................................ 7 CreateAppCookieStickinessPolicy .......................................................................................................... 9 CreateLBCookieStickinessPolicy .......................................................................................................... 11 CreateLoadBalancer ............................................................................................................................. 13 CreateLoadBalancerListeners .............................................................................................................. 19 CreateLoadBalancerPolicy ................................................................................................................... 21 DeleteLoadBalancer ............................................................................................................................. 23 DeleteLoadBalancerListeners ............................................................................................................... 24 DeleteLoadBalancerPolicy .................................................................................................................... 25 DeregisterInstancesFromLoadBalancer ............................................................................................... 26 DescribeInstanceHealth ....................................................................................................................... 28 DescribeLoadBalancerAttributes .......................................................................................................... 31 DescribeLoadBalancerPolicies ............................................................................................................. 33 DescribeLoadBalancerPolicyTypes ...................................................................................................... 36 DescribeLoadBalancers ....................................................................................................................... 39 DetachLoadBalancerFromSubnets ....................................................................................................... 42 DisableAvailabilityZonesForLoadBalancer ............................................................................................ 44 EnableAvailabilityZonesForLoadBalancer ............................................................................................ 46 ModifyLoadBalancerAttributes .............................................................................................................. 48 RegisterInstancesWithLoadBalancer .................................................................................................... 51 SetLoadBalancerListenerSSLCertificate .............................................................................................. 53 SetLoadBalancerPoliciesForBackendServer ........................................................................................ 55 SetLoadBalancerPoliciesOfListener ..................................................................................................... 57 Data Types ............................................................................................................................................ 59 AccessLog ............................................................................................................................................ 60 AppCookieStickinessPolicy ................................................................................................................... 61 ApplySecurityGroupsToLoadBalancerResult ........................................................................................ 61 AttachLoadBalancerToSubnetsResult .................................................................................................. 62 BackendServerDescription ................................................................................................................... 62 ConfigureHealthCheckResult ............................................................................................................... 62 ConnectionDraining .............................................................................................................................. 63 CreateAppCookieStickinessPolicyResult .............................................................................................. 63 CreateLBCookieStickinessPolicyResult ................................................................................................ 63 CreateLoadBalancerListenersResult .................................................................................................... 63 CreateLoadBalancerPolicyResult ......................................................................................................... 64 CreateLoadBalancerResult ................................................................................................................... 64 CrossZoneLoadBalancing .................................................................................................................... 64 DeleteLoadBalancerListenersResult .................................................................................................... 65 DeleteLoadBalancerPolicyResult .......................................................................................................... 65 DeleteLoadBalancerResult ................................................................................................................... 65 DeregisterInstancesFromLoadBalancerResult ..................................................................................... 65 DescribeInstanceHealthResult ............................................................................................................. 66 DescribeLoadBalancerAttributesResult ................................................................................................ 66 DescribeLoadBalancerPoliciesResult ................................................................................................... 66 DescribeLoadBalancerPolicyTypesResult ............................................................................................ 67 DescribeLoadBalancersResult ............................................................................................................. 67 DetachLoadBalancerFromSubnetsResult ............................................................................................ 67 DisableAvailabilityZonesForLoadBalancerResult ................................................................................. 68 EnableAvailabilityZonesForLoadBalancerResult .................................................................................. 68 HealthCheck ......................................................................................................................................... 68 Instance ................................................................................................................................................ 69 InstanceState ........................................................................................................................................ 70 LBCookieStickinessPolicy ..................................................................................................................... 70 Listener ................................................................................................................................................. 71 API Version 2012-06-01 3
Elastic Load Balancing API Reference
ListenerDescription ............................................................................................................................... 72 LoadBalancerAttributes ........................................................................................................................ 72 LoadBalancerDescription ..................................................................................................................... 73 ModifyLoadBalancerAttributesResult .................................................................................................... 75 Policies ................................................................................................................................................. 76 PolicyAttribute ....................................................................................................................................... 76 PolicyAttributeDescription ..................................................................................................................... 77 PolicyAttributeTypeDescription ............................................................................................................. 77 PolicyDescription .................................................................................................................................. 78 PolicyTypeDescription ........................................................................................................................... 78 RegisterInstancesWithLoadBalancerResult ......................................................................................... 79 SetLoadBalancerListenerSSLCertificateResult .................................................................................... 79 SetLoadBalancerPoliciesForBackendServerResult .............................................................................. 79 SetLoadBalancerPoliciesOfListenerResult ........................................................................................... 80 SourceSecurityGroup ........................................................................................................................... 80 Common Parameters ............................................................................................................................ 81 Common Parameters for Signature V4 Signing .................................................................................... 83 Common Errors .................................................................................................................................... 85
API Version 2012-06-01 4
Elastic Load Balancing API Reference
Welcome Elastic Load Balancing is a cost-effective and easy to use web service to help you improve the availability and scalability of your application running on Amazon Elastic Cloud Compute (Amazon EC2). It makes it easy for you to distribute application loads between two or more EC2 instances. Elastic Load Balancing supports the growth in traffic of your application by enabling availability through redundancy. This guide provides detailed information about Elastic Load Balancing actions, data types, and parameters that can be used for sending a query request. Query requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and a query parameter named Action or Operation. Action is used throughout this documentation, although Operation is supported for backward compatibility with other AWS Query APIs. For detailed information on constructing a query request using the actions, data types, and parameters mentioned in this guide, go to Using the Query API in the Elastic Load Balancing Developer Guide. For detailed information about Elastic Load Balancing features and their associated actions, go to Using Elastic Load Balancing in the Elastic Load Balancing Developer Guide. This reference guide is based on the current WSDL, which is available at: http://ec2-downloads.s3.amazonaws.com/ElasticLoadBalancing.wsdl Endpoints The examples in this guide assume that your load balancers are created in the US East (Northern Virginia) region and use us-east-1 as the endpoint. You can create your load balancers in other AWS regions. For information about regions and endpoints supported by Elastic Load Balancing, see Regions and Endpoints in the Amazon Web Services General Reference. This document was last updated on March 15, 2014.
API Version 2012-06-01 1
Elastic Load Balancing API Reference
Actions The following actions are supported: • • • • • • • • • • • • • • • • • •
ApplySecurityGroupsToLoadBalancer (p. 3) AttachLoadBalancerToSubnets (p. 5) ConfigureHealthCheck (p. 7) CreateAppCookieStickinessPolicy (p. 9) CreateLBCookieStickinessPolicy (p. 11) CreateLoadBalancer (p. 13) CreateLoadBalancerListeners (p. 19) CreateLoadBalancerPolicy (p. 21) DeleteLoadBalancer (p. 23) DeleteLoadBalancerListeners (p. 24) DeleteLoadBalancerPolicy (p. 25) DeregisterInstancesFromLoadBalancer (p. 26) DescribeInstanceHealth (p. 28) DescribeLoadBalancerAttributes (p. 31) DescribeLoadBalancerPolicies (p. 33) DescribeLoadBalancerPolicyTypes (p. 36) DescribeLoadBalancers (p. 39) DetachLoadBalancerFromSubnets (p. 42)
• DisableAvailabilityZonesForLoadBalancer (p. 44) • EnableAvailabilityZonesForLoadBalancer (p. 46) • ModifyLoadBalancerAttributes (p. 48) • RegisterInstancesWithLoadBalancer (p. 51) • SetLoadBalancerListenerSSLCertificate (p. 53) • SetLoadBalancerPoliciesForBackendServer (p. 55) • SetLoadBalancerPoliciesOfListener (p. 57)
API Version 2012-06-01 2
Elastic Load Balancing API Reference ApplySecurityGroupsToLoadBalancer
ApplySecurityGroupsToLoadBalancer Description Associates one or more security groups with your load balancer in Amazon Virtual Private Cloud (Amazon VPC). The provided security group IDs will override any currently applied security groups. For more information, see Manage Security Groups in Amazon VPC in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the load balancer.The name must be unique within the set of load balancers associated with your AWS account. Type: String Required: Yes SecurityGroups.member.N A list of security group IDs to associate with your load balancer in VPC. The security group IDs must be provided as the ID and not the security group name (For example, sg-1234). Type: String list Required: Yes
Response Elements The following element is returned in a structure named ApplySecurityGroupsToLoadBalancerResult. SecurityGroups A list of security group IDs associated with your load balancer. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 InvalidSecurityGroup One or more specified security groups do not exist.
API Version 2012-06-01 3
Elastic Load Balancing API Reference Examples
HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?SecurityGroups.member.1=sg-123456789 &LoadBalancerName=my-test-vpc-loadbalancer &Version=2012-06-01 &Action=ApplySecurityGroupsToLoadBalancer &AUTHPARAMS
Sample Response <ApplySecurityGroupsToLoadBalancerResponse xmlns="http://elasticloadbalan cing.amazonaws.com/doc/2012-06-01/"> <ApplySecurityGroupsToLoadBalancerResult> <SecurityGroups> <member>sg-123456789 06b5decc-102a-11e3-9ad6-bf3e4EXAMPLE
API Version 2012-06-01 4
Elastic Load Balancing API Reference AttachLoadBalancerToSubnets
AttachLoadBalancerToSubnets Description Adds one or more subnets to the set of configured subnets in the Amazon Virtual Private Cloud (Amazon VPC) for the load balancer. The load balancers evenly distribute requests across all of the registered subnets. For more information, see Deploy Elastic Load Balancing in Amazon VPC in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the load balancer.The name must be unique within the set of load balancers associated with your AWS account. Type: String Required: Yes Subnets.member.N A list of subnet IDs to add for the load balancer. You can add only one subnet per Availability Zone. Type: String list Required: Yes
Response Elements The following element is returned in a structure named AttachLoadBalancerToSubnetsResult. Subnets A list of subnet IDs attached to the load balancer. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 InvalidSubnet The VPC has no Internet gateway. HTTP Status Code: 400
API Version 2012-06-01 5
Elastic Load Balancing API Reference Examples
SubnetNotFound One or more subnets were not found. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?Subnets.member.1=subnet-3561b05e &LoadBalancerName=my-test-vpc-loadbalancer &Version=2012-06-01 &Action=AttachLoadBalancerToSubnets &AUTHPARAMS
Sample Response <Subnets> <member>subnet-119f0078 <member>subnet-3561b05e 07b1ecbc-1100-11e3-acaf-dd7edEXAMPLE
API Version 2012-06-01 6
Elastic Load Balancing API Reference ConfigureHealthCheck
ConfigureHealthCheck Description Specifies the health check settings to use for evaluating the health state of your back-end instances. For more information, see Health Check in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). HealthCheck A structure containing the configuration information for the new healthcheck. Type: HealthCheck (p. 68) Required: Yes LoadBalancerName The mnemonic name associated with the load balancer. The name must be unique within the set of load balancers associated with your AWS account. Type: String Required: Yes
Response Elements The following element is returned in a structure named ConfigureHealthCheckResult. HealthCheck The updated healthcheck for the instances. Type: HealthCheck (p. 68)
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?HealthCheck.HealthyThreshold=2 &HealthCheck.UnhealthyThreshold=2
API Version 2012-06-01 7
Elastic Load Balancing API Reference Examples
&LoadBalancerName=MyLoadBalancer &HealthCheck.Target=HTTP:80/ping &HealthCheck.Interval=30 &HealthCheck.Timeout=3 &Version=2012-06-01 &Action=ConfigureHealthCheck &AUTHPARAMS
Sample Response 30 HTTP:80/ping 2 <Timeout>3 2 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 8
Elastic Load Balancing API Reference CreateAppCookieStickinessPolicy
CreateAppCookieStickinessPolicy Description Generates a stickiness policy with sticky session lifetimes that follow that of an application-generated cookie. This policy can be associated only with HTTP/HTTPS listeners. This policy is similar to the policy created by CreateLBCookieStickinessPolicy (p. 11), except that the lifetime of the special Elastic Load Balancing cookie follows the lifetime of the application-generated cookie specified in the policy configuration. The load balancer only inserts a new stickiness cookie when the application response includes a new application cookie. If the application cookie is explicitly removed or expires, the session stops being sticky until a new application cookie is issued.
Note An application client must receive and send two cookies: the application-generated cookie and the special Elastic Load Balancing cookie named AWSELB. This is the default behavior for many common web browsers. For more information, see Enabling Application-Controlled Session Stickiness in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). CookieName Name of the application cookie used for stickiness. Type: String Required: Yes LoadBalancerName The name of the load balancer. Type: String Required: Yes PolicyName The name of the policy being created. The name must be unique within the set of policies for this load balancer. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 9
Elastic Load Balancing API Reference Examples
DuplicatePolicyName Policy with the same name exists for this load balancer. Please choose another name. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 TooManyPolicies Quota for number of policies for this load balancer has already been reached. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?CookieName=MyAppCookie &LoadBalancerName=MyLoadBalancer &PolicyName=MyAppStickyPolicy &Version=2012-06-01 &Action=CreateAppCookieStickinessPolicy &AUTHPARAMS
Sample Response 99a693e9-12b8-11e3-9ad6-bf3e4EXAMPLE
API Version 2012-06-01 10
Elastic Load Balancing API Reference CreateLBCookieStickinessPolicy
CreateLBCookieStickinessPolicy Description Generates a stickiness policy with sticky session lifetimes controlled by the lifetime of the browser (user-agent) or a specified expiration period. This policy can be associated only with HTTP/HTTPS listeners. When a load balancer implements this policy, the load balancer uses a special cookie to track the backend server instance for each request. When the load balancer receives a request, it first checks to see if this cookie is present in the request. If so, the load balancer sends the request to the application server specified in the cookie. If not, the load balancer sends the request to a server that is chosen based on the existing load balancing algorithm. A cookie is inserted into the response for binding subsequent requests from the same user to that server. The validity of the cookie is based on the cookie expiration time, which is specified in the policy configuration. For more information, see Enabling Duration-Based Session Stickiness in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). CookieExpirationPeriod The time period in seconds after which the cookie should be considered stale. Not specifying this parameter indicates that the sticky session will last for the duration of the browser session. Type: Long Required: No LoadBalancerName The name associated with the load balancer. Type: String Required: Yes PolicyName The name of the policy being created. The name must be unique within the set of policies for this load balancer. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 11
Elastic Load Balancing API Reference Examples
DuplicatePolicyName Policy with the same name exists for this load balancer. Please choose another name. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 TooManyPolicies Quota for number of policies for this load balancer has already been reached. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?CookieExpirationPeriod=60 &LoadBalancerName=MyLoadBalancer&PolicyName=MyDurationStickyPolicy &Version=2012-06-01 &Action=CreateLBCookieStickinessPolicy &AUTHPARAMS
Sample Response 99a693e9-12b8-11e3-9ad6-bf3e4EXAMPLE
API Version 2012-06-01 12
Elastic Load Balancing API Reference CreateLoadBalancer
CreateLoadBalancer Description Creates a new load balancer. After the call has completed successfully, a new load balancer is created with a unique Domain Name Service (DNS) name. The DNS name includes the name of the AWS region in which the load balance was created. For example, if your load balancer was created in the United States, the DNS name might end with either of the following: • us-east-1.elb.amazonaws.com (for the Northern Virginia Region) • us-west-1.elb.amazonaws.com (for the Northern California Region) For information about the AWS regions supported by Elastic Load Balancing, see Regions and Endpoints. You can create up to 20 load balancers per region per account. Elastic Load Balancing supports load balancing your Amazon EC2 instances launched within any one of the following platforms: • EC2-Classic For information on creating and managing your load balancers in EC2-Classic, see Deploy Elastic Load Balancing in Amazon EC2-Classic. • EC2-VPC For information on creating and managing your load balancers in EC2-VPC, see Deploy Elastic Load Balancing in Amazon VPC.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). AvailabilityZones.member.N A list of Availability Zones. At least one Availability Zone must be specified. Specified Availability Zones must be in the same EC2 Region as the load balancer. Traffic will be equally distributed across all zones. You can later add more Availability Zones after the creation of the load balancer by calling EnableAvailabilityZonesForLoadBalancer (p. 46) action. Type: String list Required: No Listeners.member.N A list of the following tuples: LoadBalancerPort, InstancePort, and Protocol. Type: Listener (p. 71) list Required: Yes LoadBalancerName The name associated with the load balancer. The name must be unique within your set of load balancers. API Version 2012-06-01 13
Elastic Load Balancing API Reference Response Elements
Type: String Required: Yes Scheme The type of a load balancer. By default, Elastic Load Balancing creates an Internet-facing load balancer with a publicly resolvable DNS name, which resolves to public IP addresses. For more informationabout Internet-facing and Internal load balancers, see Internet-facing and Internal Load Balancers. Specify the value internal for this option to create an internal load balancer with a DNS name that resolves to private IP addresses.
Note This option is only available for load balancers created within EC2-VPC. Type: String Required: No SecurityGroups.member.N The security groups to assign to your load balancer within your VPC. Type: String list Required: No Subnets.member.N A list of subnet IDs in your VPC to attach to your load balancer. Specify one subnet per Availability Zone. Type: String list Required: No
Response Elements The following element is returned in a structure named CreateLoadBalancerResult. DNSName The DNS name for the load balancer. Type: String
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). CertificateNotFound The specified SSL ID does not refer to a valid SSL certificate in the AWS Identity and Access Management Service. HTTP Status Code: 400 DuplicateAccessPointName Load balancer name already exists for this account. Please choose another name. HTTP Status Code: 400
API Version 2012-06-01 14
Elastic Load Balancing API Reference Examples
InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 InvalidScheme Invalid value for scheme. Scheme can only be specified for load balancers in VPC. HTTP Status Code: 400 InvalidSecurityGroup One or more specified security groups do not exist. HTTP Status Code: 400 InvalidSubnet The VPC has no Internet gateway. HTTP Status Code: 400 SubnetNotFound One or more subnets were not found. HTTP Status Code: 400 TooManyAccessPoints The quota for the number of load balancers has already been reached. HTTP Status Code: 400
Examples Create a TCP load balancer in EC2-Classic Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &AvailabilityZones.member.1=us-east-1c &Listeners.member.1.LoadBalancerPort=80 &Listeners.member.1.InstancePort=80 &Listeners.member.1.Protocol=http &Listeners.member.1.InstanceProtocol=http &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
Sample Response MyLoadBalancer-1234567890.us-east-1.elb.amazonaws.com 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 15
Elastic Load Balancing API Reference Examples
Create HTTPS load balancer in EC2-Classic Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyHTTPSLoadBalancer &AvailabilityZones.member.1=us-east-1c &Listeners.member.1.LoadBalancerPort=443 &Listeners.member.1.InstancePort=443 &Listeners.member.1.Protocol=https &Listeners.member.1.InstanceProtocol=https &Listeners.member.1.SSLCertificateId=arn:aws:iam::123456789012:server-certific ate/servercert &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
Sample Response MyHTTPSLoadBalancer-1234567890.us-east-1.elb.amazonaws.com 1549581b-12b7-11e3-895e-1334aEXAMPLE
Create a TCP load balancer in EC2-VPC Sample Request https://elasticloadbalancing.amazonaws.com/?SecurityGroups.member.1=sg-6801da07 &LoadBalancerName=MyVPCLoadBalancer &Listeners.member.1.LoadBalancerPort=80 &Listeners.member.1.InstancePort=80 &Listeners.member.1.Protocol=http &Listeners.member.1.InstanceProtocol=http &Subnets.member.1=subnet-6dec9f03 &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
Sample Response MyVPCLoadBalancer-1234567890.us-east-1.elb.amazonaws.com
API Version 2012-06-01 16
Elastic Load Balancing API Reference Examples
1549581b-12b7-11e3-895e-1334aEXAMPLE
Create an internal TCP load balancer in EC2-VPC Sample Request https://elasticloadbalancing.amazonaws.com/?Scheme=internal &SecurityGroups.member.1=sg-706cb61f &LoadBalancerName=MyInternalLoadBalancer &Listeners.member.1.LoadBalancerPort=80 &Listeners.member.1.InstancePort=80 &Listeners.member.1.Protocol=http &Listeners.member.1.InstanceProtocol=http &Subnets.member.1=subnet-9edc97f0 &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
Sample Response internal-MyInternalLoadBalancer-1234567890.us-east-1.elb.amazon aws.com 1549581b-12b7-11e3-895e-1334aEXAMPLE
Create a TCP load balancer in default VPC Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyDefaultVPCLoad Balancer &AvailabilityZones.member.1=sa-east-1b &Listeners.member.1.LoadBalancerPort=80 &Listeners.member.1.InstancePort=80 &Listeners.member.1.Protocol=http &Listeners.member.1.InstanceProtocol=http &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
API Version 2012-06-01 17
Elastic Load Balancing API Reference Examples
Sample Response MyDefaultVPCLoadBalancer-1234567890.sa.east-1.elb.amazonaws.com 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 18
Elastic Load Balancing API Reference CreateLoadBalancerListeners
CreateLoadBalancerListeners Description Creates one or more listeners on a load balancer for the specified port. If a listener with the given port does not already exist, it will be created; otherwise, the properties of the new listener must match the properties of the existing listener. For more information, see Add a Listener to Your Load Balancer in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). Listeners.member.N A list of LoadBalancerPort, InstancePort, Protocol, and SSLCertificateId items. Type: Listener (p. 71) list Required: Yes LoadBalancerName The name of the load balancer. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 CertificateNotFound The specified SSL ID does not refer to a valid SSL certificate in the AWS Identity and Access Management Service. HTTP Status Code: 400 DuplicateListener A Listener already exists for the given LoadBalancerName and LoadBalancerPort, but with a different InstancePort, Protocol, or SSLCertificateId. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
API Version 2012-06-01 19
Elastic Load Balancing API Reference Examples
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?Listeners.member.1.Protocol=https &Listeners.member.1.LoadBalancerPort=443 &Listeners.member.1.InstancePort=443 &Listeners.member.1.InstanceProtocol=https &Listeners.member.1.SSLCertificateId=arn:aws:iam::123456789012:server-certific ate/servercert &LoadBalancerName=MyHTTPSLoadBalancer &Version=2012-06-01 &Action=CreateLoadBalancerListeners &AUTHPARAMS
Sample Response 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 20
Elastic Load Balancing API Reference CreateLoadBalancerPolicy
CreateLoadBalancerPolicy Description Creates a new policy that contains the necessary attributes depending on the policy type. Policies are settings that are saved for your load balancer and that can be applied to the front-end listener, or the back-end application server, depending on your policy type.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the LoadBalancer for which the policy is being created. Type: String Required: Yes PolicyAttributes.member.N A list of attributes associated with the policy being created. Type: PolicyAttribute (p. 76) list Required: No PolicyName The name of the load balancer policy being created. The name must be unique within the set of policies for this load balancer. Type: String Required: Yes PolicyTypeName The name of the base policy type being used to create this policy. To get the list of policy types, use the DescribeLoadBalancerPolicyTypes (p. 36) action. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 DuplicatePolicyName Policy with the same name exists for this load balancer. Please choose another name. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid.
API Version 2012-06-01 21
Elastic Load Balancing API Reference Examples
HTTP Status Code: 409 PolicyTypeNotFound One or more of the specified policy types do not exist. HTTP Status Code: 400 TooManyPolicies Quota for number of policies for this load balancer has already been reached. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?PolicyAttributes.member.1.Attribute Name=ProxyProtocol &PolicyAttributes.member.1.AttributeValue=true &PolicyTypeName=ProxyProtocolPolicyType &LoadBalancerName=my-test-loadbalancer &PolicyName=EnableProxyProtocol &Version=2012-06-01 &Action=CreateLoadBalancerPolicy &AUTHPARAMS
Sample Response 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 22
Elastic Load Balancing API Reference DeleteLoadBalancer
DeleteLoadBalancer Description Deletes the specified load balancer. If attempting to recreate the load balancer, you must reconfigure all the settings.The DNS name associated with a deleted load balancer will no longer be usable. Once deleted, the name and associated DNS record of the load balancer no longer exist and traffic sent to any of its IP addresses will no longer be delivered to back-end instances. To successfully call this API, you must provide the same account credentials as were used to create the load balancer.
Note By design, if the load balancer does not exist or has already been deleted, a call to DeleteLoadBalancer action still succeeds.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the load balancer. Type: String Required: Yes
API Version 2012-06-01 23
Elastic Load Balancing API Reference DeleteLoadBalancerListeners
DeleteLoadBalancerListeners Description Deletes listeners from the load balancer for the specified port.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The mnemonic name associated with the load balancer. Type: String Required: Yes LoadBalancerPorts.member.N The client port number(s) of the load balancer listener(s) to be removed. Type: Integer list Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 24
Elastic Load Balancing API Reference DeleteLoadBalancerPolicy
DeleteLoadBalancerPolicy Description Deletes a policy from the load balancer. The specified policy must not be enabled for any listeners.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The mnemonic name associated with the load balancer. Type: String Required: Yes PolicyName The mnemonic name for the policy being deleted. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
API Version 2012-06-01 25
Elastic Load Balancing API Reference DeregisterInstancesFromLoadBalancer
DeregisterInstancesFromLoadBalancer Description Deregisters instances from the load balancer. Once the instance is deregistered, it will stop receiving traffic from the load balancer. In order to successfully call this API, the same account credentials as those used to create the load balancer must be provided. For more information, see De-register and Register Amazon EC2 Instances in the Elastic Load Balancing Developer Guide. You can use DescribeLoadBalancers (p. 39) to verify if the instance is deregistered from the load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). Instances.member.N A list of EC2 instance IDs consisting of all instances to be deregistered. Type: Instance (p. 69) list Required: Yes LoadBalancerName The name associated with the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named DeregisterInstancesFromLoadBalancerResult. Instances An updated list of remaining instances registered with the load balancer. Type: Instance (p. 69) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidEndPoint The specified EndPoint is not valid. HTTP Status Code: 400 API Version 2012-06-01 26
Elastic Load Balancing API Reference Examples
Examples Deregister instance i-e3677ad7 from MyHTTPSLoadBalancer load balancer. Sample Request https://elasticloadbalancing.amazonaws.com/?Instances.member.1.InstanceId=ie3677ad7 &LoadBalancerName=MyHTTPSLoadBalancer &Version=2012-06-01 &Action=DeregisterInstancesFromLoadBalancer &AUTHPARAMS
Sample Response <member> i-6ec63d59 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 27
Elastic Load Balancing API Reference DescribeInstanceHealth
DescribeInstanceHealth Description Returns the current state of the specified instances registered with the specified load balancer. If no instances are specified, the state of all the instances registered with the load balancer is returned.
Note You must provide the same account credentials as those that were used to create the load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). Instances.member.N A list of instance IDs whose states are being queried. Type: Instance (p. 69) list Required: No LoadBalancerName The name of the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named DescribeInstanceHealthResult. InstanceStates A list containing health information for the specified instances. Type: InstanceState (p. 70) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidEndPoint The specified EndPoint is not valid. HTTP Status Code: 400
API Version 2012-06-01 28
Elastic Load Balancing API Reference Examples
Examples Description of a healthy (InService) instance Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &Version=2012-06-01 &Action=DescribeInstanceHealth &AUTHPARAMS
Sample Response <member> N/A i-90d8c2a5 <State>InService N/A 1549581b-12b7-11e3-895e-1334aEXAMPLE
Description of an instance with registration in progress Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=DescribeInstanceHealth &AUTHPARAMS
Sample Response <member> Instance registration is still in progress. i-315b7e51 <State>OutOfService ELB
API Version 2012-06-01 29
Elastic Load Balancing API Reference Examples
1549581b-12b7-11e3-895e-1334aEXAMPLE
Description of an unhealthy (OutOfService) instance Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer-2 &Version=2012-06-01 &Action=DescribeInstanceHealth &AUTHPARAMS
Sample Response <member> Instance has failed at least the UnhealthyThreshold number of health checks consecutively. i-fda142c9 <State>OutOfService Instance 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 30
Elastic Load Balancing API Reference DescribeLoadBalancerAttributes
DescribeLoadBalancerAttributes Description Returns detailed information about all of the attributes associated with the specified load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name of the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named DescribeLoadBalancerAttributesResult. LoadBalancerAttributes The load balancer attributes structure. Type: LoadBalancerAttributes (p. 72)
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 LoadBalancerAttributeNotFound The specified load balancer attribute could not be found. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &Version=2012-06-01 &Action=DescribeLoadBalancerAttributes &AUTHPARAMS
API Version 2012-06-01 31
Elastic Load Balancing API Reference Examples
Sample Response <Enabled>true <S3BucketName>my-loadbalancer-logs <S3BucketPrefix>testprefix <EmitInterval>5 <Enabled>true <Enabled>true <Timeout>60 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 32
Elastic Load Balancing API Reference DescribeLoadBalancerPolicies
DescribeLoadBalancerPolicies Description Returns detailed descriptions of the policies. If you specify a load balancer name, the action returns the descriptions of all the policies created for the load balancer. If you specify a policy name associated with your load balancer, the action returns the description of that policy. If you don't specify a load balancer name, the action returns descriptions of the specified sample policies, or descriptions of all the sample policies. The names of the sample policies have the ELBSample- prefix.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The mnemonic name associated with the load balancer. If no name is specified, the operation returns the attributes of either all the sample policies pre-defined by Elastic Load Balancing or the specified sample polices. Type: String Required: No PolicyNames.member.N The names of load balancer policies you've created or Elastic Load Balancing sample policy names. Type: String list Required: No
Response Elements The following element is returned in a structure named DescribeLoadBalancerPoliciesResult. PolicyDescriptions A list of policy description structures. Type: PolicyDescription (p. 78) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 PolicyNotFound One or more specified policies were not found. HTTP Status Code: 400
API Version 2012-06-01 33
Elastic Load Balancing API Reference Examples
Examples Description of all the policies associated with a load balancer Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &Version=2012-06-01 &Action=DescribeLoadBalancerPolicies &AUTHPARAMS
Sample Response <member> MyDurationStickyPolicy LBCookieStickinessPolicyType <member> CookieExpirationPeriod 60 <member> MyAppStickyPolicy AppCookieStickinessPolicyType <member> CookieName MyAppCookie 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
Description of a specified policy associated with the load balancer Sample Request https://elasticloadbalancing.amazonaws.com/?PolicyNames.member.1=EnableProxyPro tocol
API Version 2012-06-01 34
Elastic Load Balancing API Reference Examples
&LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=DescribeLoadBalancerPolicies &AUTHPARAMS
Sample Response <member> EnableProxyProtocol ProxyProtocolPolicyType <member> ProxyProtocol true 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 35
Elastic Load Balancing API Reference DescribeLoadBalancerPolicyTypes
DescribeLoadBalancerPolicyTypes Description Returns meta-information on the specified load balancer policies defined by the Elastic Load Balancing service. The policy types that are returned from this action can be used in a CreateLoadBalancerPolicy (p. 21) action to instantiate specific policy configurations that will be applied to a load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). PolicyTypeNames.member.N Specifies the name of the policy types. If no names are specified, returns the description of all the policy types defined by Elastic Load Balancing service. Type: String list Required: No
Response Elements The following element is returned in a structure named DescribeLoadBalancerPolicyTypesResult. PolicyTypeDescriptions List of policy type description structures of the specified policy type. If no policy type names are specified, returns the description of all the policy types defined by Elastic Load Balancing service. Type: PolicyTypeDescription (p. 78) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). PolicyTypeNotFound One or more of the specified policy types do not exist. HTTP Status Code: 400
API Version 2012-06-01 36
Elastic Load Balancing API Reference Examples
Examples Partial description of all the policy types defined by Elastic Load Balancing for your account Sample Request https://elasticloadbalancing.amazonaws.com/?Version=2012-06-01 &Action=DescribeLoadBalancerPolicyTypes &AUTHPARAMS
Sample Response SSLNegotiationPolicyType < . . . .> BackendServerAuthenticationPolicyType < . . . .> PublicKeyPolicyType < . . . .> AppCookieStickinessPolicyType < . . . .> LBCookieStickinessPolicyType < . . . .> ProxyProtocolPolicyType < . . . .> 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
Description of ProxyProtocolPolicyType Sample Request https://elasticloadbalancing.amazonaws.com/?PolicyTypeNames.member.1=ProxyPro tocolPolicyType &Version=2012-06-01 &Action=DescribeLoadBalancerPolicyTypes &AUTHPARAMS
Sample Response
API Version 2012-06-01 37
Elastic Load Balancing API Reference Examples
<member> <member> ProxyProtocol Boolean ONE ProxyProtocolPolicyType Policy that controls whether to include the IP address and port of the originating request for TCP messages. This policy operates on TCP/SSL listeners only 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 38
Elastic Load Balancing API Reference DescribeLoadBalancers
DescribeLoadBalancers Description Returns detailed configuration information for all the load balancers created for the account. If you specify load balancer names, the action returns configuration information of the specified load balancers.
Note In order to retrieve this information, you must provide the same account credentials that was used to create the load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerNames.member.N A list of load balancer names associated with the account. Type: String list Required: No Marker An optional parameter reserved for future use. Type: String Required: No
Response Elements The following elements are returned in a structure named DescribeLoadBalancersResult. LoadBalancerDescriptions A list of load balancer description structures. Type: LoadBalancerDescription (p. 73) list NextMarker An optional parameter reserved for future use. Type: String
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 39
Elastic Load Balancing API Reference Examples
Examples Description of a specified load balancer Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerNames.member.1=MyLoad Balancer &Version=2012-06-01 &Action=DescribeLoadBalancers &AUTHPARAMS
Sample Response <member> <SecurityGroups/> MyLoadBalancer 2013-05-24T21:15:31.280Z 90 HTTP:80/ 2 <Timeout>60 10 <member> HTTP 80 HTTP 80 <member> i-e4cbe38d <AppCookieStickinessPolicies/> <member>us-east-1a ZZZZZZZZZZZ123X MyLoadBalancer-123456789.us-east1.elb.amazonaws.com
API Version 2012-06-01 40
Elastic Load Balancing API Reference Examples
<Scheme>internet-facing <SourceSecurityGroup> amazon-elb amazon-elb-sg MyLoadBalancer-123456789.us-east-1.elb.amazonaws.com <Subnets/> 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 41
Elastic Load Balancing API Reference DetachLoadBalancerFromSubnets
DetachLoadBalancerFromSubnets Description Removes subnets from the set of configured subnets in the Amazon Virtual Private Cloud (Amazon VPC) for the load balancer. After a subnet is removed all of the EC2 instances registered with the load balancer that are in the removed subnet will go into the OutOfService state. When a subnet is removed, the load balancer will balance the traffic among the remaining routable subnets for the load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the load balancer to be detached. Type: String Required: Yes Subnets.member.N A list of subnet IDs to remove from the set of configured subnets for the load balancer. Type: String list Required: Yes
Response Elements The following element is returned in a structure named DetachLoadBalancerFromSubnetsResult. Subnets A list of subnet IDs the load balancer is now attached to. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
API Version 2012-06-01 42
Elastic Load Balancing API Reference Examples
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?Subnets.member.1=subnet-119f0078 &LoadBalancerName=my-test-vpc-loadbalancer &Version=2012-06-01 &Action=DetachLoadBalancerFromSubnets &AUTHPARAMS
Sample Response <Subnets> <member>subnet-159f007c <member>subnet-3561b05e 07b1ecbc-1100-11e3-acaf-dd7edEXAMPLE
API Version 2012-06-01 43
Elastic Load Balancing API Reference DisableAvailabilityZonesForLoadBalancer
DisableAvailabilityZonesForLoadBalancer Description Removes the specified EC2 Availability Zones from the set of configured Availability Zones for the load balancer. There must be at least one Availability Zone registered with a load balancer at all times. Once an Availability Zone is removed, all the instances registered with the load balancer that are in the removed Availability Zone go into the OutOfService state. Upon Availability Zone removal, the load balancer attempts to equally balance the traffic among its remaining usable Availability Zones. Trying to remove an Availability Zone that was not associated with the load balancer does nothing. For more information, see Disable an Availability Zone from a Load-Balanced Application in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). AvailabilityZones.member.N A list of Availability Zones to be removed from the load balancer.
Note There must be at least one Availability Zone registered with a load balancer at all times. Specified Availability Zones must be in the same region. Type: String list Required: Yes LoadBalancerName The name associated with the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named DisableAvailabilityZonesForLoadBalancerResult. AvailabilityZones A list of updated Availability Zones for the load balancer. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found.
API Version 2012-06-01 44
Elastic Load Balancing API Reference Examples
HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?AvailabilityZones.member.1=us-east1a &LoadBalancerName=MyHTTPSLoadBalancer &Version=2012-06-01 &Action=DisableAvailabilityZonesForLoadBalancer &AUTHPARAMS
Sample Response <member>us-east-1b ba6267d5-2566-11e3-9c6d-eb728EXAMPLE
API Version 2012-06-01 45
Elastic Load Balancing API Reference EnableAvailabilityZonesForLoadBalancer
EnableAvailabilityZonesForLoadBalancer Description Adds one or more EC2 Availability Zones to the load balancer. The load balancer evenly distributes requests across all its registered Availability Zones that contain instances.
Note The new EC2 Availability Zones to be added must be in the same EC2 Region as the Availability Zones for which the load balancer was created. For more information, see Expand a Load Balanced Application to an Additional Availability Zone in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). AvailabilityZones.member.N A list of new Availability Zones for the load balancer. Each Availability Zone must be in the same region as the load balancer. Type: String list Required: Yes LoadBalancerName The name associated with the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named EnableAvailabilityZonesForLoadBalancerResult. AvailabilityZones An updated list of Availability Zones for the load balancer. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 46
Elastic Load Balancing API Reference Examples
Examples Enable Availability Zone us-east-1c for my-test-loadbalancer. Sample Request https://elasticloadbalancing.amazonaws.com/?AvailabilityZones.member.1=us-east1c &LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=EnableAvailabilityZonesForLoadBalancer &AUTHPARAMS
Sample Response <EnableAvailabilityZonesForLoadBalancerResponse xmlns="http://elasticloadbalan cing.amazonaws.com/doc/2012-06-01/"> <EnableAvailabilityZonesForLoadBalancerResult> <member>us-east-1a <member>us-east-1c 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 47
Elastic Load Balancing API Reference ModifyLoadBalancerAttributes
ModifyLoadBalancerAttributes Description Modifies the attributes of a specified load balancer. You can modify the load balancer attributes, such as AccessLogs, ConnectionDraining, and CrossZoneLoadBalancing by either enabling or disabling them. For information on cross-zone load balancing, see Request Routing and for information on connection draining, see Connection Draining in the Concepts section of the Elastic Load Balancer Developer Guide. For information on access logs, see Access Logs.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerAttributes Attributes of the load balancer. Type: LoadBalancerAttributes (p. 72) Required: Yes LoadBalancerName The name of the load balancer. Type: String Required: Yes
Response Elements The following elements are returned in a structure named ModifyLoadBalancerAttributesResult. LoadBalancerAttributes The LoadBalancerAttributes data type. Type: LoadBalancerAttributes (p. 72) LoadBalancerName The name of the load balancer. Type: String
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid.
API Version 2012-06-01 48
Elastic Load Balancing API Reference Examples
HTTP Status Code: 409 LoadBalancerAttributeNotFound The specified load balancer attribute could not be found. HTTP Status Code: 400
Examples Enable Cross-Zone Load Balancing Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &LoadBalancerAttributes.CrossZoneLoadBalancing.Enabled=true &Version=2012-06-01 &Action=ModifyLoadBalancerAttributes &AUTHPARAMS
Sample Response <ModifyLoadBalancerAttributesResult> MyLoadBalancer <Enabled>true 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
Enable Access Log Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &LoadBalancerAttributes.AccessLog.Enabled=true &LoadBalancerAttributes.AccessLog.S3BucketName=my-loadbalancer-logs &LoadBalancerAttributes.AccessLog.S3BucketPrefix=my-bucket-prefix/prod &LoadBalancerAttributes.AccessLog.EmitInterval=60 &Version=2012-06-01 &Action=ModifyLoadBalancerAttributes &AUTHPARAMS
API Version 2012-06-01 49
Elastic Load Balancing API Reference Examples
Sample Response <ModifyLoadBalancerAttributesResult> MyLoadBalancer <Enabled>true <S3BucketName>my-loadbalancer-logs <S3BucketPrefix>my-bucket-prefix/prod <EmitInterval>60 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
Enable Connection Draining Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &LoadBalancerAttributes.ConnectionDraining.Enabled=true &LoadBalancerAttributes.ConnectionDraining.Timeout=60 &Version=2012-06-01 &Action=ModifyLoadBalancerAttributes &AUTHPARAMS
Sample Response <ModifyLoadBalancerAttributesResult> MyLoadBalancer <Enabled>true <Timeout>60 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 50
Elastic Load Balancing API Reference RegisterInstancesWithLoadBalancer
RegisterInstancesWithLoadBalancer Description Adds new instances to the load balancer. Once the instance is registered, it starts receiving traffic and requests from the load balancer. Any instance that is not in any of the Availability Zones registered for the load balancer will be moved to the OutOfService state. It will move to the InService state when the Availability Zone is added to the load balancer. When an instance registered with a load balancer is stopped and then restarted, the IP addresses associated with the instance changes. Elastic Load Balancing cannot recognize the new IP address, which prevents it from routing traffic to the instances. We recommend that you de-register your Amazon EC2 instances from your load balancer after you stop your instance, and then register the load balancer with your instance after you've restarted. To de-register your instances from load balancer, use DeregisterInstancesFromLoadBalancer (p. 26) action. For more information, see De-register and Register Amazon EC2 Instances in the Elastic Load Balancing Developer Guide.
Note In order for this call to be successful, you must provide the same account credentials as those that were used to create the load balancer.
Note Completion of this API does not guarantee that operation has completed. Rather, it means that the request has been registered and the changes will happen shortly. You can use DescribeLoadBalancers (p. 39) or DescribeInstanceHealth (p. 28) action to check the state of the newly registered instances.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). Instances.member.N A list of instance IDs that should be registered with the load balancer. Type: Instance (p. 69) list Required: Yes LoadBalancerName The name associated with the load balancer. The name must be unique within your set of load balancers. Type: String Required: Yes
Response Elements The following element is returned in a structure named RegisterInstancesWithLoadBalancerResult. Instances An updated list of instances for the load balancer.
API Version 2012-06-01 51
Elastic Load Balancing API Reference Errors
Type: Instance (p. 69) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidEndPoint The specified EndPoint is not valid. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?Instances.member.1.InstanceId=i315b7e51 &LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=RegisterInstancesWithLoadBalancer &AUTHPARAMS
Sample Response <member> i-315b7e51 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 52
Elastic Load Balancing API Reference SetLoadBalancerListenerSSLCertificate
SetLoadBalancerListenerSSLCertificate Description Sets the certificate that terminates the specified listener's SSL connections. The specified certificate replaces any prior certificate that was used on the same load balancer and port. For more information on updating your SSL certificate, see Updating an SSL Certificate for a Load Balancer in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name of the load balancer. Type: String Required: Yes LoadBalancerPort The port that uses the specified SSL certificate. Type: Integer Required: Yes SSLCertificateId The Amazon Resource Number (ARN) of the SSL certificate chain to use. For more information on SSL certificates, see Managing Server Certificates in the AWS Identity and Access Management User Guide. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 CertificateNotFound The specified SSL ID does not refer to a valid SSL certificate in the AWS Identity and Access Management Service. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 ListenerNotFound Load balancer does not have a listener configured at the given port.
API Version 2012-06-01 53
Elastic Load Balancing API Reference Examples
HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyInternalLoadBal ancer &SSLCertificateId=arn:aws:iam::123456789012:server-certificate/testcert &LoadBalancerPort=443 &Version=2012-06-01 &Action=SetLoadBalancerListenerSSLCertificate &AUTHPARAMS
Sample Response <SetLoadBalancerListenerSSLCertificateResponse xmlns="http://elasticloadbalan cing.amazonaws.com/doc/2012-06-01/"> <SetLoadBalancerListenerSSLCertificateResult/> 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 54
Elastic Load Balancing API Reference SetLoadBalancerPoliciesForBackendServer
SetLoadBalancerPoliciesForBackendServer Description Replaces the current set of policies associated with a port on which the back-end server is listening with a new set of policies. After the policies have been created using CreateLoadBalancerPolicy (p. 21), they can be applied here as a list. At this time, only the back-end server authentication policy type can be applied to the back-end ports; this policy type is composed of multiple public key policies.
Note The SetLoadBalancerPoliciesForBackendServer replaces the current set of policies associated with the specified instance port. Every time you use this action to enable the policies, use the PolicyNames parameter to list all the policies you want to enable. You can use DescribeLoadBalancers (p. 39) or DescribeLoadBalancerPolicies (p. 33) action to verify that the policy has been associated with the back-end server.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). InstancePort The port number associated with the back-end server. Type: Integer Required: Yes LoadBalancerName The mnemonic name associated with the load balancer. This name must be unique within the set of your load balancers. Type: String Required: Yes PolicyNames.member.N List of policy names to be set. If the list is empty, then all current polices are removed from the back-end server. Type: String list Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
API Version 2012-06-01 55
Elastic Load Balancing API Reference Examples
PolicyNotFound One or more specified policies were not found. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?InstancePort=80 &PolicyNames.member.1=EnableProxyProtocol &PolicyNames.member.2=MyPolicyName2 &PolicyNames.member.3=MyPolicyName3 &LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=SetLoadBalancerPoliciesForBackendServer &AUTHPARAMS
Sample Response <SetLoadBalancerPoliciesForBackendServerResponse xmlns="http://elasticloadbal ancing.amazonaws.com/doc/2012-06-01/"> <SetLoadBalancerPoliciesForBackendServerResult/> 0eb9b381-dde0-11e2-8d78-6ddbaEXAMPLE
API Version 2012-06-01 56
Elastic Load Balancing API Reference SetLoadBalancerPoliciesOfListener
SetLoadBalancerPoliciesOfListener Description Associates, updates, or disables a policy with a listener on the load balancer. You can associate multiple policies with a listener.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name of the load balancer. Type: String Required: Yes LoadBalancerPort The external port of the load balancer to associate the policy. Type: Integer Required: Yes PolicyNames.member.N List of policies to be associated with the listener. If the list is empty, the current policy is removed from the listener. Type: String list Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 ListenerNotFound Load balancer does not have a listener configured at the given port. HTTP Status Code: 400 PolicyNotFound One or more specified policies were not found. HTTP Status Code: 400
API Version 2012-06-01 57
Elastic Load Balancing API Reference Examples
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?PolicyNames.member.1=MySSLNegoti ationPolicy &LoadBalancerName=MyInternalLoadBalancer &LoadBalancerPort=443 &Version=2012-06-01 &Action=SetLoadBalancerPoliciesOfListener &AUTHPARAMS
Sample Response <SetLoadBalancerPoliciesOfListenerResponse xmlns="http://elasticloadbalancing.am azonaws.com/doc/2012-06-01/"> <SetLoadBalancerPoliciesOfListenerResult/> 07b1ecbc-1100-11e3-acaf-dd7edEXAMPLE
API Version 2012-06-01 58
Elastic Load Balancing API Reference
Data Types The Elastic Load Balancing API contains several data types that various actions use.This section describes each data type in detail.
Note The order of each element in the response is not guaranteed. Applications should not assume a particular order. The following data types are supported: • • • • • • • • • •
AccessLog (p. 60) AppCookieStickinessPolicy (p. 61) ApplySecurityGroupsToLoadBalancerResult (p. 61) AttachLoadBalancerToSubnetsResult (p. 62) BackendServerDescription (p. 62) ConfigureHealthCheckResult (p. 62) ConnectionDraining (p. 63) CreateAppCookieStickinessPolicyResult (p. 63) CreateLBCookieStickinessPolicyResult (p. 63) CreateLoadBalancerListenersResult (p. 63)
• • • •
CreateLoadBalancerPolicyResult (p. 64) CreateLoadBalancerResult (p. 64) CrossZoneLoadBalancing (p. 64) DeleteLoadBalancerListenersResult (p. 65)
• DeleteLoadBalancerPolicyResult (p. 65) • • • •
DeleteLoadBalancerResult (p. 65) DeregisterInstancesFromLoadBalancerResult (p. 65) DescribeInstanceHealthResult (p. 66) DescribeLoadBalancerAttributesResult (p. 66)
• DescribeLoadBalancerPoliciesResult (p. 66) • DescribeLoadBalancerPolicyTypesResult (p. 67) • DescribeLoadBalancersResult (p. 67) • DetachLoadBalancerFromSubnetsResult (p. 67) • DisableAvailabilityZonesForLoadBalancerResult (p. 68)
API Version 2012-06-01 59
Elastic Load Balancing API Reference AccessLog
• EnableAvailabilityZonesForLoadBalancerResult (p. 68) • HealthCheck (p. 68) • Instance (p. 69) • InstanceState (p. 70) • LBCookieStickinessPolicy (p. 70) • Listener (p. 71) • ListenerDescription (p. 72) • LoadBalancerAttributes (p. 72) • LoadBalancerDescription (p. 73) • ModifyLoadBalancerAttributesResult (p. 75) • Policies (p. 76) • PolicyAttribute (p. 76) • • • • • • • • •
PolicyAttributeDescription (p. 77) PolicyAttributeTypeDescription (p. 77) PolicyDescription (p. 78) PolicyTypeDescription (p. 78) RegisterInstancesWithLoadBalancerResult (p. 79) SetLoadBalancerListenerSSLCertificateResult (p. 79) SetLoadBalancerPoliciesForBackendServerResult (p. 79) SetLoadBalancerPoliciesOfListenerResult (p. 80) SourceSecurityGroup (p. 80)
AccessLog Description The AccessLog data type.
Contents EmitInterval The interval for publishing the access logs. You can specify an interval of either 5 minutes or 60 minutes. Default: 60 minutes Type: Integer Required: No Enabled Specifies whether access log is enabled for the load balancer. Type: Boolean Required: Yes S3BucketName The name of the Amazon S3 bucket where the access logs are stored. Type: String
API Version 2012-06-01 60
Elastic Load Balancing API Reference AppCookieStickinessPolicy
Required: No S3BucketPrefix The logical hierarchy you created for your Amazon S3 bucket, for example my-bucket-prefix/prod. If the prefix is not provided, the log is placed at the root level of the bucket. Type: String Required: No
AppCookieStickinessPolicy Description The AppCookieStickinessPolicy data type.
Contents CookieName The name of the application cookie used for stickiness. Type: String Required: No PolicyName The mnemonic name for the policy being created. The name must be unique within a set of policies for this load balancer. Type: String Required: No
ApplySecurityGroupsToLoadBalancerResult Description The out for the ApplySecurityGroupsToLoadBalancer (p. 3) action.
Contents SecurityGroups A list of security group IDs associated with your load balancer. Type: String list Required: No
API Version 2012-06-01 61
Elastic Load Balancing API Reference AttachLoadBalancerToSubnetsResult
AttachLoadBalancerToSubnetsResult Description The output for the AttachLoadBalancerToSubnets (p. 5) action.
Contents Subnets A list of subnet IDs attached to the load balancer. Type: String list Required: No
BackendServerDescription Description This data type is used as a response element in the DescribeLoadBalancers (p. 39) action to describe the configuration of the back-end server.
Contents InstancePort Provides the port on which the back-end server is listening. Type: Integer Required: No PolicyNames Provides a list of policy names enabled for the back-end server. Type: String list Required: No
ConfigureHealthCheckResult Description The output for the ConfigureHealthCheck (p. 7) action.
Contents HealthCheck The updated healthcheck for the instances. Type: HealthCheck (p. 68)
API Version 2012-06-01 62
Elastic Load Balancing API Reference ConnectionDraining
Required: No
ConnectionDraining Description The ConnectionDraining data type.
Contents Enabled Specifies whether connection draining is enabled for the load balancer. Type: Boolean Required: Yes Timeout Specifies the maximum time (in seconds) to keep the existing connections open before deregistering the instances. Type: Integer Required: No
CreateAppCookieStickinessPolicyResult Description The output for the CreateAppCookieStickinessPolicy (p. 9) action.
Contents
CreateLBCookieStickinessPolicyResult Description The output for the CreateLBCookieStickinessPolicy (p. 11) action.
Contents
CreateLoadBalancerListenersResult Description The output for the CreateLoadBalancerListeners (p. 19) action. API Version 2012-06-01 63
Elastic Load Balancing API Reference Contents
Contents
CreateLoadBalancerPolicyResult Description The output for the CreateLoadBalancerPolicy (p. 21) action.
Contents
CreateLoadBalancerResult Description The output for the CreateLoadBalancer (p. 13) action.
Contents DNSName The DNS name for the load balancer. Type: String Required: No
CrossZoneLoadBalancing Description The CrossZoneLoadBalancing data type.
Contents Enabled Specifies whether cross-zone load balancing is enabled for the load balancer. Type: Boolean Required: Yes
API Version 2012-06-01 64
Elastic Load Balancing API Reference DeleteLoadBalancerListenersResult
DeleteLoadBalancerListenersResult Description The output for the DeleteLoadBalancerListeners (p. 24) action.
Contents
DeleteLoadBalancerPolicyResult Description The output for the DeleteLoadBalancerPolicy (p. 25) action.
Contents
DeleteLoadBalancerResult Description The output for the DeleteLoadBalancer (p. 23) action.
Contents
DeregisterInstancesFromLoadBalancerResult Description The output for the DeregisterInstancesFromLoadBalancer (p. 26) action.
Contents Instances An updated list of remaining instances registered with the load balancer. Type: Instance (p. 69) list Required: No
API Version 2012-06-01 65
Elastic Load Balancing API Reference DescribeInstanceHealthResult
DescribeInstanceHealthResult Description The output for the DescribeInstanceHealth (p. 28) action.
Contents InstanceStates A list containing health information for the specified instances. Type: InstanceState (p. 70) list Required: No
DescribeLoadBalancerAttributesResult Description The following element is returned in a structure named DescribeLoadBalancerAttributesResult.
Contents LoadBalancerAttributes The load balancer attributes structure. Type: LoadBalancerAttributes (p. 72) Required: No
DescribeLoadBalancerPoliciesResult Description The output for the DescribeLoadBalancerPolicies (p. 33) action.
Contents PolicyDescriptions A list of policy description structures. Type: PolicyDescription (p. 78) list Required: No
API Version 2012-06-01 66
Elastic Load Balancing API Reference DescribeLoadBalancerPolicyTypesResult
DescribeLoadBalancerPolicyTypesResult Description The output for the DescribeLoadBalancerPolicyTypes (p. 36) action.
Contents PolicyTypeDescriptions List of policy type description structures of the specified policy type. If no policy type names are specified, returns the description of all the policy types defined by Elastic Load Balancing service. Type: PolicyTypeDescription (p. 78) list Required: No
DescribeLoadBalancersResult Description The output for the DescribeLoadBalancers (p. 39) action.
Contents LoadBalancerDescriptions A list of load balancer description structures. Type: LoadBalancerDescription (p. 73) list Required: No NextMarker An optional parameter reserved for future use. Type: String Required: No
DetachLoadBalancerFromSubnetsResult Description The output for the DetachLoadBalancerFromSubnets (p. 42) action.
Contents Subnets A list of subnet IDs the load balancer is now attached to. Type: String list
API Version 2012-06-01 67
Elastic Load Balancing API Reference DisableAvailabilityZonesForLoadBalancerResult
Required: No
DisableAvailabilityZonesForLoadBalancerResult Description The output for the DisableAvailabilityZonesForLoadBalancer (p. 44) action.
Contents AvailabilityZones A list of updated Availability Zones for the load balancer. Type: String list Required: No
EnableAvailabilityZonesForLoadBalancerResult Description The output for the EnableAvailabilityZonesForLoadBalancer (p. 46) action.
Contents AvailabilityZones An updated list of Availability Zones for the load balancer. Type: String list Required: No
HealthCheck Description The HealthCheck data type.
Contents HealthyThreshold Specifies the number of consecutive health probe successes required before moving the instance to the Healthy state. Type: Integer Required: Yes
API Version 2012-06-01 68
Elastic Load Balancing API Reference Instance
Interval Specifies the approximate interval, in seconds, between health checks of an individual instance. Type: Integer Required: Yes Target Specifies the instance being checked. The protocol is either TCP, HTTP, HTTPS, or SSL. The range of valid ports is one (1) through 65535.
Note TCP is the default, specified as a TCP: port pair, for example "TCP:5000". In this case a healthcheck simply attempts to open a TCP connection to the instance on the specified port. Failure to connect within the configured timeout is considered unhealthy. SSL is also specified as SSL: port pair, for example, SSL:5000. For HTTP or HTTPS protocol, the situation is different. You have to include a ping path in the string. HTTP is specified as a HTTP:port;/;PathToPing; grouping, for example "HTTP:80/weather/us/wa/seattle". In this case, a HTTP GET request is issued to the instance on the given port and path. Any answer other than "200 OK" within the timeout period is considered unhealthy. The total length of the HTTP ping target needs to be 1024 16-bit Unicode characters or less. Type: String Required: Yes Timeout Specifies the amount of time, in seconds, during which no response means a failed health probe.
Note This value must be less than the Interval value. Type: Integer Required: Yes UnhealthyThreshold Specifies the number of consecutive health probe failures required before moving the instance to the Unhealthy state. Type: Integer Required: Yes
Instance Description The Instance data type.
Contents InstanceId Provides an EC2 instance ID.
API Version 2012-06-01 69
Elastic Load Balancing API Reference InstanceState
Type: String Required: No
InstanceState Description The InstanceState data type.
Contents Description Provides a description of the instance state. Type: String Required: No InstanceId Provides an EC2 instance ID. Type: String Required: No ReasonCode Provides information about the cause of OutOfService instances. Specifically, it indicates whether the cause is Elastic Load Balancing or the instance behind the load balancer. Valid value: ELB|Instance|N/A Type: String Required: No State Specifies the current state of the instance. Valid value: InService|OutOfService Type: String Required: No
LBCookieStickinessPolicy Description The LBCookieStickinessPolicy data type.
API Version 2012-06-01 70
Elastic Load Balancing API Reference Contents
Contents CookieExpirationPeriod The time period in seconds after which the cookie should be considered stale. Not specifying this parameter indicates that the stickiness session will last for the duration of the browser session. Type: Long Required: No PolicyName The name for the policy being created. The name must be unique within the set of policies for this load balancer. Type: String Required: No
Listener Description The Listener data type.
Contents InstancePort Specifies the TCP port on which the instance server is listening. This property cannot be modified for the life of the load balancer. Type: Integer Required: Yes InstanceProtocol Specifies the protocol to use for routing traffic to back-end instances - HTTP, HTTPS, TCP, or SSL. This property cannot be modified for the life of the load balancer.
Note If the front-end protocol is HTTP or HTTPS, InstanceProtocol has to be at the same protocol layer, i.e., HTTP or HTTPS. Likewise, if the front-end protocol is TCP or SSL, InstanceProtocol has to be TCP or SSL.
Note If there is another listener with the same InstancePort whose InstanceProtocol is secure, i.e., HTTPS or SSL, the listener's InstanceProtocol has to be secure, i.e., HTTPS or SSL. If there is another listener with the same InstancePort whose InstanceProtocol is HTTP or TCP, the listener's InstanceProtocol must be either HTTP or TCP. Type: String Required: No LoadBalancerPort Specifies the external load balancer port number. This property cannot be modified for the life of the load balancer. Type: Integer API Version 2012-06-01 71
Elastic Load Balancing API Reference ListenerDescription
Required: Yes Protocol Specifies the load balancer transport protocol to use for routing - HTTP, HTTPS, TCP or SSL. This property cannot be modified for the life of the load balancer. Type: String Required: Yes SSLCertificateId The ARN string of the server certificate. To get the ARN of the server certificate, call the AWS Identity and Access Management UploadServerCertificate API. Type: String Required: No
ListenerDescription Description The ListenerDescription data type.
Contents Listener The Listener data type. Type: Listener (p. 71) Required: No PolicyNames A list of policies enabled for this listener. An empty list indicates that no policies are enabled. Type: String list Required: No
LoadBalancerAttributes Description The LoadBalancerAttributes data type.
Contents AccessLog The name of the load balancer attribute. If enabled, the load balancer captures detailed information of all the requests and delivers the information to the Amazon S3 bucket you specify. For more information, see Enable Access Logs. Type: AccessLog (p. 60) API Version 2012-06-01 72
Elastic Load Balancing API Reference LoadBalancerDescription
Required: No ConnectionDraining The name of the load balancer attribute. If enabled, the load balancer allows existing requests to complete before the load balancer shifts traffic away from a deregistered or unhealthy back-end instance. For more information, see Enable Connection Draining. Type: ConnectionDraining (p. 63) Required: No CrossZoneLoadBalancing The name of the load balancer attribute. If enabled, the load balancer routes the request traffic evenly across all back-end instances regardless of the Availability Zones. For more information, see Enable Cross-Zone Load Balancing. Type: CrossZoneLoadBalancing (p. 64) Required: No
LoadBalancerDescription Description Contains the result of a successful invocation of DescribeLoadBalancers (p. 39).
Contents AvailabilityZones Specifies a list of Availability Zones. Type: String list Required: No BackendServerDescriptions Contains a list of back-end server descriptions. Type: BackendServerDescription (p. 62) list Required: No CanonicalHostedZoneName Provides the name of the Amazon Route 53 hosted zone that is associated with the load balancer. For information on how to associate your load balancer with a hosted zone, go to Using Domain Names With Elastic Load Balancing in the Elastic Load Balancing Developer Guide. Type: String Required: No CanonicalHostedZoneNameID Provides the ID of the Amazon Route 53 hosted zone name that is associated with the load balancer. For information on how to associate or disassociate your load balancer with a hosted zone, go to Using Domain Names With Elastic Load Balancing in the Elastic Load Balancing Developer Guide. Type: String API Version 2012-06-01 73
Elastic Load Balancing API Reference Contents
Required: No CreatedTime Provides the date and time the load balancer was created. Type: DateTime Required: No DNSName Specifies the external DNS name associated with the load balancer. Type: String Required: No HealthCheck Specifies information regarding the various health probes conducted on the load balancer. Type: HealthCheck (p. 68) Required: No Instances Provides a list of EC2 instance IDs for the load balancer. Type: Instance (p. 69) list Required: No ListenerDescriptions LoadBalancerPort, InstancePort, Protocol, InstanceProtocol, and PolicyNames are returned in a list of tuples in the ListenerDescriptions element. Type: ListenerDescription (p. 72) list Required: No LoadBalancerName Specifies the name associated with the load balancer. Type: String Required: No Policies Provides a list of policies defined for the load balancer. Type: Policies (p. 76) Required: No Scheme Specifies the type of load balancer. If the Scheme is internet-facing, the load balancer has a publicly resolvable DNS name that resolves to public IP addresses. If the Scheme is internal, the load balancer has a publicly resolvable DNS name that resolves to private IP addresses. This option is only available for load balancers attached to an Amazon VPC. Type: String Required: No
API Version 2012-06-01 74
Elastic Load Balancing API Reference ModifyLoadBalancerAttributesResult
SecurityGroups The security groups the load balancer is a member of (VPC only). Type: String list Required: No SourceSecurityGroup The security group that you can use as part of your inbound rules for your load balancer's back-end Amazon EC2 application instances. To only allow traffic from load balancers, add a security group rule to your back end instance that specifies this source security group as the inbound source. Type: SourceSecurityGroup (p. 80) Required: No Subnets Provides a list of VPC subnet IDs for the load balancer. Type: String list Required: No VPCId Provides the ID of the VPC attached to the load balancer. Type: String Required: No
ModifyLoadBalancerAttributesResult Description The output for the ModifyLoadBalancerAttributes (p. 48) action.
Contents LoadBalancerAttributes The LoadBalancerAttributes data type. Type: LoadBalancerAttributes (p. 72) Required: No LoadBalancerName The name of the load balancer. Type: String Required: No
API Version 2012-06-01 75
Elastic Load Balancing API Reference Policies
Policies Description The policies data type.
Contents AppCookieStickinessPolicies A list of the AppCookieStickinessPolicy (p. 61) objects created with CreateAppCookieStickinessPolicy (p. 9). Type: AppCookieStickinessPolicy (p. 61) list Required: No LBCookieStickinessPolicies A list of LBCookieStickinessPolicy (p. 70) objects created with CreateAppCookieStickinessPolicy (p. 9). Type: LBCookieStickinessPolicy (p. 70) list Required: No OtherPolicies A list of policy names other than the stickiness policies. Type: String list Required: No
PolicyAttribute Description The PolicyAttribute (p. 76) data type. This data type contains a key/value pair that defines properties of a specific policy.
Contents AttributeName The name of the attribute associated with the policy. Type: String Required: No AttributeValue The value of the attribute associated with the policy. Type: String Required: No
API Version 2012-06-01 76
Elastic Load Balancing API Reference PolicyAttributeDescription
PolicyAttributeDescription Description The PolicyAttributeDescription data type. This data type is used to describe the attributes and values associated with a policy.
Contents AttributeName The name of the attribute associated with the policy. Type: String Required: No AttributeValue The value of the attribute associated with the policy. Type: String Required: No
PolicyAttributeTypeDescription Description The PolicyAttributeTypeDescription data type. This data type is used to describe values that are acceptable for the policy attribute.
Contents AttributeName The name of the attribute associated with the policy type. Type: String Required: No AttributeType The type of attribute. For example, Boolean, Integer, etc. Type: String Required: No Cardinality The cardinality of the attribute. Valid Values: • ONE(1) : Single value required • ZERO_OR_ONE(0..1) : Up to one value can be supplied • ZERO_OR_MORE(0..*) : Optional. Multiple values are allowed • ONE_OR_MORE(1..*0) : Required. Multiple values are allowed Type: String
API Version 2012-06-01 77
Elastic Load Balancing API Reference PolicyDescription
Required: No DefaultValue The default value of the attribute, if applicable. Type: String Required: No Description A human-readable description of the attribute. Type: String Required: No
PolicyDescription Description The PolicyDescription data type.
Contents PolicyAttributeDescriptions A list of policy attribute description structures. Type: PolicyAttributeDescription (p. 77) list Required: No PolicyName The name of the policy associated with the load balancer. Type: String Required: No PolicyTypeName The name of the policy type associated with the load balancer. Type: String Required: No
PolicyTypeDescription Description The PolicyTypeDescription (p. 78) data type.
Contents Description A human-readable description of the policy type.
API Version 2012-06-01 78
Elastic Load Balancing API Reference RegisterInstancesWithLoadBalancerResult
Type: String Required: No PolicyAttributeTypeDescriptions The description of the policy attributes associated with the load balancer policies defined by the Elastic Load Balancing service. Type: PolicyAttributeTypeDescription (p. 77) list Required: No PolicyTypeName The name of the policy type. Type: String Required: No
RegisterInstancesWithLoadBalancerResult Description The output for the RegisterInstancesWithLoadBalancer (p. 51) action.
Contents Instances An updated list of instances for the load balancer. Type: Instance (p. 69) list Required: No
SetLoadBalancerListenerSSLCertificateResult Description The output for the SetLoadBalancerListenerSSLCertificate (p. 53) action.
Contents
SetLoadBalancerPoliciesForBackendServerResult Description The output for the SetLoadBalancerPoliciesForBackendServer (p. 55) action.
API Version 2012-06-01 79
Elastic Load Balancing API Reference Contents
Contents
SetLoadBalancerPoliciesOfListenerResult Description The output for the SetLoadBalancerPoliciesOfListener (p. 57) action.
Contents
SourceSecurityGroup Description This data type is used as a response element in the DescribeLoadBalancers (p. 39) action. For information about Elastic Load Balancing security groups, go to Using Security Groups With Elastic Load Balancing in the Elastic Load Balancing Developer Guide.
Contents GroupName Name of the source security group. Use this value for the --source-group parameter of the ec2-authorize command in the Amazon EC2 command line tool. Type: String Required: No OwnerAlias Owner of the source security group. Use this value for the --source-group-user parameter of the ec2-authorize command in the Amazon EC2 command line tool. Type: String Required: No
API Version 2012-06-01 80
Elastic Load Balancing API Reference
Common Parameters This section lists the request parameters that all actions use. Any action-specific parameters are listed in the topic for the action. Action The action to be performed. Default: None Type: string Required: Yes AuthParams The parameters that are required to authenticate a Conditional request. Contains: • AWSAccessKeyID • SignatureVersion • Timestamp • Signature Default: None Required: Conditional AWSAccessKeyId The access key ID that corresponds to the secret access key that you used to sign the request. Default: None Type: string Required: Yes Expires The date and time when the request signature expires, expressed in the format YYYY-MM-DDThh:mm:ssZ, as specified in the ISO 8601 standard. Condition: Requests must include either Timestamp or Expires, but not both. Default: None Type: string
API Version 2012-06-01 81
Elastic Load Balancing API Reference
Required: Conditional SecurityToken The temporary security token that was obtained through a call to AWS Security Token Service. For a list of services that support AWS Security Token Service, go to Using Temporary Security Credentials to Access AWS in Using Temporary Security Credentials. Default: None Type: string Required: No Signature The digital signature that you created for the request. For information about generating a signature, go to the service's developer documentation. Default: None Type: string Required: Yes SignatureMethod The hash algorithm that you used to create the request signature. Default: None Type: string Valid Values: HmacSHA256 | HmacSHA1 Required: Yes SignatureVersion The signature version you use to sign the request. Set this to the value that is recommended for your service. Default: None Type: string Required: Yes Timestamp The date and time when the request was signed, expressed in the format YYYY-MM-DDThh:mm:ssZ, as specified in the ISO 8601 standard. Condition: Requests must include either Timestamp or Expires, but not both. Default: None Type: string Required: Conditional Version The API version that the request is written for, expressed in the format YYYY-MM-DD. Default: None Type: string Required: Yes
API Version 2012-06-01 82
Elastic Load Balancing API Reference
Common Parameters for Signature V4 Signing The following table lists the parameters that all actions use for signing Signature Version 4 requests. Any action-specific parameters are listed in the topic for that action. To view sample requests, see Examples of Signed Signature Version 4 Requests or Signature Version 4 Test Suite in the Amazon Web Services General Reference . Action The action to be performed. Type: string Required: Yes Version The API version that the request is written for, expressed in the format YYYY-MM-DD. Type: string Required: Yes X-Amz-Algorithm The hash algorithm that you used to create the request signature. Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Valid Values: AWS4-HMAC-SHA256 Required: Conditional X-Amz-Credential The credential scope value, which is a string that includes your access key, the date, the region you are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request. For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web Services General Reference.
API Version 2012-06-01 83
Elastic Load Balancing API Reference
Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional X-Amz-Date The date that is used to create the signature. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value: 20120325T120000Z. Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is not required. When X-Amz-Date is used, it always overrides the value of the Date header. For more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General Reference. Type: string Required: Conditional X-Amz-Security-Token The temporary security token that was obtained through a call to AWS Security Token Service. For a list of services that support AWS Security Token Service, go to Using Temporary Security Credentials to Access AWS in Using Temporary Security Credentials. Condition: If you're using temporary security credentials from the AWS Security Token Service, you must include the security token. Type: string Required: Conditional X-Amz-Signature Specifies the hex-encoded signature that was calculated from the string to sign and the derived signing key. Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional X-Amz-SignedHeaders Specifies all the HTTP headers that were included as part of the canonical request. For more information about specifying signed headers, see Task 1: Create a Canonical Request For Signature Version 4 in the Amazon Web Services General Reference . Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional
API Version 2012-06-01 84
Elastic Load Balancing API Reference
Common Errors This section lists the common errors that all actions return. Any action-specific errors are listed in the topic for the action. IncompleteSignature The request signature does not conform to AWS standards. HTTP Status Code: 400 InternalFailure The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 InvalidAction The action or operation requested is invalid. Verify that the action is typed correctly. HTTP Status Code: 400 InvalidClientTokenId The X.509 certificate or AWS access key ID provided does not exist in our records. HTTP Status Code: 403 InvalidParameterCombination Parameters that must not be used together were used together. HTTP Status Code: 400 InvalidParameterValue An invalid or out-of-range value was supplied for the input parameter. HTTP Status Code: 400 InvalidQueryParameter The AWS query string is malformed or does not adhere to AWS standards. HTTP Status Code: 400 MalformedQueryString The query string contains a syntax error. HTTP Status Code: 404 MissingAction The request is missing an action or a required parameter.
API Version 2012-06-01 85
Elastic Load Balancing API Reference
HTTP Status Code: 400 MissingAuthenticationToken The request must contain either a valid (registered) AWS access key ID or X.509 certificate. HTTP Status Code: 403 MissingParameter A required parameter for the specified action is not supplied. HTTP Status Code: 400 OptInRequired The AWS access key ID needs a subscription for the service. HTTP Status Code: 403 RequestExpired The request reached the service more than 15 minutes after the date stamp on the request or more than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp on the request is more than 15 minutes in the future. HTTP Status Code: 400 ServiceUnavailable The request has failed due to a temporary failure of the server. HTTP Status Code: 503 Throttling The request was denied due to request throttling. HTTP Status Code: 400 ValidationError The input fails to satisfy the constraints specified by an AWS service. HTTP Status Code: 400
API Version 2012-06-01 86
Elastic Load Balancing API Reference
Elastic Load Balancing: API Reference Copyright © 2013 Amazon Web Services, Inc. and/or its affiliates. All rights reserved. The following are trademarks of Amazon Web Services, Inc.: Amazon, Amazon Web Services Design, AWS, Amazon CloudFront, Cloudfront, Amazon DevPay, DynamoDB, ElastiCache, Amazon EC2, Amazon Elastic Compute Cloud, Amazon Glacier, Kindle, Kindle Fire, AWS Marketplace Design, Mechanical Turk, Amazon Redshift, Amazon Route 53, Amazon S3, Amazon VPC. In addition, Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other countries. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.
Elastic Load Balancing API Reference
Welcome ................................................................................................................................................. 1 Actions .................................................................................................................................................... 2 ApplySecurityGroupsToLoadBalancer .................................................................................................... 3 AttachLoadBalancerToSubnets .............................................................................................................. 5 ConfigureHealthCheck ............................................................................................................................ 7 CreateAppCookieStickinessPolicy .......................................................................................................... 9 CreateLBCookieStickinessPolicy .......................................................................................................... 11 CreateLoadBalancer ............................................................................................................................. 13 CreateLoadBalancerListeners .............................................................................................................. 19 CreateLoadBalancerPolicy ................................................................................................................... 21 DeleteLoadBalancer ............................................................................................................................. 23 DeleteLoadBalancerListeners ............................................................................................................... 24 DeleteLoadBalancerPolicy .................................................................................................................... 25 DeregisterInstancesFromLoadBalancer ............................................................................................... 26 DescribeInstanceHealth ....................................................................................................................... 28 DescribeLoadBalancerAttributes .......................................................................................................... 31 DescribeLoadBalancerPolicies ............................................................................................................. 33 DescribeLoadBalancerPolicyTypes ...................................................................................................... 36 DescribeLoadBalancers ....................................................................................................................... 39 DetachLoadBalancerFromSubnets ....................................................................................................... 42 DisableAvailabilityZonesForLoadBalancer ............................................................................................ 44 EnableAvailabilityZonesForLoadBalancer ............................................................................................ 46 ModifyLoadBalancerAttributes .............................................................................................................. 48 RegisterInstancesWithLoadBalancer .................................................................................................... 51 SetLoadBalancerListenerSSLCertificate .............................................................................................. 53 SetLoadBalancerPoliciesForBackendServer ........................................................................................ 55 SetLoadBalancerPoliciesOfListener ..................................................................................................... 57 Data Types ............................................................................................................................................ 59 AccessLog ............................................................................................................................................ 60 AppCookieStickinessPolicy ................................................................................................................... 61 ApplySecurityGroupsToLoadBalancerResult ........................................................................................ 61 AttachLoadBalancerToSubnetsResult .................................................................................................. 62 BackendServerDescription ................................................................................................................... 62 ConfigureHealthCheckResult ............................................................................................................... 62 ConnectionDraining .............................................................................................................................. 63 CreateAppCookieStickinessPolicyResult .............................................................................................. 63 CreateLBCookieStickinessPolicyResult ................................................................................................ 63 CreateLoadBalancerListenersResult .................................................................................................... 63 CreateLoadBalancerPolicyResult ......................................................................................................... 64 CreateLoadBalancerResult ................................................................................................................... 64 CrossZoneLoadBalancing .................................................................................................................... 64 DeleteLoadBalancerListenersResult .................................................................................................... 65 DeleteLoadBalancerPolicyResult .......................................................................................................... 65 DeleteLoadBalancerResult ................................................................................................................... 65 DeregisterInstancesFromLoadBalancerResult ..................................................................................... 65 DescribeInstanceHealthResult ............................................................................................................. 66 DescribeLoadBalancerAttributesResult ................................................................................................ 66 DescribeLoadBalancerPoliciesResult ................................................................................................... 66 DescribeLoadBalancerPolicyTypesResult ............................................................................................ 67 DescribeLoadBalancersResult ............................................................................................................. 67 DetachLoadBalancerFromSubnetsResult ............................................................................................ 67 DisableAvailabilityZonesForLoadBalancerResult ................................................................................. 68 EnableAvailabilityZonesForLoadBalancerResult .................................................................................. 68 HealthCheck ......................................................................................................................................... 68 Instance ................................................................................................................................................ 69 InstanceState ........................................................................................................................................ 70 LBCookieStickinessPolicy ..................................................................................................................... 70 Listener ................................................................................................................................................. 71 API Version 2012-06-01 3
Elastic Load Balancing API Reference
ListenerDescription ............................................................................................................................... 72 LoadBalancerAttributes ........................................................................................................................ 72 LoadBalancerDescription ..................................................................................................................... 73 ModifyLoadBalancerAttributesResult .................................................................................................... 75 Policies ................................................................................................................................................. 76 PolicyAttribute ....................................................................................................................................... 76 PolicyAttributeDescription ..................................................................................................................... 77 PolicyAttributeTypeDescription ............................................................................................................. 77 PolicyDescription .................................................................................................................................. 78 PolicyTypeDescription ........................................................................................................................... 78 RegisterInstancesWithLoadBalancerResult ......................................................................................... 79 SetLoadBalancerListenerSSLCertificateResult .................................................................................... 79 SetLoadBalancerPoliciesForBackendServerResult .............................................................................. 79 SetLoadBalancerPoliciesOfListenerResult ........................................................................................... 80 SourceSecurityGroup ........................................................................................................................... 80 Common Parameters ............................................................................................................................ 81 Common Parameters for Signature V4 Signing .................................................................................... 83 Common Errors .................................................................................................................................... 85
API Version 2012-06-01 4
Elastic Load Balancing API Reference
Welcome Elastic Load Balancing is a cost-effective and easy to use web service to help you improve the availability and scalability of your application running on Amazon Elastic Cloud Compute (Amazon EC2). It makes it easy for you to distribute application loads between two or more EC2 instances. Elastic Load Balancing supports the growth in traffic of your application by enabling availability through redundancy. This guide provides detailed information about Elastic Load Balancing actions, data types, and parameters that can be used for sending a query request. Query requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and a query parameter named Action or Operation. Action is used throughout this documentation, although Operation is supported for backward compatibility with other AWS Query APIs. For detailed information on constructing a query request using the actions, data types, and parameters mentioned in this guide, go to Using the Query API in the Elastic Load Balancing Developer Guide. For detailed information about Elastic Load Balancing features and their associated actions, go to Using Elastic Load Balancing in the Elastic Load Balancing Developer Guide. This reference guide is based on the current WSDL, which is available at: http://ec2-downloads.s3.amazonaws.com/ElasticLoadBalancing.wsdl Endpoints The examples in this guide assume that your load balancers are created in the US East (Northern Virginia) region and use us-east-1 as the endpoint. You can create your load balancers in other AWS regions. For information about regions and endpoints supported by Elastic Load Balancing, see Regions and Endpoints in the Amazon Web Services General Reference. This document was last updated on March 15, 2014.
API Version 2012-06-01 1
Elastic Load Balancing API Reference
Actions The following actions are supported: • • • • • • • • • • • • • • • • • •
ApplySecurityGroupsToLoadBalancer (p. 3) AttachLoadBalancerToSubnets (p. 5) ConfigureHealthCheck (p. 7) CreateAppCookieStickinessPolicy (p. 9) CreateLBCookieStickinessPolicy (p. 11) CreateLoadBalancer (p. 13) CreateLoadBalancerListeners (p. 19) CreateLoadBalancerPolicy (p. 21) DeleteLoadBalancer (p. 23) DeleteLoadBalancerListeners (p. 24) DeleteLoadBalancerPolicy (p. 25) DeregisterInstancesFromLoadBalancer (p. 26) DescribeInstanceHealth (p. 28) DescribeLoadBalancerAttributes (p. 31) DescribeLoadBalancerPolicies (p. 33) DescribeLoadBalancerPolicyTypes (p. 36) DescribeLoadBalancers (p. 39) DetachLoadBalancerFromSubnets (p. 42)
• DisableAvailabilityZonesForLoadBalancer (p. 44) • EnableAvailabilityZonesForLoadBalancer (p. 46) • ModifyLoadBalancerAttributes (p. 48) • RegisterInstancesWithLoadBalancer (p. 51) • SetLoadBalancerListenerSSLCertificate (p. 53) • SetLoadBalancerPoliciesForBackendServer (p. 55) • SetLoadBalancerPoliciesOfListener (p. 57)
API Version 2012-06-01 2
Elastic Load Balancing API Reference ApplySecurityGroupsToLoadBalancer
ApplySecurityGroupsToLoadBalancer Description Associates one or more security groups with your load balancer in Amazon Virtual Private Cloud (Amazon VPC). The provided security group IDs will override any currently applied security groups. For more information, see Manage Security Groups in Amazon VPC in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the load balancer.The name must be unique within the set of load balancers associated with your AWS account. Type: String Required: Yes SecurityGroups.member.N A list of security group IDs to associate with your load balancer in VPC. The security group IDs must be provided as the ID and not the security group name (For example, sg-1234). Type: String list Required: Yes
Response Elements The following element is returned in a structure named ApplySecurityGroupsToLoadBalancerResult. SecurityGroups A list of security group IDs associated with your load balancer. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 InvalidSecurityGroup One or more specified security groups do not exist.
API Version 2012-06-01 3
Elastic Load Balancing API Reference Examples
HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?SecurityGroups.member.1=sg-123456789 &LoadBalancerName=my-test-vpc-loadbalancer &Version=2012-06-01 &Action=ApplySecurityGroupsToLoadBalancer &AUTHPARAMS
Sample Response <ApplySecurityGroupsToLoadBalancerResponse xmlns="http://elasticloadbalan cing.amazonaws.com/doc/2012-06-01/"> <ApplySecurityGroupsToLoadBalancerResult> <SecurityGroups> <member>sg-123456789 06b5decc-102a-11e3-9ad6-bf3e4EXAMPLE
API Version 2012-06-01 4
Elastic Load Balancing API Reference AttachLoadBalancerToSubnets
AttachLoadBalancerToSubnets Description Adds one or more subnets to the set of configured subnets in the Amazon Virtual Private Cloud (Amazon VPC) for the load balancer. The load balancers evenly distribute requests across all of the registered subnets. For more information, see Deploy Elastic Load Balancing in Amazon VPC in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the load balancer.The name must be unique within the set of load balancers associated with your AWS account. Type: String Required: Yes Subnets.member.N A list of subnet IDs to add for the load balancer. You can add only one subnet per Availability Zone. Type: String list Required: Yes
Response Elements The following element is returned in a structure named AttachLoadBalancerToSubnetsResult. Subnets A list of subnet IDs attached to the load balancer. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 InvalidSubnet The VPC has no Internet gateway. HTTP Status Code: 400
API Version 2012-06-01 5
Elastic Load Balancing API Reference Examples
SubnetNotFound One or more subnets were not found. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?Subnets.member.1=subnet-3561b05e &LoadBalancerName=my-test-vpc-loadbalancer &Version=2012-06-01 &Action=AttachLoadBalancerToSubnets &AUTHPARAMS
Sample Response <Subnets> <member>subnet-119f0078 <member>subnet-3561b05e 07b1ecbc-1100-11e3-acaf-dd7edEXAMPLE
API Version 2012-06-01 6
Elastic Load Balancing API Reference ConfigureHealthCheck
ConfigureHealthCheck Description Specifies the health check settings to use for evaluating the health state of your back-end instances. For more information, see Health Check in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). HealthCheck A structure containing the configuration information for the new healthcheck. Type: HealthCheck (p. 68) Required: Yes LoadBalancerName The mnemonic name associated with the load balancer. The name must be unique within the set of load balancers associated with your AWS account. Type: String Required: Yes
Response Elements The following element is returned in a structure named ConfigureHealthCheckResult. HealthCheck The updated healthcheck for the instances. Type: HealthCheck (p. 68)
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?HealthCheck.HealthyThreshold=2 &HealthCheck.UnhealthyThreshold=2
API Version 2012-06-01 7
Elastic Load Balancing API Reference Examples
&LoadBalancerName=MyLoadBalancer &HealthCheck.Target=HTTP:80/ping &HealthCheck.Interval=30 &HealthCheck.Timeout=3 &Version=2012-06-01 &Action=ConfigureHealthCheck &AUTHPARAMS
Sample Response 30 HTTP:80/ping 2 <Timeout>3 2 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 8
Elastic Load Balancing API Reference CreateAppCookieStickinessPolicy
CreateAppCookieStickinessPolicy Description Generates a stickiness policy with sticky session lifetimes that follow that of an application-generated cookie. This policy can be associated only with HTTP/HTTPS listeners. This policy is similar to the policy created by CreateLBCookieStickinessPolicy (p. 11), except that the lifetime of the special Elastic Load Balancing cookie follows the lifetime of the application-generated cookie specified in the policy configuration. The load balancer only inserts a new stickiness cookie when the application response includes a new application cookie. If the application cookie is explicitly removed or expires, the session stops being sticky until a new application cookie is issued.
Note An application client must receive and send two cookies: the application-generated cookie and the special Elastic Load Balancing cookie named AWSELB. This is the default behavior for many common web browsers. For more information, see Enabling Application-Controlled Session Stickiness in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). CookieName Name of the application cookie used for stickiness. Type: String Required: Yes LoadBalancerName The name of the load balancer. Type: String Required: Yes PolicyName The name of the policy being created. The name must be unique within the set of policies for this load balancer. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 9
Elastic Load Balancing API Reference Examples
DuplicatePolicyName Policy with the same name exists for this load balancer. Please choose another name. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 TooManyPolicies Quota for number of policies for this load balancer has already been reached. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?CookieName=MyAppCookie &LoadBalancerName=MyLoadBalancer &PolicyName=MyAppStickyPolicy &Version=2012-06-01 &Action=CreateAppCookieStickinessPolicy &AUTHPARAMS
Sample Response 99a693e9-12b8-11e3-9ad6-bf3e4EXAMPLE
API Version 2012-06-01 10
Elastic Load Balancing API Reference CreateLBCookieStickinessPolicy
CreateLBCookieStickinessPolicy Description Generates a stickiness policy with sticky session lifetimes controlled by the lifetime of the browser (user-agent) or a specified expiration period. This policy can be associated only with HTTP/HTTPS listeners. When a load balancer implements this policy, the load balancer uses a special cookie to track the backend server instance for each request. When the load balancer receives a request, it first checks to see if this cookie is present in the request. If so, the load balancer sends the request to the application server specified in the cookie. If not, the load balancer sends the request to a server that is chosen based on the existing load balancing algorithm. A cookie is inserted into the response for binding subsequent requests from the same user to that server. The validity of the cookie is based on the cookie expiration time, which is specified in the policy configuration. For more information, see Enabling Duration-Based Session Stickiness in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). CookieExpirationPeriod The time period in seconds after which the cookie should be considered stale. Not specifying this parameter indicates that the sticky session will last for the duration of the browser session. Type: Long Required: No LoadBalancerName The name associated with the load balancer. Type: String Required: Yes PolicyName The name of the policy being created. The name must be unique within the set of policies for this load balancer. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 11
Elastic Load Balancing API Reference Examples
DuplicatePolicyName Policy with the same name exists for this load balancer. Please choose another name. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 TooManyPolicies Quota for number of policies for this load balancer has already been reached. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?CookieExpirationPeriod=60 &LoadBalancerName=MyLoadBalancer&PolicyName=MyDurationStickyPolicy &Version=2012-06-01 &Action=CreateLBCookieStickinessPolicy &AUTHPARAMS
Sample Response 99a693e9-12b8-11e3-9ad6-bf3e4EXAMPLE
API Version 2012-06-01 12
Elastic Load Balancing API Reference CreateLoadBalancer
CreateLoadBalancer Description Creates a new load balancer. After the call has completed successfully, a new load balancer is created with a unique Domain Name Service (DNS) name. The DNS name includes the name of the AWS region in which the load balance was created. For example, if your load balancer was created in the United States, the DNS name might end with either of the following: • us-east-1.elb.amazonaws.com (for the Northern Virginia Region) • us-west-1.elb.amazonaws.com (for the Northern California Region) For information about the AWS regions supported by Elastic Load Balancing, see Regions and Endpoints. You can create up to 20 load balancers per region per account. Elastic Load Balancing supports load balancing your Amazon EC2 instances launched within any one of the following platforms: • EC2-Classic For information on creating and managing your load balancers in EC2-Classic, see Deploy Elastic Load Balancing in Amazon EC2-Classic. • EC2-VPC For information on creating and managing your load balancers in EC2-VPC, see Deploy Elastic Load Balancing in Amazon VPC.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). AvailabilityZones.member.N A list of Availability Zones. At least one Availability Zone must be specified. Specified Availability Zones must be in the same EC2 Region as the load balancer. Traffic will be equally distributed across all zones. You can later add more Availability Zones after the creation of the load balancer by calling EnableAvailabilityZonesForLoadBalancer (p. 46) action. Type: String list Required: No Listeners.member.N A list of the following tuples: LoadBalancerPort, InstancePort, and Protocol. Type: Listener (p. 71) list Required: Yes LoadBalancerName The name associated with the load balancer. The name must be unique within your set of load balancers. API Version 2012-06-01 13
Elastic Load Balancing API Reference Response Elements
Type: String Required: Yes Scheme The type of a load balancer. By default, Elastic Load Balancing creates an Internet-facing load balancer with a publicly resolvable DNS name, which resolves to public IP addresses. For more informationabout Internet-facing and Internal load balancers, see Internet-facing and Internal Load Balancers. Specify the value internal for this option to create an internal load balancer with a DNS name that resolves to private IP addresses.
Note This option is only available for load balancers created within EC2-VPC. Type: String Required: No SecurityGroups.member.N The security groups to assign to your load balancer within your VPC. Type: String list Required: No Subnets.member.N A list of subnet IDs in your VPC to attach to your load balancer. Specify one subnet per Availability Zone. Type: String list Required: No
Response Elements The following element is returned in a structure named CreateLoadBalancerResult. DNSName The DNS name for the load balancer. Type: String
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). CertificateNotFound The specified SSL ID does not refer to a valid SSL certificate in the AWS Identity and Access Management Service. HTTP Status Code: 400 DuplicateAccessPointName Load balancer name already exists for this account. Please choose another name. HTTP Status Code: 400
API Version 2012-06-01 14
Elastic Load Balancing API Reference Examples
InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 InvalidScheme Invalid value for scheme. Scheme can only be specified for load balancers in VPC. HTTP Status Code: 400 InvalidSecurityGroup One or more specified security groups do not exist. HTTP Status Code: 400 InvalidSubnet The VPC has no Internet gateway. HTTP Status Code: 400 SubnetNotFound One or more subnets were not found. HTTP Status Code: 400 TooManyAccessPoints The quota for the number of load balancers has already been reached. HTTP Status Code: 400
Examples Create a TCP load balancer in EC2-Classic Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &AvailabilityZones.member.1=us-east-1c &Listeners.member.1.LoadBalancerPort=80 &Listeners.member.1.InstancePort=80 &Listeners.member.1.Protocol=http &Listeners.member.1.InstanceProtocol=http &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
Sample Response MyLoadBalancer-1234567890.us-east-1.elb.amazonaws.com 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 15
Elastic Load Balancing API Reference Examples
Create HTTPS load balancer in EC2-Classic Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyHTTPSLoadBalancer &AvailabilityZones.member.1=us-east-1c &Listeners.member.1.LoadBalancerPort=443 &Listeners.member.1.InstancePort=443 &Listeners.member.1.Protocol=https &Listeners.member.1.InstanceProtocol=https &Listeners.member.1.SSLCertificateId=arn:aws:iam::123456789012:server-certific ate/servercert &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
Sample Response MyHTTPSLoadBalancer-1234567890.us-east-1.elb.amazonaws.com 1549581b-12b7-11e3-895e-1334aEXAMPLE
Create a TCP load balancer in EC2-VPC Sample Request https://elasticloadbalancing.amazonaws.com/?SecurityGroups.member.1=sg-6801da07 &LoadBalancerName=MyVPCLoadBalancer &Listeners.member.1.LoadBalancerPort=80 &Listeners.member.1.InstancePort=80 &Listeners.member.1.Protocol=http &Listeners.member.1.InstanceProtocol=http &Subnets.member.1=subnet-6dec9f03 &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
Sample Response MyVPCLoadBalancer-1234567890.us-east-1.elb.amazonaws.com
API Version 2012-06-01 16
Elastic Load Balancing API Reference Examples
1549581b-12b7-11e3-895e-1334aEXAMPLE
Create an internal TCP load balancer in EC2-VPC Sample Request https://elasticloadbalancing.amazonaws.com/?Scheme=internal &SecurityGroups.member.1=sg-706cb61f &LoadBalancerName=MyInternalLoadBalancer &Listeners.member.1.LoadBalancerPort=80 &Listeners.member.1.InstancePort=80 &Listeners.member.1.Protocol=http &Listeners.member.1.InstanceProtocol=http &Subnets.member.1=subnet-9edc97f0 &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
Sample Response internal-MyInternalLoadBalancer-1234567890.us-east-1.elb.amazon aws.com 1549581b-12b7-11e3-895e-1334aEXAMPLE
Create a TCP load balancer in default VPC Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyDefaultVPCLoad Balancer &AvailabilityZones.member.1=sa-east-1b &Listeners.member.1.LoadBalancerPort=80 &Listeners.member.1.InstancePort=80 &Listeners.member.1.Protocol=http &Listeners.member.1.InstanceProtocol=http &Version=2012-06-01 &Action=CreateLoadBalancer &AUTHPARAMS
API Version 2012-06-01 17
Elastic Load Balancing API Reference Examples
Sample Response MyDefaultVPCLoadBalancer-1234567890.sa.east-1.elb.amazonaws.com 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 18
Elastic Load Balancing API Reference CreateLoadBalancerListeners
CreateLoadBalancerListeners Description Creates one or more listeners on a load balancer for the specified port. If a listener with the given port does not already exist, it will be created; otherwise, the properties of the new listener must match the properties of the existing listener. For more information, see Add a Listener to Your Load Balancer in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). Listeners.member.N A list of LoadBalancerPort, InstancePort, Protocol, and SSLCertificateId items. Type: Listener (p. 71) list Required: Yes LoadBalancerName The name of the load balancer. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 CertificateNotFound The specified SSL ID does not refer to a valid SSL certificate in the AWS Identity and Access Management Service. HTTP Status Code: 400 DuplicateListener A Listener already exists for the given LoadBalancerName and LoadBalancerPort, but with a different InstancePort, Protocol, or SSLCertificateId. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
API Version 2012-06-01 19
Elastic Load Balancing API Reference Examples
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?Listeners.member.1.Protocol=https &Listeners.member.1.LoadBalancerPort=443 &Listeners.member.1.InstancePort=443 &Listeners.member.1.InstanceProtocol=https &Listeners.member.1.SSLCertificateId=arn:aws:iam::123456789012:server-certific ate/servercert &LoadBalancerName=MyHTTPSLoadBalancer &Version=2012-06-01 &Action=CreateLoadBalancerListeners &AUTHPARAMS
Sample Response 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 20
Elastic Load Balancing API Reference CreateLoadBalancerPolicy
CreateLoadBalancerPolicy Description Creates a new policy that contains the necessary attributes depending on the policy type. Policies are settings that are saved for your load balancer and that can be applied to the front-end listener, or the back-end application server, depending on your policy type.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the LoadBalancer for which the policy is being created. Type: String Required: Yes PolicyAttributes.member.N A list of attributes associated with the policy being created. Type: PolicyAttribute (p. 76) list Required: No PolicyName The name of the load balancer policy being created. The name must be unique within the set of policies for this load balancer. Type: String Required: Yes PolicyTypeName The name of the base policy type being used to create this policy. To get the list of policy types, use the DescribeLoadBalancerPolicyTypes (p. 36) action. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 DuplicatePolicyName Policy with the same name exists for this load balancer. Please choose another name. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid.
API Version 2012-06-01 21
Elastic Load Balancing API Reference Examples
HTTP Status Code: 409 PolicyTypeNotFound One or more of the specified policy types do not exist. HTTP Status Code: 400 TooManyPolicies Quota for number of policies for this load balancer has already been reached. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?PolicyAttributes.member.1.Attribute Name=ProxyProtocol &PolicyAttributes.member.1.AttributeValue=true &PolicyTypeName=ProxyProtocolPolicyType &LoadBalancerName=my-test-loadbalancer &PolicyName=EnableProxyProtocol &Version=2012-06-01 &Action=CreateLoadBalancerPolicy &AUTHPARAMS
Sample Response 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 22
Elastic Load Balancing API Reference DeleteLoadBalancer
DeleteLoadBalancer Description Deletes the specified load balancer. If attempting to recreate the load balancer, you must reconfigure all the settings.The DNS name associated with a deleted load balancer will no longer be usable. Once deleted, the name and associated DNS record of the load balancer no longer exist and traffic sent to any of its IP addresses will no longer be delivered to back-end instances. To successfully call this API, you must provide the same account credentials as were used to create the load balancer.
Note By design, if the load balancer does not exist or has already been deleted, a call to DeleteLoadBalancer action still succeeds.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the load balancer. Type: String Required: Yes
API Version 2012-06-01 23
Elastic Load Balancing API Reference DeleteLoadBalancerListeners
DeleteLoadBalancerListeners Description Deletes listeners from the load balancer for the specified port.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The mnemonic name associated with the load balancer. Type: String Required: Yes LoadBalancerPorts.member.N The client port number(s) of the load balancer listener(s) to be removed. Type: Integer list Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 24
Elastic Load Balancing API Reference DeleteLoadBalancerPolicy
DeleteLoadBalancerPolicy Description Deletes a policy from the load balancer. The specified policy must not be enabled for any listeners.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The mnemonic name associated with the load balancer. Type: String Required: Yes PolicyName The mnemonic name for the policy being deleted. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
API Version 2012-06-01 25
Elastic Load Balancing API Reference DeregisterInstancesFromLoadBalancer
DeregisterInstancesFromLoadBalancer Description Deregisters instances from the load balancer. Once the instance is deregistered, it will stop receiving traffic from the load balancer. In order to successfully call this API, the same account credentials as those used to create the load balancer must be provided. For more information, see De-register and Register Amazon EC2 Instances in the Elastic Load Balancing Developer Guide. You can use DescribeLoadBalancers (p. 39) to verify if the instance is deregistered from the load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). Instances.member.N A list of EC2 instance IDs consisting of all instances to be deregistered. Type: Instance (p. 69) list Required: Yes LoadBalancerName The name associated with the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named DeregisterInstancesFromLoadBalancerResult. Instances An updated list of remaining instances registered with the load balancer. Type: Instance (p. 69) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidEndPoint The specified EndPoint is not valid. HTTP Status Code: 400 API Version 2012-06-01 26
Elastic Load Balancing API Reference Examples
Examples Deregister instance i-e3677ad7 from MyHTTPSLoadBalancer load balancer. Sample Request https://elasticloadbalancing.amazonaws.com/?Instances.member.1.InstanceId=ie3677ad7 &LoadBalancerName=MyHTTPSLoadBalancer &Version=2012-06-01 &Action=DeregisterInstancesFromLoadBalancer &AUTHPARAMS
Sample Response <member> i-6ec63d59 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 27
Elastic Load Balancing API Reference DescribeInstanceHealth
DescribeInstanceHealth Description Returns the current state of the specified instances registered with the specified load balancer. If no instances are specified, the state of all the instances registered with the load balancer is returned.
Note You must provide the same account credentials as those that were used to create the load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). Instances.member.N A list of instance IDs whose states are being queried. Type: Instance (p. 69) list Required: No LoadBalancerName The name of the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named DescribeInstanceHealthResult. InstanceStates A list containing health information for the specified instances. Type: InstanceState (p. 70) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidEndPoint The specified EndPoint is not valid. HTTP Status Code: 400
API Version 2012-06-01 28
Elastic Load Balancing API Reference Examples
Examples Description of a healthy (InService) instance Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &Version=2012-06-01 &Action=DescribeInstanceHealth &AUTHPARAMS
Sample Response <member> N/A i-90d8c2a5 <State>InService N/A 1549581b-12b7-11e3-895e-1334aEXAMPLE
Description of an instance with registration in progress Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=DescribeInstanceHealth &AUTHPARAMS
Sample Response <member> Instance registration is still in progress. i-315b7e51 <State>OutOfService ELB
API Version 2012-06-01 29
Elastic Load Balancing API Reference Examples
1549581b-12b7-11e3-895e-1334aEXAMPLE
Description of an unhealthy (OutOfService) instance Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer-2 &Version=2012-06-01 &Action=DescribeInstanceHealth &AUTHPARAMS
Sample Response <member> Instance has failed at least the UnhealthyThreshold number of health checks consecutively. i-fda142c9 <State>OutOfService Instance 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 30
Elastic Load Balancing API Reference DescribeLoadBalancerAttributes
DescribeLoadBalancerAttributes Description Returns detailed information about all of the attributes associated with the specified load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name of the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named DescribeLoadBalancerAttributesResult. LoadBalancerAttributes The load balancer attributes structure. Type: LoadBalancerAttributes (p. 72)
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 LoadBalancerAttributeNotFound The specified load balancer attribute could not be found. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &Version=2012-06-01 &Action=DescribeLoadBalancerAttributes &AUTHPARAMS
API Version 2012-06-01 31
Elastic Load Balancing API Reference Examples
Sample Response <Enabled>true <S3BucketName>my-loadbalancer-logs <S3BucketPrefix>testprefix <EmitInterval>5 <Enabled>true <Enabled>true <Timeout>60 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 32
Elastic Load Balancing API Reference DescribeLoadBalancerPolicies
DescribeLoadBalancerPolicies Description Returns detailed descriptions of the policies. If you specify a load balancer name, the action returns the descriptions of all the policies created for the load balancer. If you specify a policy name associated with your load balancer, the action returns the description of that policy. If you don't specify a load balancer name, the action returns descriptions of the specified sample policies, or descriptions of all the sample policies. The names of the sample policies have the ELBSample- prefix.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The mnemonic name associated with the load balancer. If no name is specified, the operation returns the attributes of either all the sample policies pre-defined by Elastic Load Balancing or the specified sample polices. Type: String Required: No PolicyNames.member.N The names of load balancer policies you've created or Elastic Load Balancing sample policy names. Type: String list Required: No
Response Elements The following element is returned in a structure named DescribeLoadBalancerPoliciesResult. PolicyDescriptions A list of policy description structures. Type: PolicyDescription (p. 78) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 PolicyNotFound One or more specified policies were not found. HTTP Status Code: 400
API Version 2012-06-01 33
Elastic Load Balancing API Reference Examples
Examples Description of all the policies associated with a load balancer Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &Version=2012-06-01 &Action=DescribeLoadBalancerPolicies &AUTHPARAMS
Sample Response <member> MyDurationStickyPolicy LBCookieStickinessPolicyType <member> CookieExpirationPeriod 60 <member> MyAppStickyPolicy AppCookieStickinessPolicyType <member> CookieName MyAppCookie 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
Description of a specified policy associated with the load balancer Sample Request https://elasticloadbalancing.amazonaws.com/?PolicyNames.member.1=EnableProxyPro tocol
API Version 2012-06-01 34
Elastic Load Balancing API Reference Examples
&LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=DescribeLoadBalancerPolicies &AUTHPARAMS
Sample Response <member> EnableProxyProtocol ProxyProtocolPolicyType <member> ProxyProtocol true 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 35
Elastic Load Balancing API Reference DescribeLoadBalancerPolicyTypes
DescribeLoadBalancerPolicyTypes Description Returns meta-information on the specified load balancer policies defined by the Elastic Load Balancing service. The policy types that are returned from this action can be used in a CreateLoadBalancerPolicy (p. 21) action to instantiate specific policy configurations that will be applied to a load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). PolicyTypeNames.member.N Specifies the name of the policy types. If no names are specified, returns the description of all the policy types defined by Elastic Load Balancing service. Type: String list Required: No
Response Elements The following element is returned in a structure named DescribeLoadBalancerPolicyTypesResult. PolicyTypeDescriptions List of policy type description structures of the specified policy type. If no policy type names are specified, returns the description of all the policy types defined by Elastic Load Balancing service. Type: PolicyTypeDescription (p. 78) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). PolicyTypeNotFound One or more of the specified policy types do not exist. HTTP Status Code: 400
API Version 2012-06-01 36
Elastic Load Balancing API Reference Examples
Examples Partial description of all the policy types defined by Elastic Load Balancing for your account Sample Request https://elasticloadbalancing.amazonaws.com/?Version=2012-06-01 &Action=DescribeLoadBalancerPolicyTypes &AUTHPARAMS
Sample Response SSLNegotiationPolicyType < . . . .> BackendServerAuthenticationPolicyType < . . . .> PublicKeyPolicyType < . . . .> AppCookieStickinessPolicyType < . . . .> LBCookieStickinessPolicyType < . . . .> ProxyProtocolPolicyType < . . . .> 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
Description of ProxyProtocolPolicyType Sample Request https://elasticloadbalancing.amazonaws.com/?PolicyTypeNames.member.1=ProxyPro tocolPolicyType &Version=2012-06-01 &Action=DescribeLoadBalancerPolicyTypes &AUTHPARAMS
Sample Response
API Version 2012-06-01 37
Elastic Load Balancing API Reference Examples
<member> <member> ProxyProtocol Boolean ONE ProxyProtocolPolicyType Policy that controls whether to include the IP address and port of the originating request for TCP messages. This policy operates on TCP/SSL listeners only 1549581b-12b7-11e3-895e-1334aEXAMPLE
API Version 2012-06-01 38
Elastic Load Balancing API Reference DescribeLoadBalancers
DescribeLoadBalancers Description Returns detailed configuration information for all the load balancers created for the account. If you specify load balancer names, the action returns configuration information of the specified load balancers.
Note In order to retrieve this information, you must provide the same account credentials that was used to create the load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerNames.member.N A list of load balancer names associated with the account. Type: String list Required: No Marker An optional parameter reserved for future use. Type: String Required: No
Response Elements The following elements are returned in a structure named DescribeLoadBalancersResult. LoadBalancerDescriptions A list of load balancer description structures. Type: LoadBalancerDescription (p. 73) list NextMarker An optional parameter reserved for future use. Type: String
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 39
Elastic Load Balancing API Reference Examples
Examples Description of a specified load balancer Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerNames.member.1=MyLoad Balancer &Version=2012-06-01 &Action=DescribeLoadBalancers &AUTHPARAMS
Sample Response <member> <SecurityGroups/> MyLoadBalancer 2013-05-24T21:15:31.280Z 90 HTTP:80/ 2 <Timeout>60 10 <member> HTTP 80 HTTP 80 <member> i-e4cbe38d <AppCookieStickinessPolicies/> <member>us-east-1a ZZZZZZZZZZZ123X MyLoadBalancer-123456789.us-east1.elb.amazonaws.com
API Version 2012-06-01 40
Elastic Load Balancing API Reference Examples
<Scheme>internet-facing <SourceSecurityGroup> amazon-elb amazon-elb-sg MyLoadBalancer-123456789.us-east-1.elb.amazonaws.com <Subnets/> 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 41
Elastic Load Balancing API Reference DetachLoadBalancerFromSubnets
DetachLoadBalancerFromSubnets Description Removes subnets from the set of configured subnets in the Amazon Virtual Private Cloud (Amazon VPC) for the load balancer. After a subnet is removed all of the EC2 instances registered with the load balancer that are in the removed subnet will go into the OutOfService state. When a subnet is removed, the load balancer will balance the traffic among the remaining routable subnets for the load balancer.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name associated with the load balancer to be detached. Type: String Required: Yes Subnets.member.N A list of subnet IDs to remove from the set of configured subnets for the load balancer. Type: String list Required: Yes
Response Elements The following element is returned in a structure named DetachLoadBalancerFromSubnetsResult. Subnets A list of subnet IDs the load balancer is now attached to. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
API Version 2012-06-01 42
Elastic Load Balancing API Reference Examples
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?Subnets.member.1=subnet-119f0078 &LoadBalancerName=my-test-vpc-loadbalancer &Version=2012-06-01 &Action=DetachLoadBalancerFromSubnets &AUTHPARAMS
Sample Response <Subnets> <member>subnet-159f007c <member>subnet-3561b05e 07b1ecbc-1100-11e3-acaf-dd7edEXAMPLE
API Version 2012-06-01 43
Elastic Load Balancing API Reference DisableAvailabilityZonesForLoadBalancer
DisableAvailabilityZonesForLoadBalancer Description Removes the specified EC2 Availability Zones from the set of configured Availability Zones for the load balancer. There must be at least one Availability Zone registered with a load balancer at all times. Once an Availability Zone is removed, all the instances registered with the load balancer that are in the removed Availability Zone go into the OutOfService state. Upon Availability Zone removal, the load balancer attempts to equally balance the traffic among its remaining usable Availability Zones. Trying to remove an Availability Zone that was not associated with the load balancer does nothing. For more information, see Disable an Availability Zone from a Load-Balanced Application in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). AvailabilityZones.member.N A list of Availability Zones to be removed from the load balancer.
Note There must be at least one Availability Zone registered with a load balancer at all times. Specified Availability Zones must be in the same region. Type: String list Required: Yes LoadBalancerName The name associated with the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named DisableAvailabilityZonesForLoadBalancerResult. AvailabilityZones A list of updated Availability Zones for the load balancer. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found.
API Version 2012-06-01 44
Elastic Load Balancing API Reference Examples
HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?AvailabilityZones.member.1=us-east1a &LoadBalancerName=MyHTTPSLoadBalancer &Version=2012-06-01 &Action=DisableAvailabilityZonesForLoadBalancer &AUTHPARAMS
Sample Response <member>us-east-1b ba6267d5-2566-11e3-9c6d-eb728EXAMPLE
API Version 2012-06-01 45
Elastic Load Balancing API Reference EnableAvailabilityZonesForLoadBalancer
EnableAvailabilityZonesForLoadBalancer Description Adds one or more EC2 Availability Zones to the load balancer. The load balancer evenly distributes requests across all its registered Availability Zones that contain instances.
Note The new EC2 Availability Zones to be added must be in the same EC2 Region as the Availability Zones for which the load balancer was created. For more information, see Expand a Load Balanced Application to an Additional Availability Zone in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). AvailabilityZones.member.N A list of new Availability Zones for the load balancer. Each Availability Zone must be in the same region as the load balancer. Type: String list Required: Yes LoadBalancerName The name associated with the load balancer. Type: String Required: Yes
Response Elements The following element is returned in a structure named EnableAvailabilityZonesForLoadBalancerResult. AvailabilityZones An updated list of Availability Zones for the load balancer. Type: String list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400
API Version 2012-06-01 46
Elastic Load Balancing API Reference Examples
Examples Enable Availability Zone us-east-1c for my-test-loadbalancer. Sample Request https://elasticloadbalancing.amazonaws.com/?AvailabilityZones.member.1=us-east1c &LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=EnableAvailabilityZonesForLoadBalancer &AUTHPARAMS
Sample Response <EnableAvailabilityZonesForLoadBalancerResponse xmlns="http://elasticloadbalan cing.amazonaws.com/doc/2012-06-01/"> <EnableAvailabilityZonesForLoadBalancerResult> <member>us-east-1a <member>us-east-1c 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 47
Elastic Load Balancing API Reference ModifyLoadBalancerAttributes
ModifyLoadBalancerAttributes Description Modifies the attributes of a specified load balancer. You can modify the load balancer attributes, such as AccessLogs, ConnectionDraining, and CrossZoneLoadBalancing by either enabling or disabling them. For information on cross-zone load balancing, see Request Routing and for information on connection draining, see Connection Draining in the Concepts section of the Elastic Load Balancer Developer Guide. For information on access logs, see Access Logs.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerAttributes Attributes of the load balancer. Type: LoadBalancerAttributes (p. 72) Required: Yes LoadBalancerName The name of the load balancer. Type: String Required: Yes
Response Elements The following elements are returned in a structure named ModifyLoadBalancerAttributesResult. LoadBalancerAttributes The LoadBalancerAttributes data type. Type: LoadBalancerAttributes (p. 72) LoadBalancerName The name of the load balancer. Type: String
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid.
API Version 2012-06-01 48
Elastic Load Balancing API Reference Examples
HTTP Status Code: 409 LoadBalancerAttributeNotFound The specified load balancer attribute could not be found. HTTP Status Code: 400
Examples Enable Cross-Zone Load Balancing Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &LoadBalancerAttributes.CrossZoneLoadBalancing.Enabled=true &Version=2012-06-01 &Action=ModifyLoadBalancerAttributes &AUTHPARAMS
Sample Response <ModifyLoadBalancerAttributesResult> MyLoadBalancer <Enabled>true 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
Enable Access Log Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &LoadBalancerAttributes.AccessLog.Enabled=true &LoadBalancerAttributes.AccessLog.S3BucketName=my-loadbalancer-logs &LoadBalancerAttributes.AccessLog.S3BucketPrefix=my-bucket-prefix/prod &LoadBalancerAttributes.AccessLog.EmitInterval=60 &Version=2012-06-01 &Action=ModifyLoadBalancerAttributes &AUTHPARAMS
API Version 2012-06-01 49
Elastic Load Balancing API Reference Examples
Sample Response <ModifyLoadBalancerAttributesResult> MyLoadBalancer <Enabled>true <S3BucketName>my-loadbalancer-logs <S3BucketPrefix>my-bucket-prefix/prod <EmitInterval>60 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
Enable Connection Draining Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyLoadBalancer &LoadBalancerAttributes.ConnectionDraining.Enabled=true &LoadBalancerAttributes.ConnectionDraining.Timeout=60 &Version=2012-06-01 &Action=ModifyLoadBalancerAttributes &AUTHPARAMS
Sample Response <ModifyLoadBalancerAttributesResult> MyLoadBalancer <Enabled>true <Timeout>60 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 50
Elastic Load Balancing API Reference RegisterInstancesWithLoadBalancer
RegisterInstancesWithLoadBalancer Description Adds new instances to the load balancer. Once the instance is registered, it starts receiving traffic and requests from the load balancer. Any instance that is not in any of the Availability Zones registered for the load balancer will be moved to the OutOfService state. It will move to the InService state when the Availability Zone is added to the load balancer. When an instance registered with a load balancer is stopped and then restarted, the IP addresses associated with the instance changes. Elastic Load Balancing cannot recognize the new IP address, which prevents it from routing traffic to the instances. We recommend that you de-register your Amazon EC2 instances from your load balancer after you stop your instance, and then register the load balancer with your instance after you've restarted. To de-register your instances from load balancer, use DeregisterInstancesFromLoadBalancer (p. 26) action. For more information, see De-register and Register Amazon EC2 Instances in the Elastic Load Balancing Developer Guide.
Note In order for this call to be successful, you must provide the same account credentials as those that were used to create the load balancer.
Note Completion of this API does not guarantee that operation has completed. Rather, it means that the request has been registered and the changes will happen shortly. You can use DescribeLoadBalancers (p. 39) or DescribeInstanceHealth (p. 28) action to check the state of the newly registered instances.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). Instances.member.N A list of instance IDs that should be registered with the load balancer. Type: Instance (p. 69) list Required: Yes LoadBalancerName The name associated with the load balancer. The name must be unique within your set of load balancers. Type: String Required: Yes
Response Elements The following element is returned in a structure named RegisterInstancesWithLoadBalancerResult. Instances An updated list of instances for the load balancer.
API Version 2012-06-01 51
Elastic Load Balancing API Reference Errors
Type: Instance (p. 69) list
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidEndPoint The specified EndPoint is not valid. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?Instances.member.1.InstanceId=i315b7e51 &LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=RegisterInstancesWithLoadBalancer &AUTHPARAMS
Sample Response <member> i-315b7e51 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 52
Elastic Load Balancing API Reference SetLoadBalancerListenerSSLCertificate
SetLoadBalancerListenerSSLCertificate Description Sets the certificate that terminates the specified listener's SSL connections. The specified certificate replaces any prior certificate that was used on the same load balancer and port. For more information on updating your SSL certificate, see Updating an SSL Certificate for a Load Balancer in the Elastic Load Balancing Developer Guide.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name of the load balancer. Type: String Required: Yes LoadBalancerPort The port that uses the specified SSL certificate. Type: Integer Required: Yes SSLCertificateId The Amazon Resource Number (ARN) of the SSL certificate chain to use. For more information on SSL certificates, see Managing Server Certificates in the AWS Identity and Access Management User Guide. Type: String Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 CertificateNotFound The specified SSL ID does not refer to a valid SSL certificate in the AWS Identity and Access Management Service. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 ListenerNotFound Load balancer does not have a listener configured at the given port.
API Version 2012-06-01 53
Elastic Load Balancing API Reference Examples
HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?LoadBalancerName=MyInternalLoadBal ancer &SSLCertificateId=arn:aws:iam::123456789012:server-certificate/testcert &LoadBalancerPort=443 &Version=2012-06-01 &Action=SetLoadBalancerListenerSSLCertificate &AUTHPARAMS
Sample Response <SetLoadBalancerListenerSSLCertificateResponse xmlns="http://elasticloadbalan cing.amazonaws.com/doc/2012-06-01/"> <SetLoadBalancerListenerSSLCertificateResult/> 83c88b9d-12b7-11e3-8b82-87b12EXAMPLE
API Version 2012-06-01 54
Elastic Load Balancing API Reference SetLoadBalancerPoliciesForBackendServer
SetLoadBalancerPoliciesForBackendServer Description Replaces the current set of policies associated with a port on which the back-end server is listening with a new set of policies. After the policies have been created using CreateLoadBalancerPolicy (p. 21), they can be applied here as a list. At this time, only the back-end server authentication policy type can be applied to the back-end ports; this policy type is composed of multiple public key policies.
Note The SetLoadBalancerPoliciesForBackendServer replaces the current set of policies associated with the specified instance port. Every time you use this action to enable the policies, use the PolicyNames parameter to list all the policies you want to enable. You can use DescribeLoadBalancers (p. 39) or DescribeLoadBalancerPolicies (p. 33) action to verify that the policy has been associated with the back-end server.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). InstancePort The port number associated with the back-end server. Type: Integer Required: Yes LoadBalancerName The mnemonic name associated with the load balancer. This name must be unique within the set of your load balancers. Type: String Required: Yes PolicyNames.member.N List of policy names to be set. If the list is empty, then all current polices are removed from the back-end server. Type: String list Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409
API Version 2012-06-01 55
Elastic Load Balancing API Reference Examples
PolicyNotFound One or more specified policies were not found. HTTP Status Code: 400
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?InstancePort=80 &PolicyNames.member.1=EnableProxyProtocol &PolicyNames.member.2=MyPolicyName2 &PolicyNames.member.3=MyPolicyName3 &LoadBalancerName=my-test-loadbalancer &Version=2012-06-01 &Action=SetLoadBalancerPoliciesForBackendServer &AUTHPARAMS
Sample Response <SetLoadBalancerPoliciesForBackendServerResponse xmlns="http://elasticloadbal ancing.amazonaws.com/doc/2012-06-01/"> <SetLoadBalancerPoliciesForBackendServerResult/> 0eb9b381-dde0-11e2-8d78-6ddbaEXAMPLE
API Version 2012-06-01 56
Elastic Load Balancing API Reference SetLoadBalancerPoliciesOfListener
SetLoadBalancerPoliciesOfListener Description Associates, updates, or disables a policy with a listener on the load balancer. You can associate multiple policies with a listener.
Request Parameters For information about the common parameters that all actions use, see Common Parameters (p. 81). LoadBalancerName The name of the load balancer. Type: String Required: Yes LoadBalancerPort The external port of the load balancer to associate the policy. Type: Integer Required: Yes PolicyNames.member.N List of policies to be associated with the listener. If the list is empty, the current policy is removed from the listener. Type: String list Required: Yes
Errors For information about the errors that are common to all actions, see Common Errors (p. 85). AccessPointNotFound The specified load balancer could not be found. HTTP Status Code: 400 InvalidConfigurationRequest Requested configuration change is invalid. HTTP Status Code: 409 ListenerNotFound Load balancer does not have a listener configured at the given port. HTTP Status Code: 400 PolicyNotFound One or more specified policies were not found. HTTP Status Code: 400
API Version 2012-06-01 57
Elastic Load Balancing API Reference Examples
Examples Sample Request https://elasticloadbalancing.amazonaws.com/?PolicyNames.member.1=MySSLNegoti ationPolicy &LoadBalancerName=MyInternalLoadBalancer &LoadBalancerPort=443 &Version=2012-06-01 &Action=SetLoadBalancerPoliciesOfListener &AUTHPARAMS
Sample Response <SetLoadBalancerPoliciesOfListenerResponse xmlns="http://elasticloadbalancing.am azonaws.com/doc/2012-06-01/"> <SetLoadBalancerPoliciesOfListenerResult/> 07b1ecbc-1100-11e3-acaf-dd7edEXAMPLE
API Version 2012-06-01 58
Elastic Load Balancing API Reference
Data Types The Elastic Load Balancing API contains several data types that various actions use.This section describes each data type in detail.
Note The order of each element in the response is not guaranteed. Applications should not assume a particular order. The following data types are supported: • • • • • • • • • •
AccessLog (p. 60) AppCookieStickinessPolicy (p. 61) ApplySecurityGroupsToLoadBalancerResult (p. 61) AttachLoadBalancerToSubnetsResult (p. 62) BackendServerDescription (p. 62) ConfigureHealthCheckResult (p. 62) ConnectionDraining (p. 63) CreateAppCookieStickinessPolicyResult (p. 63) CreateLBCookieStickinessPolicyResult (p. 63) CreateLoadBalancerListenersResult (p. 63)
• • • •
CreateLoadBalancerPolicyResult (p. 64) CreateLoadBalancerResult (p. 64) CrossZoneLoadBalancing (p. 64) DeleteLoadBalancerListenersResult (p. 65)
• DeleteLoadBalancerPolicyResult (p. 65) • • • •
DeleteLoadBalancerResult (p. 65) DeregisterInstancesFromLoadBalancerResult (p. 65) DescribeInstanceHealthResult (p. 66) DescribeLoadBalancerAttributesResult (p. 66)
• DescribeLoadBalancerPoliciesResult (p. 66) • DescribeLoadBalancerPolicyTypesResult (p. 67) • DescribeLoadBalancersResult (p. 67) • DetachLoadBalancerFromSubnetsResult (p. 67) • DisableAvailabilityZonesForLoadBalancerResult (p. 68)
API Version 2012-06-01 59
Elastic Load Balancing API Reference AccessLog
• EnableAvailabilityZonesForLoadBalancerResult (p. 68) • HealthCheck (p. 68) • Instance (p. 69) • InstanceState (p. 70) • LBCookieStickinessPolicy (p. 70) • Listener (p. 71) • ListenerDescription (p. 72) • LoadBalancerAttributes (p. 72) • LoadBalancerDescription (p. 73) • ModifyLoadBalancerAttributesResult (p. 75) • Policies (p. 76) • PolicyAttribute (p. 76) • • • • • • • • •
PolicyAttributeDescription (p. 77) PolicyAttributeTypeDescription (p. 77) PolicyDescription (p. 78) PolicyTypeDescription (p. 78) RegisterInstancesWithLoadBalancerResult (p. 79) SetLoadBalancerListenerSSLCertificateResult (p. 79) SetLoadBalancerPoliciesForBackendServerResult (p. 79) SetLoadBalancerPoliciesOfListenerResult (p. 80) SourceSecurityGroup (p. 80)
AccessLog Description The AccessLog data type.
Contents EmitInterval The interval for publishing the access logs. You can specify an interval of either 5 minutes or 60 minutes. Default: 60 minutes Type: Integer Required: No Enabled Specifies whether access log is enabled for the load balancer. Type: Boolean Required: Yes S3BucketName The name of the Amazon S3 bucket where the access logs are stored. Type: String
API Version 2012-06-01 60
Elastic Load Balancing API Reference AppCookieStickinessPolicy
Required: No S3BucketPrefix The logical hierarchy you created for your Amazon S3 bucket, for example my-bucket-prefix/prod. If the prefix is not provided, the log is placed at the root level of the bucket. Type: String Required: No
AppCookieStickinessPolicy Description The AppCookieStickinessPolicy data type.
Contents CookieName The name of the application cookie used for stickiness. Type: String Required: No PolicyName The mnemonic name for the policy being created. The name must be unique within a set of policies for this load balancer. Type: String Required: No
ApplySecurityGroupsToLoadBalancerResult Description The out for the ApplySecurityGroupsToLoadBalancer (p. 3) action.
Contents SecurityGroups A list of security group IDs associated with your load balancer. Type: String list Required: No
API Version 2012-06-01 61
Elastic Load Balancing API Reference AttachLoadBalancerToSubnetsResult
AttachLoadBalancerToSubnetsResult Description The output for the AttachLoadBalancerToSubnets (p. 5) action.
Contents Subnets A list of subnet IDs attached to the load balancer. Type: String list Required: No
BackendServerDescription Description This data type is used as a response element in the DescribeLoadBalancers (p. 39) action to describe the configuration of the back-end server.
Contents InstancePort Provides the port on which the back-end server is listening. Type: Integer Required: No PolicyNames Provides a list of policy names enabled for the back-end server. Type: String list Required: No
ConfigureHealthCheckResult Description The output for the ConfigureHealthCheck (p. 7) action.
Contents HealthCheck The updated healthcheck for the instances. Type: HealthCheck (p. 68)
API Version 2012-06-01 62
Elastic Load Balancing API Reference ConnectionDraining
Required: No
ConnectionDraining Description The ConnectionDraining data type.
Contents Enabled Specifies whether connection draining is enabled for the load balancer. Type: Boolean Required: Yes Timeout Specifies the maximum time (in seconds) to keep the existing connections open before deregistering the instances. Type: Integer Required: No
CreateAppCookieStickinessPolicyResult Description The output for the CreateAppCookieStickinessPolicy (p. 9) action.
Contents
CreateLBCookieStickinessPolicyResult Description The output for the CreateLBCookieStickinessPolicy (p. 11) action.
Contents
CreateLoadBalancerListenersResult Description The output for the CreateLoadBalancerListeners (p. 19) action. API Version 2012-06-01 63
Elastic Load Balancing API Reference Contents
Contents
CreateLoadBalancerPolicyResult Description The output for the CreateLoadBalancerPolicy (p. 21) action.
Contents
CreateLoadBalancerResult Description The output for the CreateLoadBalancer (p. 13) action.
Contents DNSName The DNS name for the load balancer. Type: String Required: No
CrossZoneLoadBalancing Description The CrossZoneLoadBalancing data type.
Contents Enabled Specifies whether cross-zone load balancing is enabled for the load balancer. Type: Boolean Required: Yes
API Version 2012-06-01 64
Elastic Load Balancing API Reference DeleteLoadBalancerListenersResult
DeleteLoadBalancerListenersResult Description The output for the DeleteLoadBalancerListeners (p. 24) action.
Contents
DeleteLoadBalancerPolicyResult Description The output for the DeleteLoadBalancerPolicy (p. 25) action.
Contents
DeleteLoadBalancerResult Description The output for the DeleteLoadBalancer (p. 23) action.
Contents
DeregisterInstancesFromLoadBalancerResult Description The output for the DeregisterInstancesFromLoadBalancer (p. 26) action.
Contents Instances An updated list of remaining instances registered with the load balancer. Type: Instance (p. 69) list Required: No
API Version 2012-06-01 65
Elastic Load Balancing API Reference DescribeInstanceHealthResult
DescribeInstanceHealthResult Description The output for the DescribeInstanceHealth (p. 28) action.
Contents InstanceStates A list containing health information for the specified instances. Type: InstanceState (p. 70) list Required: No
DescribeLoadBalancerAttributesResult Description The following element is returned in a structure named DescribeLoadBalancerAttributesResult.
Contents LoadBalancerAttributes The load balancer attributes structure. Type: LoadBalancerAttributes (p. 72) Required: No
DescribeLoadBalancerPoliciesResult Description The output for the DescribeLoadBalancerPolicies (p. 33) action.
Contents PolicyDescriptions A list of policy description structures. Type: PolicyDescription (p. 78) list Required: No
API Version 2012-06-01 66
Elastic Load Balancing API Reference DescribeLoadBalancerPolicyTypesResult
DescribeLoadBalancerPolicyTypesResult Description The output for the DescribeLoadBalancerPolicyTypes (p. 36) action.
Contents PolicyTypeDescriptions List of policy type description structures of the specified policy type. If no policy type names are specified, returns the description of all the policy types defined by Elastic Load Balancing service. Type: PolicyTypeDescription (p. 78) list Required: No
DescribeLoadBalancersResult Description The output for the DescribeLoadBalancers (p. 39) action.
Contents LoadBalancerDescriptions A list of load balancer description structures. Type: LoadBalancerDescription (p. 73) list Required: No NextMarker An optional parameter reserved for future use. Type: String Required: No
DetachLoadBalancerFromSubnetsResult Description The output for the DetachLoadBalancerFromSubnets (p. 42) action.
Contents Subnets A list of subnet IDs the load balancer is now attached to. Type: String list
API Version 2012-06-01 67
Elastic Load Balancing API Reference DisableAvailabilityZonesForLoadBalancerResult
Required: No
DisableAvailabilityZonesForLoadBalancerResult Description The output for the DisableAvailabilityZonesForLoadBalancer (p. 44) action.
Contents AvailabilityZones A list of updated Availability Zones for the load balancer. Type: String list Required: No
EnableAvailabilityZonesForLoadBalancerResult Description The output for the EnableAvailabilityZonesForLoadBalancer (p. 46) action.
Contents AvailabilityZones An updated list of Availability Zones for the load balancer. Type: String list Required: No
HealthCheck Description The HealthCheck data type.
Contents HealthyThreshold Specifies the number of consecutive health probe successes required before moving the instance to the Healthy state. Type: Integer Required: Yes
API Version 2012-06-01 68
Elastic Load Balancing API Reference Instance
Interval Specifies the approximate interval, in seconds, between health checks of an individual instance. Type: Integer Required: Yes Target Specifies the instance being checked. The protocol is either TCP, HTTP, HTTPS, or SSL. The range of valid ports is one (1) through 65535.
Note TCP is the default, specified as a TCP: port pair, for example "TCP:5000". In this case a healthcheck simply attempts to open a TCP connection to the instance on the specified port. Failure to connect within the configured timeout is considered unhealthy. SSL is also specified as SSL: port pair, for example, SSL:5000. For HTTP or HTTPS protocol, the situation is different. You have to include a ping path in the string. HTTP is specified as a HTTP:port;/;PathToPing; grouping, for example "HTTP:80/weather/us/wa/seattle". In this case, a HTTP GET request is issued to the instance on the given port and path. Any answer other than "200 OK" within the timeout period is considered unhealthy. The total length of the HTTP ping target needs to be 1024 16-bit Unicode characters or less. Type: String Required: Yes Timeout Specifies the amount of time, in seconds, during which no response means a failed health probe.
Note This value must be less than the Interval value. Type: Integer Required: Yes UnhealthyThreshold Specifies the number of consecutive health probe failures required before moving the instance to the Unhealthy state. Type: Integer Required: Yes
Instance Description The Instance data type.
Contents InstanceId Provides an EC2 instance ID.
API Version 2012-06-01 69
Elastic Load Balancing API Reference InstanceState
Type: String Required: No
InstanceState Description The InstanceState data type.
Contents Description Provides a description of the instance state. Type: String Required: No InstanceId Provides an EC2 instance ID. Type: String Required: No ReasonCode Provides information about the cause of OutOfService instances. Specifically, it indicates whether the cause is Elastic Load Balancing or the instance behind the load balancer. Valid value: ELB|Instance|N/A Type: String Required: No State Specifies the current state of the instance. Valid value: InService|OutOfService Type: String Required: No
LBCookieStickinessPolicy Description The LBCookieStickinessPolicy data type.
API Version 2012-06-01 70
Elastic Load Balancing API Reference Contents
Contents CookieExpirationPeriod The time period in seconds after which the cookie should be considered stale. Not specifying this parameter indicates that the stickiness session will last for the duration of the browser session. Type: Long Required: No PolicyName The name for the policy being created. The name must be unique within the set of policies for this load balancer. Type: String Required: No
Listener Description The Listener data type.
Contents InstancePort Specifies the TCP port on which the instance server is listening. This property cannot be modified for the life of the load balancer. Type: Integer Required: Yes InstanceProtocol Specifies the protocol to use for routing traffic to back-end instances - HTTP, HTTPS, TCP, or SSL. This property cannot be modified for the life of the load balancer.
Note If the front-end protocol is HTTP or HTTPS, InstanceProtocol has to be at the same protocol layer, i.e., HTTP or HTTPS. Likewise, if the front-end protocol is TCP or SSL, InstanceProtocol has to be TCP or SSL.
Note If there is another listener with the same InstancePort whose InstanceProtocol is secure, i.e., HTTPS or SSL, the listener's InstanceProtocol has to be secure, i.e., HTTPS or SSL. If there is another listener with the same InstancePort whose InstanceProtocol is HTTP or TCP, the listener's InstanceProtocol must be either HTTP or TCP. Type: String Required: No LoadBalancerPort Specifies the external load balancer port number. This property cannot be modified for the life of the load balancer. Type: Integer API Version 2012-06-01 71
Elastic Load Balancing API Reference ListenerDescription
Required: Yes Protocol Specifies the load balancer transport protocol to use for routing - HTTP, HTTPS, TCP or SSL. This property cannot be modified for the life of the load balancer. Type: String Required: Yes SSLCertificateId The ARN string of the server certificate. To get the ARN of the server certificate, call the AWS Identity and Access Management UploadServerCertificate API. Type: String Required: No
ListenerDescription Description The ListenerDescription data type.
Contents Listener The Listener data type. Type: Listener (p. 71) Required: No PolicyNames A list of policies enabled for this listener. An empty list indicates that no policies are enabled. Type: String list Required: No
LoadBalancerAttributes Description The LoadBalancerAttributes data type.
Contents AccessLog The name of the load balancer attribute. If enabled, the load balancer captures detailed information of all the requests and delivers the information to the Amazon S3 bucket you specify. For more information, see Enable Access Logs. Type: AccessLog (p. 60) API Version 2012-06-01 72
Elastic Load Balancing API Reference LoadBalancerDescription
Required: No ConnectionDraining The name of the load balancer attribute. If enabled, the load balancer allows existing requests to complete before the load balancer shifts traffic away from a deregistered or unhealthy back-end instance. For more information, see Enable Connection Draining. Type: ConnectionDraining (p. 63) Required: No CrossZoneLoadBalancing The name of the load balancer attribute. If enabled, the load balancer routes the request traffic evenly across all back-end instances regardless of the Availability Zones. For more information, see Enable Cross-Zone Load Balancing. Type: CrossZoneLoadBalancing (p. 64) Required: No
LoadBalancerDescription Description Contains the result of a successful invocation of DescribeLoadBalancers (p. 39).
Contents AvailabilityZones Specifies a list of Availability Zones. Type: String list Required: No BackendServerDescriptions Contains a list of back-end server descriptions. Type: BackendServerDescription (p. 62) list Required: No CanonicalHostedZoneName Provides the name of the Amazon Route 53 hosted zone that is associated with the load balancer. For information on how to associate your load balancer with a hosted zone, go to Using Domain Names With Elastic Load Balancing in the Elastic Load Balancing Developer Guide. Type: String Required: No CanonicalHostedZoneNameID Provides the ID of the Amazon Route 53 hosted zone name that is associated with the load balancer. For information on how to associate or disassociate your load balancer with a hosted zone, go to Using Domain Names With Elastic Load Balancing in the Elastic Load Balancing Developer Guide. Type: String API Version 2012-06-01 73
Elastic Load Balancing API Reference Contents
Required: No CreatedTime Provides the date and time the load balancer was created. Type: DateTime Required: No DNSName Specifies the external DNS name associated with the load balancer. Type: String Required: No HealthCheck Specifies information regarding the various health probes conducted on the load balancer. Type: HealthCheck (p. 68) Required: No Instances Provides a list of EC2 instance IDs for the load balancer. Type: Instance (p. 69) list Required: No ListenerDescriptions LoadBalancerPort, InstancePort, Protocol, InstanceProtocol, and PolicyNames are returned in a list of tuples in the ListenerDescriptions element. Type: ListenerDescription (p. 72) list Required: No LoadBalancerName Specifies the name associated with the load balancer. Type: String Required: No Policies Provides a list of policies defined for the load balancer. Type: Policies (p. 76) Required: No Scheme Specifies the type of load balancer. If the Scheme is internet-facing, the load balancer has a publicly resolvable DNS name that resolves to public IP addresses. If the Scheme is internal, the load balancer has a publicly resolvable DNS name that resolves to private IP addresses. This option is only available for load balancers attached to an Amazon VPC. Type: String Required: No
API Version 2012-06-01 74
Elastic Load Balancing API Reference ModifyLoadBalancerAttributesResult
SecurityGroups The security groups the load balancer is a member of (VPC only). Type: String list Required: No SourceSecurityGroup The security group that you can use as part of your inbound rules for your load balancer's back-end Amazon EC2 application instances. To only allow traffic from load balancers, add a security group rule to your back end instance that specifies this source security group as the inbound source. Type: SourceSecurityGroup (p. 80) Required: No Subnets Provides a list of VPC subnet IDs for the load balancer. Type: String list Required: No VPCId Provides the ID of the VPC attached to the load balancer. Type: String Required: No
ModifyLoadBalancerAttributesResult Description The output for the ModifyLoadBalancerAttributes (p. 48) action.
Contents LoadBalancerAttributes The LoadBalancerAttributes data type. Type: LoadBalancerAttributes (p. 72) Required: No LoadBalancerName The name of the load balancer. Type: String Required: No
API Version 2012-06-01 75
Elastic Load Balancing API Reference Policies
Policies Description The policies data type.
Contents AppCookieStickinessPolicies A list of the AppCookieStickinessPolicy (p. 61) objects created with CreateAppCookieStickinessPolicy (p. 9). Type: AppCookieStickinessPolicy (p. 61) list Required: No LBCookieStickinessPolicies A list of LBCookieStickinessPolicy (p. 70) objects created with CreateAppCookieStickinessPolicy (p. 9). Type: LBCookieStickinessPolicy (p. 70) list Required: No OtherPolicies A list of policy names other than the stickiness policies. Type: String list Required: No
PolicyAttribute Description The PolicyAttribute (p. 76) data type. This data type contains a key/value pair that defines properties of a specific policy.
Contents AttributeName The name of the attribute associated with the policy. Type: String Required: No AttributeValue The value of the attribute associated with the policy. Type: String Required: No
API Version 2012-06-01 76
Elastic Load Balancing API Reference PolicyAttributeDescription
PolicyAttributeDescription Description The PolicyAttributeDescription data type. This data type is used to describe the attributes and values associated with a policy.
Contents AttributeName The name of the attribute associated with the policy. Type: String Required: No AttributeValue The value of the attribute associated with the policy. Type: String Required: No
PolicyAttributeTypeDescription Description The PolicyAttributeTypeDescription data type. This data type is used to describe values that are acceptable for the policy attribute.
Contents AttributeName The name of the attribute associated with the policy type. Type: String Required: No AttributeType The type of attribute. For example, Boolean, Integer, etc. Type: String Required: No Cardinality The cardinality of the attribute. Valid Values: • ONE(1) : Single value required • ZERO_OR_ONE(0..1) : Up to one value can be supplied • ZERO_OR_MORE(0..*) : Optional. Multiple values are allowed • ONE_OR_MORE(1..*0) : Required. Multiple values are allowed Type: String
API Version 2012-06-01 77
Elastic Load Balancing API Reference PolicyDescription
Required: No DefaultValue The default value of the attribute, if applicable. Type: String Required: No Description A human-readable description of the attribute. Type: String Required: No
PolicyDescription Description The PolicyDescription data type.
Contents PolicyAttributeDescriptions A list of policy attribute description structures. Type: PolicyAttributeDescription (p. 77) list Required: No PolicyName The name of the policy associated with the load balancer. Type: String Required: No PolicyTypeName The name of the policy type associated with the load balancer. Type: String Required: No
PolicyTypeDescription Description The PolicyTypeDescription (p. 78) data type.
Contents Description A human-readable description of the policy type.
API Version 2012-06-01 78
Elastic Load Balancing API Reference RegisterInstancesWithLoadBalancerResult
Type: String Required: No PolicyAttributeTypeDescriptions The description of the policy attributes associated with the load balancer policies defined by the Elastic Load Balancing service. Type: PolicyAttributeTypeDescription (p. 77) list Required: No PolicyTypeName The name of the policy type. Type: String Required: No
RegisterInstancesWithLoadBalancerResult Description The output for the RegisterInstancesWithLoadBalancer (p. 51) action.
Contents Instances An updated list of instances for the load balancer. Type: Instance (p. 69) list Required: No
SetLoadBalancerListenerSSLCertificateResult Description The output for the SetLoadBalancerListenerSSLCertificate (p. 53) action.
Contents
SetLoadBalancerPoliciesForBackendServerResult Description The output for the SetLoadBalancerPoliciesForBackendServer (p. 55) action.
API Version 2012-06-01 79
Elastic Load Balancing API Reference Contents
Contents
SetLoadBalancerPoliciesOfListenerResult Description The output for the SetLoadBalancerPoliciesOfListener (p. 57) action.
Contents
SourceSecurityGroup Description This data type is used as a response element in the DescribeLoadBalancers (p. 39) action. For information about Elastic Load Balancing security groups, go to Using Security Groups With Elastic Load Balancing in the Elastic Load Balancing Developer Guide.
Contents GroupName Name of the source security group. Use this value for the --source-group parameter of the ec2-authorize command in the Amazon EC2 command line tool. Type: String Required: No OwnerAlias Owner of the source security group. Use this value for the --source-group-user parameter of the ec2-authorize command in the Amazon EC2 command line tool. Type: String Required: No
API Version 2012-06-01 80
Elastic Load Balancing API Reference
Common Parameters This section lists the request parameters that all actions use. Any action-specific parameters are listed in the topic for the action. Action The action to be performed. Default: None Type: string Required: Yes AuthParams The parameters that are required to authenticate a Conditional request. Contains: • AWSAccessKeyID • SignatureVersion • Timestamp • Signature Default: None Required: Conditional AWSAccessKeyId The access key ID that corresponds to the secret access key that you used to sign the request. Default: None Type: string Required: Yes Expires The date and time when the request signature expires, expressed in the format YYYY-MM-DDThh:mm:ssZ, as specified in the ISO 8601 standard. Condition: Requests must include either Timestamp or Expires, but not both. Default: None Type: string
API Version 2012-06-01 81
Elastic Load Balancing API Reference
Required: Conditional SecurityToken The temporary security token that was obtained through a call to AWS Security Token Service. For a list of services that support AWS Security Token Service, go to Using Temporary Security Credentials to Access AWS in Using Temporary Security Credentials. Default: None Type: string Required: No Signature The digital signature that you created for the request. For information about generating a signature, go to the service's developer documentation. Default: None Type: string Required: Yes SignatureMethod The hash algorithm that you used to create the request signature. Default: None Type: string Valid Values: HmacSHA256 | HmacSHA1 Required: Yes SignatureVersion The signature version you use to sign the request. Set this to the value that is recommended for your service. Default: None Type: string Required: Yes Timestamp The date and time when the request was signed, expressed in the format YYYY-MM-DDThh:mm:ssZ, as specified in the ISO 8601 standard. Condition: Requests must include either Timestamp or Expires, but not both. Default: None Type: string Required: Conditional Version The API version that the request is written for, expressed in the format YYYY-MM-DD. Default: None Type: string Required: Yes
API Version 2012-06-01 82
Elastic Load Balancing API Reference
Common Parameters for Signature V4 Signing The following table lists the parameters that all actions use for signing Signature Version 4 requests. Any action-specific parameters are listed in the topic for that action. To view sample requests, see Examples of Signed Signature Version 4 Requests or Signature Version 4 Test Suite in the Amazon Web Services General Reference . Action The action to be performed. Type: string Required: Yes Version The API version that the request is written for, expressed in the format YYYY-MM-DD. Type: string Required: Yes X-Amz-Algorithm The hash algorithm that you used to create the request signature. Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Valid Values: AWS4-HMAC-SHA256 Required: Conditional X-Amz-Credential The credential scope value, which is a string that includes your access key, the date, the region you are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request. For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web Services General Reference.
API Version 2012-06-01 83
Elastic Load Balancing API Reference
Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional X-Amz-Date The date that is used to create the signature. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value: 20120325T120000Z. Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is not required. When X-Amz-Date is used, it always overrides the value of the Date header. For more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General Reference. Type: string Required: Conditional X-Amz-Security-Token The temporary security token that was obtained through a call to AWS Security Token Service. For a list of services that support AWS Security Token Service, go to Using Temporary Security Credentials to Access AWS in Using Temporary Security Credentials. Condition: If you're using temporary security credentials from the AWS Security Token Service, you must include the security token. Type: string Required: Conditional X-Amz-Signature Specifies the hex-encoded signature that was calculated from the string to sign and the derived signing key. Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional X-Amz-SignedHeaders Specifies all the HTTP headers that were included as part of the canonical request. For more information about specifying signed headers, see Task 1: Create a Canonical Request For Signature Version 4 in the Amazon Web Services General Reference . Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional
API Version 2012-06-01 84
Elastic Load Balancing API Reference
Common Errors This section lists the common errors that all actions return. Any action-specific errors are listed in the topic for the action. IncompleteSignature The request signature does not conform to AWS standards. HTTP Status Code: 400 InternalFailure The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 InvalidAction The action or operation requested is invalid. Verify that the action is typed correctly. HTTP Status Code: 400 InvalidClientTokenId The X.509 certificate or AWS access key ID provided does not exist in our records. HTTP Status Code: 403 InvalidParameterCombination Parameters that must not be used together were used together. HTTP Status Code: 400 InvalidParameterValue An invalid or out-of-range value was supplied for the input parameter. HTTP Status Code: 400 InvalidQueryParameter The AWS query string is malformed or does not adhere to AWS standards. HTTP Status Code: 400 MalformedQueryString The query string contains a syntax error. HTTP Status Code: 404 MissingAction The request is missing an action or a required parameter.
API Version 2012-06-01 85
Elastic Load Balancing API Reference
HTTP Status Code: 400 MissingAuthenticationToken The request must contain either a valid (registered) AWS access key ID or X.509 certificate. HTTP Status Code: 403 MissingParameter A required parameter for the specified action is not supplied. HTTP Status Code: 400 OptInRequired The AWS access key ID needs a subscription for the service. HTTP Status Code: 403 RequestExpired The request reached the service more than 15 minutes after the date stamp on the request or more than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp on the request is more than 15 minutes in the future. HTTP Status Code: 400 ServiceUnavailable The request has failed due to a temporary failure of the server. HTTP Status Code: 503 Throttling The request was denied due to request throttling. HTTP Status Code: 400 ValidationError The input fails to satisfy the constraints specified by an AWS service. HTTP Status Code: 400
API Version 2012-06-01 86
