GCP

The GCP provider maps Kyku abstract resources to Google Cloud Platform services via REST APIs (Compute Engine, Cloud SQL, Cloud DNS, Cloud Storage, IAM, Cloud Load Balancing).

Credentials

# Application Default Credentials (recommended)
gcloud auth application-default login

# Service account key file
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
export GOOGLE_PROJECT_ID=my-project

# OIDC for CI/CD
export KYKU_GCP_WORKLOAD_PROVIDER=projects/123/locations/global/workloadIdentityPools/my-pool/providers/github
export KYKU_GCP_SERVICE_ACCOUNT=deployer@my-project.iam.gserviceaccount.com
export KYKU_GCP_PROJECT_ID=my-project

Kyku uses google-auth-library for ADC and OIDC token exchange. Tokens are cached with a 1-minute margin before expiry.

Supported Resources

Resource	GCP Service	Status
Vpc	VPC Network	✅
Subnet	VPC Network (synthetic)	✅
Vm	Compute Engine	✅
SecurityGroup	Firewall Rules	✅
LoadBalancer	Cloud LB stack (5+ resources)	✅
TargetGroup	—	❌
Database	Cloud SQL	✅
Identity	Service Account	✅
Role	Custom Role	✅
SshKey	—	❌
Bucket	Cloud Storage	✅
DnsZone	Cloud DNS	✅
DnsRecord	Cloud DNS	✅
Custom	wired	✅

Instance Type Mapping

Abstract	GCP Compute	GCP Cloud SQL
micro	e2-micro	db-f1-micro
small	e2-small	db-g1-small
medium	e2-medium	db-custom-2-8192
large	e2-standard-4	db-custom-4-16384
xlarge	e2-standard-8	db-custom-8-32768
2xlarge	e2-standard-16	db-custom-16-65536
4xlarge	e2-standard-32	db-custom-32-131072
8xlarge	n2-standard-48	db-custom-48-196608

Cloud SQL uses a separate CLOUD_SQL_INSTANCE_MAP (compute types vs DB tiers).

Image Mapping

Abstract	GCP Image
ubuntu-22.04	ubuntu-2204-jammy-v20240101
ubuntu-24.04	ubuntu-2404-noble-v20240101
debian-12	debian-12-bookworm-v20240101

Region Mapping

GCP uses provider-native region names directly (no abstract mapping layer). Abstract regions (us-east, eu-central) are passed through as-is because GCP region names like us-central1, europe-west3 already follow the same pattern.

Override with provider-specific region:

region: { gcp: 'us-west1' }

Gotchas

Custom Config

Every resource manager accepts a customConfig object merged directly into the underlying GCP request body — see Custom Config. @kykucloud/gcp exports typed aliases for nearly every resource: GcpVpcCustomConfig/GcpVmCustomConfig/GcpSecurityGroupCustomConfig/GcpVolumeCustomConfig/GcpAutoScalingGroupCustomConfig from @google-cloud/compute, plus GcpBucketCustomConfig/GcpDnsZoneCustomConfig/GcpSecretCustomConfig/GcpKmsKeyCustomConfig/GcpQueueCustomConfig/GcpCacheCustomConfig/GcpKubernetesClusterCustomConfig/GcpCertificateCustomConfig/GcpDatabaseCustomConfig/GcpLoadBalancerCustomConfig from dedicated @google-cloud/* SDK deps added purely for their request types (the GCP provider itself still calls the REST API directly, not through these SDKs). Identity/Role are the one gap — no clean client library covers IAM Admin’s service-account/custom-role request shapes, only IAM policy APIs.

Vpc/Vm also have real update routing now, not just create-time merging: VPC’s description/mtu/routingConfig/networkFirewallPolicyEnforcementOrder/ULA-IPv6 fields route through the network PATCH; VM’s metadata (including startup-script for vm.userData), scheduling, deletionProtection, and shielded-instance integrity policy route through their respective GCP setters (fetching the current fingerprint first, where GCP requires one). Fields that require a TERMINATED instance (service account, shielded config, display device, machine type) stay create-only.

Multi-Resource LB Stack

GCP Load Balancers require 5+ resources to be created in order:

1. Health check
2. Backend service
3. URL map
4. Target HTTP/HTTPS proxy
5. Forwarding rule

Destroy follows the reverse order. Kyku handles this transparently within the LoadBalancerManager.

Cloud SQL is Slow

Cloud SQL instance creation takes 10–15 minutes. Kyku polls with 120 attempts × 5s = 600s timeout. Use --parallelism 1 to avoid overwhelming the sqladmin API.

Cloud SQL Uses Separate API

Cloud SQL uses sqladmin.googleapis.com (not the Compute Engine API). Kyku constructs URLs as https://sqladmin.googleapis.com/v1/projects/{project}/instances.

Firewall Rules: One Per Ingress/Express Entry

GCP does not support multiple rules in a single firewall resource. Kyku creates separate firewall resources named ${sg.name}-ingress-0, ${sg.name}-ingress-1, etc. Destroy removes all by name prefix.

Firewall Rule Format

GCP firewall rules use network URLs and target tags:

network: `${baseUrl}/global/networks/${name}`
targetTags: [sg.name]
direction: 'INGRESS' | 'EGRESS'

Unsupported Resources

• TargetGroup: No GCP equivalent — use managed instance groups and throw UnsupportedFeatureError.
• SshKey: GCP stores SSH keys in project-level metadata. Use vm.sshPublicKey directly (set in instance metadata via ssh-keys key).

Naming Constraints

Constraint	Limit
Max length	62 chars
Allowed chars	[a-z0-9-]
Normalizer	normalizeGcpName() strips invalid chars

Labels Format

GCP labels use {key: value} with strict limits:

• Keys: ≤ 62 chars, [a-z0-9_-]
• Values: ≤ 63 chars, [a-z0-9_-]

The toGcpLabels() helper normalizes all labels. Labels are separate from firewall targetTags.

IAM Uses Separate API Base

IAM operations use iam.googleapis.com:

• Service Accounts: POST /v1/projects/{project}/serviceAccounts
• Custom Roles: POST /v1/projects/{project}/roles

Operations API Polling

POST/PATCH/DELETE return a selfLink. Poll with GET every 2s until status === 'DONE'.

Subnet is Synthetic

GCP subnet resources are auto-injected by the planner (no standalone cloud resource). The SubnetManager.readState checks if the parent VPC exists. Create/destroy are no-ops handled by VpcManager.

process.env in Bun

GCP provider uses (globalThis as any).process?.env?.VAR for env var access instead of @types/node.