VM::EC...lancer(3pm)

📦
version 1.28 · 7 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ NAME ✨

VM::EC2::REST::elastic_load_balancer — Elastic Load Balancers 💖

okay so real talk: this is the manual page for VM::EC2::REST::elastic_load_balancer(3pm) out of the User Contributed Perl Documentation, and it's all about ELBs — making them, reading them, and rearranging their whole vibe. Grab a snack, this one's long and it comes in parts 🍓

🎀 SYNOPSIS 🎀

use VM::EC2 ':elb';

that's it, that's the whole summoning ritual ✨

👑 METHODS 👑

So the methods in this module let you retrieve information about Elastic Load Balancers, create brand new ELBs, and change the properties of the ELBs you already have. Very main character of them, honestly.

Implemented:

AddTags
ApplySecurityGroupsToLoadBalancer
AttachLoadBalancerToSubnets
ConfigureHealthCheck
CreateAppCookieStickinessPolicy
CreateLBCookieStickinessPolicy
CreateLoadBalancer
CreateLoadBalancerListeners
CreateLoadBalancerPolicy
DeleteLoadBalancer
DeleteLoadBalancerListeners
DeleteLoadBalancerPolicy
DeregisterInstancesFromLoadBalancer
DescribeInstanceHealth
DescribeLoadBalancerAttributes
DescribeLoadBalancerPolicies
DescribeLoadBalancerPolicyTypes
DescribeLoadBalancers
DescribeTags
DetachLoadBalancerFromSubnets
DisableAvailabilityZonesForLoadBalancer
EnableAvailabilityZonesForLoadBalancer
ModifyLoadBalancerAttributes
RegisterInstancesWithLoadBalancer
RemoveTags
SetLoadBalancerListenerSSLCertificate
SetLoadBalancerPoliciesForBackendServer
SetLoadBalancerPoliciesOfListener

Unimplemented:

  • (none) — not a single one missing, we ate and left no crumbs 👑

The primary object you'll be handling with all of these is VM::EC2::ELB. Please go read the VM::EC2::ELB manual page, bestie, it's the whole lore 🦋

tag_load_balancer — go stick some tags on it 🏷️

$success = $ec2->tag_load_balancer(-load_balancer_names => $name, -tags => {
    key => value, [key2 => value2], ... })

Adds one or more tags to the load balancer you point at. Heads up: each load balancer can have a maximum of 10 tags, so don't go feral. Every tag is a key plus an optional value.

Tag keys have to be unique per load balancer. If a tag with that same key is already chilling on the load balancer, this call will just update the value of that key. Slay, no conflict.

Arguments:

  • -load_balancer_names — the name of the load balancer you're tagging. You can specify a maximum of one load balancer name.
  • -tags — a hashref of tag key/value pairs.

Returns true on success ✨

describe_load_balancer_tags — tell me everything 🕵️

%tags = $ec2->describe_load_balancer_tags(-load_balancer_name=>\@names)
%tags = $ec2->describe_load_balancer_tags(@names)

Describes the tags hanging off one or more load balancers.

Arguments:

  • -load_balancer_names — the name of the load balancer(s) to retrieve tags for.

Returns a hash of hashes, shaped exactly like this:

{
   'LBName' =>
   {
       TagName => TagValue,
       TagName => TagValue,
   } }

remove_load_balancer_tags — bye bye tags 👋

$success = $ec2->remove_load_balancer_tags(-load_balancer_names => $name,
    -tags => [ name1,[name2,name3,...] ])
$success = $ec2->remove_load_balancer_tags(-load_balancer_names => $name,
    -tags => $tag)

ngl the original page gives you no prose here, just these two call shapes — one where -tags is an arrayref situation, one where it's a single $tag. Those are your two options, periodt 💅

describe_load_balancer_attributes — the deep dive 🌊

$attrs = $ec2->describe_load_balancer_attributes(-load_balancer_name =>
    $name)

Returns detailed info about every single attribute attached to the load balancer you name.

Arguments:

  • -load_balancer_name — name of the ELB to return information on.

Returns a VM::EC2::ELB::Attributes object 🫶

modify_load_balancer_attributes — glow-up time 💅

$attr = $ec2->modify_load_balancer_attributes(%args)

Modifies the attributes of the load balancer you specify.

Arguments:

  • -load_balancer_name — name of the ELB to change attributes on. Required.

You also need one or more of these:

  • -access_log — a hashref of attribute values for AccessLog. ex: -access_log => { Enabled => 'false' }
  • -connection_draining — a hashref of attribute values for ConnectionDraining. ex: -connection_draining => { Enabled => 'false' }
  • -connection_settings — a hashref of attribute values for ConnectionSettings. ex: -connection_settings => { IdleTimeout => 30 }
  • -cross_zone_load_balancing — a hashref of attribute values for CrossZoneLoadBalancing. ex: -cross_zone_load_balancing => { Enabled => 'true' }

Returns a VM::EC2::ELB::Attributes object ✨

describe_load_balancers — the info dump 📋

@lbs = $ec2->describe_load_balancers(-load_balancer_name=>\@names)
@lbs = $ec2->describe_load_balancers(@names)

Hands you detailed configuration info for the ELB(s) you asked about.

Optional parameters are:

  • -load_balancer_names — name of the ELB to return information on. Can be a string scalar, or an arrayref.
  • -lb_name, -lb_names, -load_balancer_name — aliases for -load_balancer_names

Returns a series of VM::EC2::ELB objects 🌈

delete_load_balancer — yeet it into the void 💀

$success = $ec2->delete_load_balancer(-load_balancer_name=>$name)
$success = $ec2->delete_load_balancer($name)

Deletes the ELB you name.

Arguments:

  • -load_balancer_name — the name of the ELB to delete.
  • -lb_name — alias for -load_balancer_name.

Returns true on successful deletion.

⚠️ NOTE: this API call will return success regardless of the existence of the ELB. So yeah, "success" here does not mean "it was definitely there." Do not let that lie to you bestie, it's giving gaslight 💀

configure_health_check — keeping the instances alive 🩺

$healthcheck = $ec2->configure_health_check(-load_balancer_name  => $name,
    -healthy_threshold   => $cnt, -interval            => $secs, -target
    => $target, -timeout             => $secs, -unhealthy_threshold => $cnt)

Defines an application healthcheck for the instances.

All parameters are required. No skips, no shortcuts. 👑
  • -load_balancer_name — name of the ELB.
  • -healthy_threashold — how many consecutive health probe successes you need before the instance gets moved to the Healthy state.
  • -interval — the approximate interval, in seconds, between health checks of an individual instance.
  • -target — has to be a string in the form Protocol:Port[/PathToPing]
    • Valid protocol types are: HTTP, HTTPS, TCP, SSL
    • Port must be in range 1-65535
    • PathToPing only applies to HTTP or HTTPS protocol types, and must be 1024 characters long or fewer.
  • -timeout — how much time, in seconds, with no response, counts as a failed health probe.
  • -unhealthy_threashold — how many consecutive health probe failures you need before the instance gets moved to the Unhealthy state.
  • -lb_name — alias for -load_balancer_name.

Returns a VM::EC2::ELB::HealthCheck object 🫶

$success = $ec2->create_app_cookie_stickiness_policy(-load_balancer_name =>
    $name, -cookie_name        => $cookie, -policy_name        => $policy)

Generates a stickiness policy whose sticky session lifetimes follow the lifetime of an application-generated cookie. This policy can only be associated with HTTP/HTTPS listeners — don't try it anywhere else.

Required arguments:

  • -load_balancer_name — name of the ELB.
  • -cookie_name — name of the application cookie used for stickiness.
  • -policy_name — the name of the policy being created. This name must be unique within the set of policies for this ELB.
  • -lb_name — alias for -load_balancer_name.

Returns true on successful execution ✨

$success = $ec2->create_lb_cookie_stickiness_policy(-load_balancer_name
    => $name, -cookie_expiration_period => $secs, -policy_name
    => $policy)

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

Required arguments:

  • -load_balancer_name — name of the ELB.
  • -cookie_expiration_period — the time period in seconds after which the cookie should be considered stale. If you don't specify this parameter, that means the sticky session will last for the duration of the browser session. OPTIONAL (yes, the list says "required" and this line says OPTIONAL, that's just how the page is, don't come for me 💀)
  • -policy_name — the name of the policy being created. Must be unique within the set of policies for this ELB.
  • -lb_name — alias for -load_balancer_name.

Returns true on successful execution ✨

create_load_balancer — build the whole thing 🏗️

$lb = $ec2->create_load_balancer(-load_balancer_name => $name, -listeners
    => \@listeners, -availability_zones => \@zones, -scheme             =>
    $scheme, )

Creates a new ELB. The main event, honestly.

Required arguments:

  • -load_balancer_name — name of the ELB.
  • -listeners — must either be a VM::EC2::ELB:Listener object (or an arrayref of objects) or a hashref (or an arrayref of hashrefs) containing these 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 the AWS IAM certificate list
  • -availability_zones — a literal string, or an array of strings, containing valid availability zones. This one is optional if subnets are specified in a VPC usage scenario.

Optional arguments:

  • -scheme — the type of ELB. By default, Elastic Load Balancing creates an Internet-facing LoadBalancer with a publicly resolvable DNS name, which resolves to public IP addresses. Specify the value 'internal' for this option to create an internal LoadBalancer with a DNS name that resolves to private IP addresses. This option is only available in a VPC.
  • -security_groups — the security groups assigned to your ELB within your VPC. String or arrayref.
  • -subnets — a list of subnet IDs in your VPC to attach to your ELB. String or arrayref. REQUIRED if availability zones are not specified above.
  • -tags — a list of tags to assign to the load balancer. A hashref of tag key/value pairs. ex: { Name => Value, Name => Value, ... }

Argument aliases:

  • -zones — alias for -availability_zones
  • -lb_name — alias for -load_balancer_name

Returns a VM::EC2::ELB object if successful 🌈

and that's part 1 bestie, we're not even done yet — more incoming 💖

💅 create_load_balancer_listeners

$success = $ec2->create_load_balancer_listeners(-load_balancer_name =>
    $name, -listeners          => \@listeners)

Okay so this one spins up one or more listeners on an ELB for a given port. Here's the tea: if a listener with that port doesn't already exist, it gets created. But if it does exist, the properties of your new listener must match the properties of the existing one — no cap. Mismatch = not the vibe.

  • -listeners — has to be either a VM::EC2::ELB:Listener object (or an arrayref of those objects), or a hash (or arrayref of hashes) carrying these keys:
    • Protocol — value is one of: HTTP, HTTPS, TCP, or SSL
    • LoadBalancerPort — value in range 1-65535
    • InstancePort — value in range 1-65535
    • and optionally:
    • InstanceProtocol — value is one of: HTTP, HTTPS, TCP, or SSL
    • SSLCertificateId — certificate ID from the AWS IAM certificate list
  • -lb_name — alias for -load_balancer_name

Returns true on successful execution. 🫶

💜 delete_load_balancer_listeners

$success = $ec2->delete_load_balancer_listeners(-load_balancer_name  =>
    $name, -load_balancer_ports => \@ports)

Yeets listeners off the ELB for the port(s) you name. Bye bestie 👋

Arguments:

  • -load_balancer_name — the name of the ELB
  • -load_balancer_ports — an arrayref of strings or a literal string containing the port numbers
  • -ports — alias for -load_balancer_ports
  • -lb_name — alias for -load_balancer_name

Returns true on successful execution.

🌸 disable_availability_zones_for_load_balancer

@z = $ec2->disable_availability_zones_for_load_balancer(-load_balancer_name
    => $name, -availability_zones => \@zones)

Removes the EC2 Availability Zones you list from the set of configured Availability Zones for the ELB.

⚠️ There must be at least one Availability Zone registered with a LoadBalancer at all times. And heads up — instances registered with the ELB that live in the removed Availability Zone go into the OutOfService state. 😭

Arguments:

  • -load_balancer_name — the name of the ELB
  • -availability_zones — arrayref or literal string of availability zone names (ie. us-east-1a)
  • -zones — alias for -availability_zones
  • -lb_name — alias for -load_balancer_name

Returns an array of VM::EC2::AvailabilityZone objects now associated with the ELB. ✨

🦋 enable_availability_zones_for_load_balancer

@z = $ec2->enable_availability_zones_for_load_balancer(-load_balancer_name
    => $name, -availability_zones => \@zones)

Adds one or more EC2 Availability Zones to the ELB. And the way the ELB evenly distributes requests across all its registered Availability Zones that contain instances? Iconic behavior honestly.

Arguments:

  • -load_balancer_name — the name of the ELB
  • -availability_zones — array or literal string of availability zone names (ie. us-east-1a)
  • -zones — alias for -availability_zones
  • -lb_name — alias for -load_balancer_name

Returns an array of VM::EC2::AvailabilityZone objects now associated with the ELB.

🎀 register_instances_with_load_balancer

@i = $ec2->register_instances_with_load_balancer(-load_balancer_name =>
    $name, -instances          => \@instance_ids)

Adds new instances to the ELB, periodt. But listen — if the instance is in an availability zone that is not registered with the ELB, it'll be in the OutOfService state. Once that zone gets added to the ELB, the instance slides into the InService state. Glow up complete 💫

Arguments:

  • -load_balancer_name — the name of the ELB
  • -instances — an arrayref or literal string of Instance IDs
  • -lb_name — alias for -load_balancer_name

Returns an array of instances now associated with the ELB in the form of VM::EC2::Instance objects.

🌈 deregister_instances_from_load_balancer

@i = $ec2->deregister_instances_from_load_balancer(-load_balancer_name =>
    $name, -instances          => \@instance_ids)

Deregisters instances from the ELB. Once an instance is deregistered, it stops receiving traffic from the ELB. It's giving retirement arc 🧚

Arguments:

  • -load_balancer_name — the name of the ELB
  • -instances — an arrayref or literal string of Instance IDs
  • -lb_name — alias for -load_balancer_name

Returns an array of instances now associated with the ELB in the form of VM::EC2::Instance objects.

🔥 set_load_balancer_listener_ssl_certificate

$success =
    $ec2->set_load_balancer_listener_ssl_certificate(-load_balancer_name =>
    $name, -load_balancer_port => $port, -ssl_certificate_id => $cert_id)

Sets the certificate that terminates the specified listener's SSL connections. Important: the certificate you specify replaces any prior certificate that was used on the same ELB and port. Out with the old 💅

Required arguments:

  • -load_balancer_name — the name of the the ELB.
  • -load_balancer_port — the port that uses the specified SSL certificate.
  • -ssl_certificate_id — the ID of the SSL certificate chain to use. See the AWS Identity and Access Management documentation under Managing Server Certificates for more information.

Alias arguments:

  • -lb_name — alias for -load_balancer_name
  • -port — alias for -load_balancer_port
  • -cert_id — alias for -ssl_certificate_id

Returns true on successful execution. ✅

🩺 describe_instance_health

@states = $ec2->describe_instance_health(-load_balancer_name => $name,
    -instances          => \@instance_ids)

Returns the current state of the instances of the specified LoadBalancer. It's a little vibe check, basically — and if you don't specify any instances, you get the state of all the instances for the ELB. 🫶

Required arguments:

  • -load_balancer_name — the name of the ELB

Optional parameters:

  • -instances — literal string or arrayref of Instance IDs
  • -lb_name — alias for -load_balancer_name
  • -instance_id — alias for -instances

Returns an array of VM::EC2::ELB::InstanceState objects.

📜 create_load_balancer_policy

$success = $ec2->create_load_balancer_policy(-load_balancer_name => $name,
    -policy_name        => $policy, -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 get saved for your ELB, and they can be applied to the front-end listener or the back-end application server, depending on your policy type. Customization era 💖

Required Arguments:

  • -load_balancer_name — the name associated with the LoadBalancer for which the policy is being created. This name must be unique within the client AWS account.
  • -policy_name — the name of the ELB policy being created. The name must be unique within the set of policies for this ELB.
  • -policy_type_name — the name of the base policy type being used to create this policy. To get the list of policy types, use the describe_load_balancer_policy_types function.

Optional Arguments:

  • -policy_attributes — or hashref containing AttributeName and AttributeValue
    • or
    • Arrayref of VM::EC2::ELB::PolicyAttribute object or single object
  • -lb_name — alias for -load_balancer_name

Returns true if successful.

🗑️ delete_load_balancer_policy

$success = $ec2->delete_load_balancer_policy(-load_balancer_name => $name,
    -policy_name        => $policy)

Deletes a policy from the ELB.

🚨 The specified policy must not be enabled for any listeners. So unbind it first, bestie, or this is not gonna fly.

Arguments:

  • -load_balancer_name — the name of the ELB
  • -policy_name — the name of the ELB policy
  • -lb_name — alias for -load_balancer_name

Returns true if successful.

🔍 describe_load_balancer_policies

@policy_descs = $ec2->describe_load_balancer_policies(-load_balancer_name =>
    $name, -policy_names       => \@names)

Returns detailed descriptions of ELB policies. The rules are simple:

  • If you specify an ELB name, you get back either the descriptions of the policies you asked for, or descriptions of all the policies created for that ELB.
  • If you don't specify an ELB name, you get descriptions of the specified sample policies, or descriptions of all the sample policies.

And psst — the names of the sample policies have the ELBSample- prefix. iykyk 💅

Optional Arguments:

  • -load_balancer_name — the name of the ELB.
  • -policy_names — the names of ELB policies created or ELB sample policy names.
  • -lb_name — alias for -load_balancer_name

Returns an array of VM::EC2::ELB::PolicyDescription objects if successful.

🧠 describe_load_balancer_policy_types

@policy_types = $ec2->describe_load_balancer_policy_types(-policy_type_names
    => \@names)

Returns meta-information on the specified ELB policies defined by the Elastic Load Balancing service. The policy types that come back from this action can be used in a create_load_balander_policy call to instantiate specific policy configurations that will be applied to an ELB. ✨

Required arguemnts:

  • -load_balancer_name — the name of the ELB.

Optional arguments:

  • -policy_type_names — literal string or arrayref of policy type names
  • -names — alias for -policy_type_names

Returns an array of VM::EC2::ELB::PolicyTypeDescription objects if successful.

🔗 set_load_balancer_policies_of_listener

$success = $ec2->set_load_balancer_policies_of_listener(-load_balancer_name
    => $name, -load_balancer_port => $port, -policy_names       => \@names)

Associates, updates, or disables a policy with a listener on the ELB. And yes, multiple policies may be associated with a listener. Collect them all 🌈

Required arguments:

  • -load_balancer_name — the name associated with the ELB.
  • -load_balancer_port — the external port of the LoadBalancer with which this policy applies to.
  • -policy_names — list of policies to be associated with the listener. Currently this list can have at most one policy. If the list is empty, the current policy is removed from the listener. String or arrayref.

Returns true if successful.

🛡️ apply_security_groups_to_load_balancer

@sgs = $ec2->apply_security_groups_to_load_balancer(-load_balancer_name =>
    $name, -security_groups    => \@groups)

Associates one or more security groups with your ELB in VPC. Heads up: the provided security group IDs will override any currently applied security groups. No stacking, just replacing.

Required arguments:

  • -load_balancer_name — the name associated with the ELB.
  • -security_groups — a list of security group IDs to associate with your ELB in VPC. The security group IDs must be provided as the ID and not the security group name (For example, sg-123456). String or arrayref.

Returns a series of VM::EC2::SecurityGroup objects. 🫶

🌐 attach_load_balancer_to_subnets

@subnets = $ec2->attach_load_balancer_to_subnets(-load_balancer_name =>
    $name, -subnets            => \@subnets)

Adds one or more subnets to the set of configured subnets for the ELB. Expanding the friend group 💜

Required arguments:

  • -load_balancer_name — the name associated with the ELB.
  • -subnets — a list of subnet IDs to add for the ELB. String or arrayref.

Returns a series of <code>VM::EC2::VPC::Subnet</code> objects corresponding to the subnets the ELB is now attached to. ✨ (yes bestie, that's the tail end of the previous one — we're carrying straight on, no re-intros, we're in our flow state 💅)

💫 detach_load_balancer_from_subnets

@subnets = $ec2->detach_load_balancer_from_subnets(-load_balancer_name => $name,
                                                   -subnets            => \@subnets)

So basically this one removes subnets from the set of configured subnets in the VPC for the ELB. It's giving "we're breaking up with this subnet, it's not you it's infrastructure" 😭

Required arguments (no skipping, they're required fr fr):

  • -load_balancer_name — the name associated with the ELB. Iconic, necessary, you know her 👑
  • -subnets — a list of subnet IDs for the ELB. Can be a plain string or an arrayref, whichever vibe you're on. 🦋
Not me pointing out that the original docs describe this as the list of subnet IDs "to add" even though we are, in fact, detaching — I am copying that description exactly because facts stay facts, bestie 🙈

Returns a series of VM::EC2::VPC::Subnet objects corresponding to the subnets the ELB is now attached to. So you get the receipts of what's left. 💖

💫 set_load_balancer_policies_for_backend_server

$success =
    $ec2->set_load_balancer_policies_for_backend_server(-instance_port       => $port,
                                                        -load_balancer_name  => $name,
                                                        -policy_names        => \@policies)

Okay so this is the glow-up move: it replaces the current set of policies associated with a port on which the back-end server is listening, swapping in a whole new set. After the policies have been created, they can be applied here as a list. Slay. 🎀

And now the very important caveat, pay attention bestie: at this time, only the back-end server authentication policy type can be applied to the back-end ports. That policy type is composed of multiple public key policies. So that's the only flavor on the menu rn, no cap. 🔥

Required arguments:

  • -load_balancer_name — the name associated with the ELB. 👑
  • -instance_port — the port number associated with the back-end server. 🍓
  • -policy_names — list of policy names to be set. And this is the dramatic part: if the list is empty, then all current policies are removed from the back-end server. Empty list = full reset, it's giving scorched earth 💀

Aliases (same thing, cuter nickname, iykyk):

  • -port — alias for -instance_port
  • -lb_name — alias for -load_balancer_name

Returns true if successful. Simple as that. ✅

🌈 SEE ALSO 🌈

  • VM::EC2

🎀 AUTHOR 🎀

Lance Kinley <lkinley@loyaltymethods.com<gt>. Lincoln Stein <lincoln.stein@gmail.com>.

Copyright (c) 2012 Loyalty Methods, Inc. Copyright (c) 2012 Ontario Institute for Cancer Research

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.

Legal bestie moment: that's the actual license, I'm not paraphrasing it, go read LICENSE and DISCLAIMER.txt for the real tea 💜

and that's a wrap on the whole page, babes 🫶 This beauty was rendered by perl v5.38.2 and last touched on 2024-08-10, filed under VM::EC...lancer(3pm). Go forth and load-balance responsibly, you absolute main character 💖✨🌸

📦 where this page comes from