AWS

The AWS provider maps Kyku abstract resources to native AWS services via the AWS SDK v3 (@aws-sdk/client-ec2, @aws-sdk/client-rds, @aws-sdk/client-iam, @aws-sdk/client-elastic-load-balancing-v2, @aws-sdk/client-s3, @aws-sdk/client-route-53).

Credentials

# Env vars (standard)
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

# Or via AWS SSO
aws sso login --profile my-profile
export AWS_PROFILE=my-profile

# OIDC for CI/CD
export KYKU_AWS_ROLE_ARN=arn:aws:iam::123456789012:role/KykuDeployRole

Kyku auto-detects CI platforms (GitHub Actions, GitLab CI, CircleCI) and exchanges OIDC tokens via STS AssumeRoleWithWebIdentity — no long-lived keys needed.

Supported Resources

Resource	AWS Service	Status
Vpc	EC2-VPC	✅
Subnet	EC2-VPC	✅
Vm	EC2	✅
SecurityGroup	EC2-SG	✅
LoadBalancer	ALB / NLB	✅
TargetGroup	ELBv2 TG	✅
Database	RDS	✅
Identity	IAM User	✅
Role	IAM Role	✅
SshKey	Key Pair	✅
Bucket	S3	✅
DnsZone	Route53	✅
DnsRecord	Route53	✅
Custom	wired	✅

Instance Type Mapping

Abstract	AWS
micro	t3.micro
small	t3.small
medium	t3.medium
large	t3.large
xlarge	t3.xlarge
2xlarge	t3.2xlarge
4xlarge	m6i.4xlarge
8xlarge	m6i.8xlarge

RDS uses a separate mapping with db.* prefix:

Abstract	RDS
micro	db.t3.micro
small	db.t3.small
medium	db.t3.medium
large	db.t3.large
xlarge	db.t3.xlarge
2xlarge	db.t3.2xlarge
4xlarge	db.m6i.4xlarge
8xlarge	db.m6i.8xlarge

Override with provider-specific instance types:

instanceType: { aws: 'm5.large', gcp: 'n2-standard-4' }

Image Mapping

Abstract	AWS AMI
ubuntu-22.04	ami-0c7217cdde317cfec
ubuntu-24.04	ami-04a4fb15521f51d19
debian-12	ami-0c55b159cbfafe1f0

Override with a custom AMI ID:

image: { aws: 'ami-0custom123' }

Region Mapping

Abstract	AWS
us-east	us-east-1
us-west	us-west-2
eu-central	eu-central-1
eu-west	eu-west-1
ap-southeast	ap-southeast-1
ap-south	ap-south-1
ap-northeast	ap-northeast-1
ca-east	ca-central-1

Override with a provider-specific region:

region: { aws: 'eu-west-2', gcp: 'europe-west2' }

Gotchas

Custom Config

Every resource manager accepts a customConfig object merged directly into the underlying AWS SDK request — see Custom Config. AWS has the broadest typed-alias coverage of any provider: @kykucloud/aws exports an Omit<CommandInput, KykuOwnedFields> alias (AwsVpcCustomConfig, AwsVmCustomConfig, AwsSecurityGroupCustomConfig, …) for every resource manager except DnsRecord (its request body is 100% Kyku-owned) and TargetGroup (a synthetic tag-based resource with no AWS create call of its own).

Vpc and Vm also have real update routing, not just create-time merging: Vpc’s EnableDnsHostnames/EnableDnsSupport/EnableNetworkAddressUsageMetrics route through ModifyVpcAttribute; Vm’s termination/stop protection, monitoring, source/dest check, shutdown behavior, and instance metadata options route through their respective EC2 attribute APIs. Vpc.customConfig also exposes subnet/natGateway/routeTable/internetGateway namespaces (flat objects applying to every child object of that type Kyku creates) so you can configure the rest of the network stack Kyku provisions alongside the VPC — see Custom Config. Vm.userData is a first-class portable field now (base64-encoded into RunInstances automatically); it’s immutable after launch, same as AWS itself requires.

SDK v3 Error Names

Each AWS service uses different error names. Kyku catches per-service errors:

Service	Error Name
VPC	InvalidVpcID.NotFound
SecurityGroup	InvalidGroup.NotFound
LoadBalancer	LoadBalancerNotFound
RDS	DBInstanceNotFound
IAM	NoSuchEntity
KeyPair	InvalidKeyPair.NotFound

Name-Based Lookups

Each resource type has a different lookup pattern:

Resource	Lookup Method
VPC	DescribeVpcs + tag:Name filter
EC2	DescribeInstances + tag:Name filter
SecurityGroup	DescribeSecurityGroups + group-name filter
ALB/NLB	DescribeLoadBalancers + Names: [name]
IAM	GetUser(UserName) / GetRole(RoleName)
RDS	DescribeDBInstances (list all, filter client-side)
KeyPairs	DescribeKeyPairs + KeyNames: [name]

VPC Auto-Creates Full Network Stack

When you create a Vpc, Kyku automatically provisions:

• Internet Gateway
• NAT Gateways (one per public subnet, incurring ongoing costs)
• Elastic IPs (one per NAT Gateway)
• Public + private route tables

Destroy cleans up in reverse order: route tables → NATs + EIPs → IGWs → subnets → VPC.

SSH Keys are Key Pairs

AWS treats SSH keys as EC2 Key Pairs. Kyku uses ImportKeyPairCommand to upload the public key. The key name (not public key content) is passed to RunInstances.KeyName. Keys must be pre-imported before VM creation.

ALB Name Limit

ALB names are limited to 32 characters (not 255 like other AWS resources). Kyku validates this in validateLoadBalancer.

RDS Polling

RDS creation is slow — Kyku polls up to 120 attempts × 5s = 600s (10 minutes). RDS instance types use a separate RDS_INSTANCE_TYPE_MAP (db.t3.* prefix), not the standard EC2 mapping.

RDS DB Subnet Group

RDS requires a DB subnet group for VPC placement. Kyku auto-creates this via CreateDBSubnetGroupCommand using the private subnets from the VPC.

Security Group Rule Mapping

AWS IpPermissions format differs from Kyku’s rule model. Kyku implements fromAwsIpPermissions() to reverse-map AWS IpPermissions / IpPermissionsEgress back to the Kyku SecurityGroupRule[] format for config comparison.

IAM Policy Cleanup

Before deleting IAM users/roles, Kyku must detach managed policies (DetachUserPolicy) and delete inline policies (DeleteUserPolicy). Each step catches NoSuchEntity.

Immutable Properties

Changes to these properties trigger destroy + recreate:

Resource	Immutable
Vm	network (can’t move between VPCs)
SecurityGroup	name (AWS can’t rename SGs)
Identity	name (IAM rename is separate)
Role	name (IAM rename is separate)

Tags Format

AWS uses [{Key: string, Value: string}] arrays. The Name tag is set automatically via toAwsTags(tags, name).

AZ Distribution

distributeAcrossAzs: N creates N public subnets + N private subnets (one pair per AZ). The AWS provider always creates a paired public/private topology.