AWS Elastic Load Balancing ExecModule

Overview

AwsElbModule brings governed AWS Elastic Load Balancing v2 operations into ValkyrAI workflows. It discovers Application, Network, and Gateway Load Balancers, listeners, certificates, target groups, and target health; creates or deletes an exact load balancer; adds or removes one listener certificate; and registers or deregisters bounded targets.

The module uses ValkyrAI's native map ABI, annotation-backed Workflow Studio discovery, and a verified IntegrationAccount. Workflow input never accepts AWS access keys, secret keys, session tokens, or authorization headers.

The connector is designed for deployment gates, health-aware remediation, controlled certificate rotation, and reviewed infrastructure workflows. Every provider mutation requires an operation-specific confirmation and is sent once. Read operations may retry transient failures with bounded backoff.

Usage

1. Create or select a least-privilege AWS identity for the reviewed ELB actions.
2. Store its access-key pair in an AWS IntegrationAccount.
3. Verify the account and ensure its status is READY.
4. Add AwsElbModule to the workflow and bind that account through ExecModuleConfig.authConfig.integrationAccount.
5. Choose an operation, AWS region, and exact resource scope.
6. For mutations, review current AWS state and set only the matching confirmation field to true.

Never place credentials in module input. Credential-shaped fields are rejected before any AWS request.

Inputs

Common inputs

Input	Type	Required	Default	Purpose
operation	string	Yes	—	One supported ELB operation.
region	string	Yes	—	AWS region such as us-west-2.
marker	string	No	—	Opaque continuation marker for a list operation.
limit	integer	For lists	100	Total result bound from 1 to 1,000.
returnAll	boolean	For lists	false	Follow provider pages until limit or a provider boundary.

Resource scope

Input	Used by	Rules
loadBalancerArn	Exact read/delete, listener list, target-group list	Must be an exact ELB load-balancer ARN.
loadBalancerName	Exact read or creation	1–32 alphanumeric or hyphen characters; cannot begin or end with -.
listenerArn	Certificate list/add/remove	Must be an exact ELB listener ARN.
certificateArn	Certificate add/remove	Must be an exact ACM certificate or IAM server-certificate ARN.
targetGroupArn	Target health/register/deregister	Must be an exact ELB target-group ARN.

get_load_balancer accepts exactly one of loadBalancerArn or loadBalancerName.

Load-balancer creation

Input	Type	Default	Notes
loadBalancerType	string	application	application, network, or gateway.
scheme	string	internet-facing	internet-facing or internal; Gateway Load Balancers require internal.
ipAddressType	string	ipv4	ipv4 or dualstack; Gateway Load Balancers require ipv4.
subnetIds	string array	—	Application Load Balancers require at least two; other supported types require at least one.
securityGroupIds	string array	[]	Up to five exact IDs; unavailable for Gateway Load Balancers.
tags	object array	[]	Up to 50 unique {key, value} objects; aws: keys are rejected.
confirmCreateLoadBalancer	boolean	false	Must be true for creation.

The module requests load-balancer creation but does not wait for the resource to become active. Follow the returned ARN with get_load_balancer and treat provider state as the readiness signal.

Target inputs

targets is an array of 1–100 objects:

[
  {
    "id": "i-0123456789abcdef0",
    "port": 8080,
    "availabilityZone": "us-west-2a"
  }
]

• id is the exact instance ID, IP address, Lambda ARN, or supported load-balancer ARN expected by the target group's target type.
• port is optional and must be between 1 and 65,535.
• availabilityZone is optional and may be an exact zone or all where AWS supports it.
• describe_target_health may omit targets to read every bounded target returned by AWS.
• register_targets and deregister_targets require confirmTargetChange: true.

Other confirmations

Mutation	Confirmation
delete_load_balancer	confirmDeleteLoadBalancer: true
add_listener_certificate	confirmCertificateChange: true
remove_listener_certificate	confirmCertificateChange: true

Outputs

Successful output uses a stable envelope:

Output	Meaning
status	success or error.
operation	Normalized operation name.
attempts	Provider calls, including pages and read retries.
resultType	Resource or control family.
items / count	Bounded normalized list or target-health records.
pages	Provider pages consumed by a list operation.
hasMore / marker	Whether and where provider pagination may continue.
data	Exact resource, health summary, or mutation receipt.
requestId	Safe AWS request reference when available.
error	Safe error code, message, HTTP status, and retryability.

Normalized resource output includes only useful operational fields. It excludes credentials, signed material, authorization headers, and raw provider exception text.

IntegrationAccount Requirements

The bound account must be verified, have status READY, and supply its AWS access-key ID through apiKey plus its secret access key through password. The module never serializes those fields into output or logs.

Grant only the actions used by the workflow. Depending on selected operations, that can include:

elasticloadbalancing:DescribeLoadBalancers
elasticloadbalancing:CreateLoadBalancer
elasticloadbalancing:DeleteLoadBalancer
elasticloadbalancing:DescribeListeners
elasticloadbalancing:DescribeListenerCertificates
elasticloadbalancing:AddListenerCertificates
elasticloadbalancing:RemoveListenerCertificates
elasticloadbalancing:DescribeTargetGroups
elasticloadbalancing:DescribeTargetHealth
elasticloadbalancing:RegisterTargets
elasticloadbalancing:DeregisterTargets

Scope mutating permissions to reviewed resource ARNs, regions, VPCs, subnets, security groups, certificates, and target groups where AWS IAM supports those conditions. Load-balancer creation may also require permission to create service-linked roles in an account where ELB has not created them already.

Configuration

The module uses ExecModuleConfig for the account binding, retry ceiling, and workflow-level policy. It does not accept endpoint overrides, custom signing hosts, arbitrary SDK options, or inline IAM policy documents.

Reads use at most five attempts, bounded by the configured maxAttempts. Provider SDK retries are disabled so the module owns the visible attempt count. Mutations always use one provider call even if AWS reports a transient failure.

Operations

Operation	Behavior	Side effect
list_load_balancers	Lists bounded load balancers.	None
get_load_balancer	Reads one exact load balancer by ARN or name.	None
create_load_balancer	Requests one confirmed ALB, NLB, or Gateway Load Balancer.	Creates infrastructure
delete_load_balancer	Deletes one confirmed exact load balancer.	Destructive
list_listeners	Lists listeners for one exact load balancer.	None
list_listener_certificates	Lists certificates for one exact listener.	None
add_listener_certificate	Adds one confirmed ACM or IAM certificate.	Changes TLS routing
remove_listener_certificate	Removes one confirmed non-default certificate.	Changes TLS routing
list_target_groups	Lists bounded target groups, optionally scoped to one load balancer.	None
describe_target_health	Reads provider health for all or selected targets.	None
register_targets	Registers 1–100 confirmed exact targets.	Changes traffic eligibility
deregister_targets	Deregisters 1–100 confirmed exact targets.	Changes traffic eligibility

Errors and Failure Modes

Code	Meaning	Retry guidance
VALIDATION_ERROR	Input, identifier, bound, target shape, or confirmation failed locally.	Correct input; no AWS call occurred.
INTEGRATION_ACCOUNT_ERROR	The account is missing, unverified, not READY, or incomplete.	Repair the account binding.
AWS_ELB_HTTP_400	AWS rejected the resource, state, network configuration, target, certificate, or quota.	Usually no; inspect exact state first.
AWS_ELB_HTTP_403	IAM denied the action or resource.	Add only the missing least-privilege permission.
AWS_ELB_HTTP_404	A referenced ARN no longer exists.	Reconcile discovery output.
AWS_ELB_HTTP_429 / 500 / 502 / 503 / 504	Throttling or transient provider pressure.	Reads retry; mutations report ambiguity.
NETWORK_ERROR	AWS could not be reached.	Reads may retry; reconcile any attempted mutation before replay.
EXECUTION_ERROR	An unexpected local failure was safely normalized.	Use logs and the request envelope; secrets remain redacted.

AWS may accept a mutation before the client observes a timeout. A retryable status is never permission to blindly replay a create, delete, certificate, register, or deregister operation. Discover the exact resource state first.

Example

This example checks a target group before a deployment decision:

{
  "operation": "describe_target_health",
  "region": "us-west-2",
  "targetGroupArn": "arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/valkyrai-web/0123456789abcdef"
}

Expected normalized result:

{
  "status": "success",
  "operation": "describe_target_health",
  "attempts": 1,
  "resultType": "target_health",
  "count": 2,
  "items": [
    {
      "id": "i-0123456789abcdef0",
      "port": 8080,
      "availabilityZone": "us-west-2a",
      "state": "healthy"
    },
    {
      "id": "i-0fedcba9876543210",
      "port": 8080,
      "availabilityZone": "us-west-2b",
      "state": "unhealthy",
      "reason": "Target.ResponseCodeMismatch"
    }
  ],
  "data": {
    "targetGroupArn": "arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/valkyrai-web/0123456789abcdef",
    "count": 2
  },
  "requestId": "example-request-id"
}

The workflow can stop the rollout, alert an operator, or open a separately reviewed deregistration step. Health output reflects AWS's observation at request time; it is not a continuous monitor.

Notes

• Pagination: List operations return marker and hasMore. returnAll: true follows at most 100 pages and never returns more than limit items.
• Rate limits: AWS throttling varies by API, account, and region. Bound list sizes and avoid tight polling loops.
• API limits: This module caps lists at 1,000 items, provider page sizes at 400 or lower, creation tags at 50, security groups at five, and target mutations at 100 targets.
• Idempotency: Reads are repeatable. Mutations are not assumed idempotent and are never automatically retried.
• Destructive behavior: Deletion removes the load balancer, and deregistration can remove production traffic capacity. Both require exact ARNs or target IDs plus explicit confirmation.
• Certificate safety: Removing the default certificate is rejected by AWS. Discover the current certificate list and default marker before a change.
• Target drain: A successful deregistration response means AWS accepted the request; connection draining and deregistration delay may continue afterward.
• Creation boundary: Listener, rule, target-group creation, attributes, WAF association, trust stores, zonal shift, and Classic Load Balancer APIs are intentionally deferred.
• Credential boundary: Live AWS behavior is unverified until an authorized least-privilege non-production account and reviewed resources are supplied.
• Functional reference: n8n's AWS ELB node demonstrates load-balancer create/get/list/delete and listener-certificate workflows. ValkyrAI adds strict account binding, exact ARN validation, target-health and registration controls, bounded output, confirmation gates, and mutation replay safety.
• Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsElbModule through /v1/modules/metadata.

Related documentation

• AWS Elastic Load Balancing API Reference
• AWS ELB quotas
• AWS Elastic Container Registry ExecModule