AWS.GlobalAccelerator reference

Accelerator

Source: src/AWS/GlobalAccelerator/Accelerator.ts

An AWS Global Accelerator standard accelerator — two anycast static IP addresses that route client traffic over the AWS global network to the closest healthy regional endpoint.

Accelerators are global resources (the control-plane API lives in us-west-2 regardless of your deployment region — alchemy pins it automatically). Attach Listeners to accept traffic and EndpointGroups to route it to ALBs, NLBs, EC2 instances, or Elastic IPs per region.

Accelerator: Creating Accelerators

Basic Accelerator

import * as GlobalAccelerator from "alchemy/AWS/GlobalAccelerator";

const accelerator = yield* GlobalAccelerator.Accelerator("Edge");

Dual-Stack Accelerator

const accelerator = yield* GlobalAccelerator.Accelerator("Edge", {
  ipAddressType: "DUAL_STACK",
});

Accelerator: Flow Logs

// the bucket policy must grant delivery.logs.amazonaws.com
// s3:PutObject + s3:GetBucketAcl
const accelerator = yield* GlobalAccelerator.Accelerator("Edge", {
  flowLogs: { bucket: logBucket.bucketName, prefix: "ga-flow-logs" },
});

Accelerator: Routing Traffic

const accelerator = yield* GlobalAccelerator.Accelerator("Edge");
const listener = yield* GlobalAccelerator.Listener("Web", {
  acceleratorArn: accelerator.acceleratorArn,
  portRanges: [{ fromPort: 443, toPort: 443 }],
  protocol: "TCP",
});
yield* GlobalAccelerator.EndpointGroup("UsWest2", {
  listenerArn: listener.listenerArn,
  endpointGroupRegion: "us-west-2",
  endpoints: [{ endpointId: alb.loadBalancerArn }],
});

AddEndpoints

Source: src/AWS/GlobalAccelerator/AddEndpoints.ts

Runtime binding for globalaccelerator:AddEndpoints.

Registers additional endpoints (ALB/NLB ARNs, EC2 instance IDs, or Elastic IP allocation IDs) on the bound EndpointGroup at runtime — the dynamic-scaling counterpart to declaring endpoints in the resource props. Unlike a full UpdateEndpointGroup, adding endpoints does not touch the group’s other endpoints or its health-check configuration. The endpoint group ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.GlobalAccelerator.AddEndpointsHttp).

AddEndpoints: Managing Endpoints

// init — bind the operation to the endpoint group
const addEndpoints = yield* AWS.GlobalAccelerator.AddEndpoints(group);

// runtime
yield* addEndpoints({
  EndpointConfigurations: [{ EndpointId: allocationId, Weight: 128 }],
});

DescribeAccelerator

Source: src/AWS/GlobalAccelerator/DescribeAccelerator.ts

Runtime binding for globalaccelerator:DescribeAccelerator.

Reads the bound Accelerator’s live state — deployment status (DEPLOYED / IN_PROGRESS), DNS names, static IP sets, and whether it is enabled — so a function can health-check the accelerator or hand out its DNS name at runtime. The accelerator ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.GlobalAccelerator.DescribeAcceleratorHttp).

DescribeAccelerator: Observing Accelerators

// init — bind the operation to the accelerator
const describeAccelerator =
  yield* AWS.GlobalAccelerator.DescribeAccelerator(accelerator);

// runtime
const { Accelerator } = yield* describeAccelerator();
yield* Effect.log(`${Accelerator?.DnsName} is ${Accelerator?.Status}`);

DescribeEndpointGroup

Source: src/AWS/GlobalAccelerator/DescribeEndpointGroup.ts

Runtime binding for globalaccelerator:DescribeEndpointGroup.

Reads the bound EndpointGroup’s live state — most usefully the observed per-endpoint health (HEALTHY / UNHEALTHY / INITIAL) — so a function can monitor regional endpoint health or verify an endpoint it just registered. The endpoint group ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.GlobalAccelerator.DescribeEndpointGroupHttp).

DescribeEndpointGroup: Observing Endpoint Groups

// init — bind the operation to the endpoint group
const describeEndpointGroup =
  yield* AWS.GlobalAccelerator.DescribeEndpointGroup(group);

// runtime
const { EndpointGroup } = yield* describeEndpointGroup({});
const unhealthy = (EndpointGroup?.EndpointDescriptions ?? []).filter(
  (endpoint) => endpoint.HealthState === "UNHEALTHY",
);

EndpointGroup

Source: src/AWS/GlobalAccelerator/EndpointGroup.ts

A Global Accelerator endpoint group — the set of regional endpoints (ALBs, NLBs, EC2 instances, or Elastic IPs) that a listener routes traffic to in one AWS Region, with traffic-dial and health-check configuration.

One endpoint group per region per listener. Everything except the listener and region is updatable in place.

EndpointGroup: Creating Endpoint Groups

Route to an Application Load Balancer

const group = yield* GlobalAccelerator.EndpointGroup("UsWest2", {
  listenerArn: listener.listenerArn,
  endpointGroupRegion: "us-west-2",
  endpoints: [{ endpointId: alb.loadBalancerArn }],
});

Weighted Endpoints with HTTP Health Checks

const group = yield* GlobalAccelerator.EndpointGroup("UsEast1", {
  listenerArn: listener.listenerArn,
  endpointGroupRegion: "us-east-1",
  endpoints: [
    { endpointId: blueAlb.loadBalancerArn, weight: 200 },
    { endpointId: greenAlb.loadBalancerArn, weight: 55 },
  ],
  healthCheckProtocol: "HTTP",
  healthCheckPath: "/health",
  healthCheckInterval: "10 seconds",
});

EndpointGroup: Traffic Management

const group = yield* GlobalAccelerator.EndpointGroup("Canary", {
  listenerArn: listener.listenerArn,
  endpointGroupRegion: "eu-west-1",
  trafficDialPercentage: 10,
});

Listener

Source: src/AWS/GlobalAccelerator/Listener.ts

A Global Accelerator listener that accepts inbound client connections on an accelerator’s static IP addresses, on one or more port ranges.

Port ranges, protocol, and client affinity are all updatable in place; only moving the listener to a different accelerator replaces it. Attach EndpointGroups to route the accepted traffic to regional endpoints.

Listener: Creating Listeners

TCP Listener

const listener = yield* GlobalAccelerator.Listener("Web", {
  acceleratorArn: accelerator.acceleratorArn,
  portRanges: [{ fromPort: 80, toPort: 80 }],
  protocol: "TCP",
});

Sticky UDP Listener with Multiple Port Ranges

const listener = yield* GlobalAccelerator.Listener("Game", {
  acceleratorArn: accelerator.acceleratorArn,
  portRanges: [
    { fromPort: 3000, toPort: 3100 },
    { fromPort: 4000, toPort: 4000 },
  ],
  protocol: "UDP",
  clientAffinity: "SOURCE_IP",
});

RemoveEndpoints

Source: src/AWS/GlobalAccelerator/RemoveEndpoints.ts

Runtime binding for globalaccelerator:RemoveEndpoints.

Deregisters endpoints from the bound EndpointGroup at runtime — e.g. draining an instance before it is terminated. Unlike a full UpdateEndpointGroup, removing endpoints leaves the group’s other endpoints and health-check configuration untouched. The endpoint group ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.GlobalAccelerator.RemoveEndpointsHttp).

RemoveEndpoints: Managing Endpoints

// init — bind the operation to the endpoint group
const removeEndpoints = yield* AWS.GlobalAccelerator.RemoveEndpoints(group);

// runtime
yield* removeEndpoints({
  EndpointIdentifiers: [{ EndpointId: allocationId }],
});