Provided by: libvm-ec2-perl_1.28-4_all bug

NAME

       VM::EC2::ELB -- Object describing an Elastic Load Balancer

SYNOPSIS

         use VM::EC2;

         $ec2       = VM::EC2->new(...);
         $lb = $ec2->create_load_balancer(%args);
           or
         $lb = $ec2->describe_load_balancers(-load_balancer_name=>'my-lb');

         @zones        = $lb->AvailabilityZones;
         $created      = $lb->CreatedTime;
         $dns_name     = $lb->DNSName;
         $health_check = $lb->HealthCheck;
         @instances    = $lb->Instances;
         @list_desc    = $lb->ListenerDescriptions;
         $name         = $lb->LoadBalancerName;
         @policies_obj = $lb->Policies;
         @policies     = $lb->describe_policies(-policy_names=>'mypolicy');
         $scheme       = $lb->Scheme;
         $sg_name      = $lb->SourceSecurityGroup;
         $success      = $lb->create_load_balancer_listeners(%args);
         $success      = $lb->enable_availability_zones_for_load_balancer(@zones);
         @list         = $lb->register_instances_with_load_balancer(-instances => 'i-12345678');
         $state        = $lb->describe_instance_health(-instances => 'i-12345678')
         $success      = $lb->delete_load_balancer;

DESCRIPTION

       This object represents an Amazon Elastic Load Balancer and is returned by
       VM::EC2->describe_load_balancers() and VM::EC2->create_load_balancer().  In addition to
       methods to query the ELB's attributes, there are methods that manage the ELB's lifecycle
       and properties.

METHODS

       The following object methods are supported:

        AvailabilityZones         -- The enabled availability zones for the ELB in the
                                     form of an array of L<VM::EC2::AvailabilityZone>
                                     objects.
        BackendServerDescriptions -- The backend server descriptions.
        CreatedTime               -- The creation date of the ELB.
        DNSName                   -- The DNS name of the ELB.
        HealthCheck               -- The health check associated with the ELB in the
                                     form of a L<VM::EC2::ELB::HealthCheck> object.
        Instances                 -- The instances that the ELB points to, in the form
                                     of an array of L<VM::EC2::Instance> objects.
        ListenerDescriptions      -- An array of L<VM::EC2::ELB::ListenerDescription>
                                     objects.
        LoadBalancerName          -- The name of the ELB
        Policies                  -- The policies of the ELB in the form of a
                                     L<VM::EC2::ELB::Policies> object.
        Scheme                    -- Specifies the type of ELB ('internal' is for VPC
                                     only.)
        SecurityGroups            -- The security groups the ELB is a member of (VPC
                                     only) in the form of L<VM::EC2::SecurityGroup>
                                     objects.
        SourceSecurityGroup       -- The security group that the ELB is a member of
        Subnets                   -- Provides an array of VPC subnet objects
                                     (L<VM::EC2::VPC::Subnet>) that the ELB is part of.
        VPCId                     -- Provides the ID of the VPC attached to the ELB.

       "Unimplemented/untested" object methods related to Route 53 (return raw data/ data
       structures):

        CanonicalHostedZoneName   -- The name of the Amazon Route 53 hosted zone that
                                     is associated with the ELB.
        CanonicalHostedZoneNameID -- The ID of the Amazon Route 53 hosted zone name
                                     that is associated with the ELB.

       The following convenience methods are supported;

        active_policies           -- Returns the policies that are actively in use by
                                     the ELB in the form of L<VM::EC2::ELB::PolicyDescription>
                                     objects.
        all_policies              -- Returns all policies that are associated with the
                                     ELB in the form of L<VM::EC2::ELB::PolicyDescription>
                                     objects.
        listeners                 -- Provides the L<VM::EC2::ELB::Listener> objects
                                     associated with the ELB

LIFECYCLE METHODS

   $success = $elb->delete_load_balancer =head2 $success = $elb->delete
       This method deletes the ELB.  Returns true on success.

   $success =
       $elb->create_app_cookie_stickiness_policy(-cookie_name=>$cookie_name,-policy_name=>$policy_name)
       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.  Returns true on success.

   $success =
       $elb->create_lb_cookie_stickiness_policy(-cookie_expiration_period=>$secs,-policy_name=>$name)
       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.  Returns true on success.

   $success = $elb->create_load_balancer_listeners(-listeners=>\%listener_hash); =head2 $success
       = $elb->create_listeners(\%listener_hash);
       Creates one or more listeners on a ELB 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.  Returns true on success.

       The passed argument must either be a VM::EC2::ELB:Listener object (or arrayref of objects)
       or a hash (or arrayref of hashes) containing the following keys:

        Protocol            -- Value as one of: HTTP, HTTPS, TCP, or SSL
        LoadBalancerPort    -- Value in range 1-65535
        InstancePort        -- Value in range 1-65535
         and optionally:
        InstanceProtocol    -- Value as one of: HTTP, HTTPS, TCP, or SSL
        SSLCertificateId    -- Certificate ID from AWS IAM certificate list

   $success = $elb->delete_load_balancer_listeners(-load_balancer_ports=>\@ports) =head2 $success
       = $elb->delete_listeners(@ports)
       Deletes listeners from the ELB for the specified port.  Returns true on success.

   @zones = $elb->disable_availability_zones_for_load_balancer(-zones=>\@zones) =head2 @zones =
       $elb->disable_availability_zones(@zones) =head2 @zones = $elb->disable_zones(@zones)
       Removes the specified EC2 Availability Zones from the set of configured Availability Zones
       for the ELB.  Returns a series of VM::EC2::AvailabilityZone objects now associated with
       the ELB.

   @zones = $elb->enable_availability_zones_for_load_balancer(-zones=>\@zones) =head2 @zones =
       $elb->enable_availability_zones(@zones) =head2 @zones = $elb->enable_zones(@zones)
       Adds the specified EC2 Availability Zones to the set of configured Availability Zones for
       the ELB.  Returns a series of VM::EC2::AvailabilityZone objects now associated with the
       ELB.

   @instance_ids = $elb->register_instances_with_load_balancer(-instances=>\@instance_ids) =head2
       @instance_ids = $elb->register_instances(@instance_ids)
       Adds new instances to the ELB.  If the instance is in an availability zone that is not
       registered with the ELB will be in the OutOfService state.  Once the zone is added to the
       ELB the instance will go into the InService state. Returns an array of instance IDs now
       associated with the ELB.

   @instance_ids = $elb->deregister_instances_from_load_balancer(-instances=>\@instance_ids)
       =head2 @instance_ids = $elb->deregister_instances(@instance_ids)
       Deregisters instances from the ELB. Once the instance is deregistered, it will stop
       receiving traffic from the ELB.  Returns an array of instance IDs now associated with the
       ELB.

   @states = $elb->describe_instance_health(-instances=>\@instance_ids) =head2 @states =
       $elb->describe_instance_health(@instance_ids)
       Provides the current state of the instances of the specified LoadBalancer. If no instances
       are specified, the state of all the instances for the ELB is returned.  Returns an array
       of VM::EC2::ELB::InstanceState objects.

   $success =
       $elb->create_load_balancer_policy(-policy_name=>$name,-policy_type_name=>$type_name,-policy_attributes=>\@attrs)
       =head2 $success =
       $elb->create_policy(-policy_name=>$name,-policy_type_name=>$type_name,-policy_attributes=>\@attrs)
       Creates a new policy that contains the necessary attributes depending on the policy type.
       Policies are settings that are saved for your ELB and that can be applied to the front-end
       listener, or the back-end application server, depending on your policy type.  Returns true
       on success.

   $success = $elb->delete_load_balancer_policy(-policy_name=>$policy_name) =head2 $success =
       $elb->delete_policy($policy_name)
       Deletes a policy from the ELB.  The specified policy must not be enabled for any
       listeners.  Returns true on success.

CONFIGURATION METHODS

   $health_check =
       $elb->configure_health_check(-healthy_threshold=>$cnt,-interval=>$secs,-target=>$target,-timeout=>$secs,-unhealthy_threshold=>$cnt)
       This method configures the health check for a particular target service.

       -target must be in the format Protocol:Port[/PathToPing]:
        - Valid Protocol types are: HTTP, HTTPS, TCP, SSL
        - Port must be in range 0-65535
        - PathToPing is only applicable to HTTP or HTTPS protocol
          types and must be 1024 characters long or fewer.

        ex: HTTP:80/index.html

   $success = $elb->create_policy(-policy_name=>$name,-policy_type_name=>$type_name)
       Creates a new policy that contains the necessary attributes depending on the policy type.
       Returns true on success.

   $success = $elb->set_load_balancer_listener_ssl_certificate(-port=>$port,-cert_id=>$cert_id)
       Sets the certificate that terminates the specified listener's SSL connections.  The
       specified certificate replaces any prior certificate that was used on the same ELB and
       port.  Returns true on success.

   $success = $elb->set_load_balancer_policies_of_listener(-port=>$port,-policy_names=>\@names)
       =head2 $success = $elb->set_policies_of_listener(-port=>$port,-policy_names=>\@names)
       Associates, updates, or disables a policy with a listener on the ELB.  Multiple policies
       may be associated with a listener.  Returns true on success.

   @groups = $elb->apply_security_groups_to_load_balancer(-security_groups=>\@groups) =head2
       @groups = $elb->apply_security_groups(@groups)
       Associates one or more security groups with your ELB in VPC.  The provided security group
       IDs will override any currently applied security groups.  Returns a list of
       VM::EC2::SecurityGroup objects.

   @subnets = $elb->attach_load_balancer_to_subnets(-subnets=>\@subnets) =head2 @subnets =
       $elb->attach_to_subnets(@subnets)
       Adds one or more subnets to the set of configured subnets for the ELB.  Returns a series
       of VM::EC2::VPC::Subnet objects corresponding to the subnets the ELB is now attached to.

   @subnets = $elb->detach_load_balancer_from_subnets(-subnets=>\@subnets) =head2 @subnets =
       $elb->detach_from_subnets(@subnets)
       Removes subnets from the set of configured subnets in the VPC for the ELB.  Returns a
       series of VM::EC2::VPC::Subnet objects corresponding to the subnets the ELB is now
       attached to.

   $success =
       $elb->set_load_balancer_policies_for_backend_server(-port=>$port,-policy_names=>$names)
       =head2 $success =
       $elb->set_policies_for_backend_server(-port=>$port,-policy_names=>$names)
       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, 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.  Returns true on success.

   $success = $elb->add_tags({ Name => Value[, Name => Value,...]); =head2 $success =
       $elb->add_tags(\%tags);
       Adds tags to the ELB.  Up to ten tags can be applied.

INFORMATION METHODS

   $state = $lb->describe_instance_health(-instances=>\@instances) =head2 $state =
       $lb->describe_instance_health(@instances) =head2 $state = $lb->describe_instance_health
       Returns the current state of the instances registered with the ELB.

   @policies = $lb->describe_load_balancer_policies(-policy_names=>\@names) =head2 @policies =
       $lb->describe_load_balancer_policies;

STRING OVERLOADING

       When used in a string context, this object will interpolate the Elastic Load Balancer
       Name.

SEE ALSO

       VM::EC2 VM::EC2::Generic VM::EC2::ELB::HealthCheck VM::EC2::ELB::ListenerDescription
       VM::EC2::ELB::BackendServerDescription VM::EC2::ELB::Policies

AUTHOR

       Lance Kinley <lkinley@loyaltymethods.com>.

       Copyright (c) 2012-2014 Loyalty Methods, Inc.

       This package and its accompanying libraries is free software; you can redistribute it
       and/or modify it under the terms of the GPL (either version 1, or at your option, any
       later version) or the Artistic License 2.0.  Refer to LICENSE for the full license text.
       In addition, please see DISCLAIMER.txt for disclaimers of warranty.