LoadBalancer

A LoadBalancer distributes incoming traffic across a set of virtual machines. It can be an application layer (HTTP/HTTPS) or network layer (TCP/UDP) load balancer. On AWS this is an ALB or NLB, on GCP a multi-resource LB stack, on Hetzner a Load Balancer, and on DigitalOcean a Load Balancer.

Config

Property	Type	Required	Description
name	string	yes	Unique resource name
id	string	no	Explicit ID (auto-generated UUID if omitted)
provider	string	no	Provider label for multi-provider configs
tags	Record<string, string>	no	Arbitrary key-value metadata
lbType	'application' | 'network'	yes	Application (HTTP/HTTPS) or Network (TCP/UDP) LB
vpc	Vpc | string	yes	Vpc to attach the LB to
listeners	LoadBalancerListener[]	yes	Port/protocol listeners with targets
healthCheck	HealthCheck	no	Health check configuration
spanAcrossAzs	boolean	no	Spread across availability zones (default true)
securityGroups	(SecurityGroup | string)[]	no	Security groups attached to the LB
size	string	no	Abstract size (provider-specific mapping)
staticIp	StaticIp | string	no	Reserved public IP referenced at create time

LoadBalancerListener

Property	Type	Required	Description
port	number	yes	Listener port
protocol	'http' | 'https' | 'tcp' | 'udp'	yes	Listener protocol
certificate	string	no	SSL/TLS certificate ARN or reference
targets	LoadBalancerTarget[]	yes	Target VMs and ports

LoadBalancerTarget

Property	Type	Required	Description
vm	Vm | string | OutputValue	yes	Target VM or output reference
port	number	yes	Target port

HealthCheck

Property	Type	Required	Description
protocol	'http' | 'https' | 'tcp'	yes	Health check protocol
port	number	yes	Health check port
path	string	no	Health check path (HTTP/HTTPS only)
interval	number	no	Check interval in seconds
timeout	number	no	Check timeout in seconds
healthyThreshold	number	no	Consecutive successes to mark healthy
unhealthyThreshold	number	no	Consecutive failures to mark unhealthy

Example

import { Vpc, Vm, LoadBalancer } from '@kykucloud/types'

const myVpc = new Vpc({ name: 'my-vpc', cidr: '10.0.0.0/16', region: 'eu-central' })

const server = new Vm({
  name: 'web',
  instanceType: 'small',
  image: 'ubuntu-24.04',
  network: myVpc,
})

const lb = new LoadBalancer({
  name: 'web-lb',
  lbType: 'application',
  vpc: myVpc,
  listeners: [{
    port: 443,
    protocol: 'https',
    targets: [{ vm: server, port: 8080 }],
  }],
  healthCheck: { protocol: 'tcp', port: 8080, interval: 10, timeout: 5 },
})

Provider Support

Provider	Supported	Backend
AWS	✅	ALB (application) / NLB (network)
GCP	✅	Multi-resource stack (health check → backend service → url map → proxy → forwarding rule)
Hetzner	✅	Load Balancer
DigitalOcean	✅	Load Balancer (with size_unit)

Notes

• GCP LB is composed of 5+ resources: health check, backend service, URL map, target HTTP(S) proxy, and forwarding rule. Destroy reverses this order.
• AWS ALB name limit is 32 characters (not 255). ALB provisioning uses State.Code — poll for active, handle failed state.
• Hetzner LB network attachment is async. Poll the private_net field before adding targets (up to 120s). POST to /load_balancers does not return private_net — must poll GET.
• DigitalOcean LB uses size_unit (1–100) for sizing, not named sizes. Map abstract size config to size_unit.
• Label selectors preferred over server IDs for target registration to avoid lookup race conditions and ordering issues.
• AWS listeners support SSL termination via certificate (ACM ARN).