AWS (EKS)
Run shpyrd on Amazon EKS - the network, cluster and VPN from Terraform, then one command for the platform.
On shpyrd cloud the platform is run for you: see Getting started. This page is for running shpyrd yourself, in your own AWS account. The aws profile installs shpyrd on Amazon EKS with Network Load Balancers for the public and the internal front door, Let's Encrypt certificates, Route 53 automation, an in-cluster registry and network policy enforcement from the VPC CNI. The reference infrastructure lives in contrib/aws as Terraform, including an AWS Client VPN as the way into private parts of the platform; the platform itself is shpyrd cluster init.
What you get
| Network | a VPC (10.0.0.0/16) with two public subnets (load balancers, one NAT gateway per zone) and two private /19 subnets for nodes and pods (the VPC CNI gives pods VPC addresses) |
| Cluster | EKS in API authentication mode (the Terraform caller is the first administrator), a private API endpoint (reachable over the VPN; a public one restricted to your address is opt-in), one managed node group on Amazon Linux 2023, labelled as the platform pool (shpyrd.io/pool=platform: the installer pins the platform's pods to it), standard support only |
| Credentials | EKS Pod Identity: IAM roles associated with the service accounts that need AWS (the load balancer controller, the EBS and EFS CSI drivers, ExternalDNS, cert-manager). The cluster's Terraform creates no access keys; the optional object storage module below is the one exception |
| Front doors | Network Load Balancers from the AWS Load Balancer Controller with pod targets: an internet-facing one on two Elastic IPs (static addresses for allow-lists and apex A records), an internal one for projects marked internal (Domains and exposure). DNS uses their hostnames as alias records |
| Certificates | Let's Encrypt; with the zone in Route 53, one wildcard certificate for every project hostname through cert-manager's Route 53 solver |
| Registry | the in-cluster registry with TLS from the platform CA |
| Isolation | the VPC CNI's own network policy agent enforces NetworkPolicy (no Calico needed) |
| Storage | EBS gp3 (encrypted, snapshots) for project disks, databases and the platform's own disks; the node's disk only for disks made before this version; EFS for shared volumes (Resources) |
| DNS | optional: a public zone in Route 53 managed by ExternalDNS, delegated from your registrar once |
| Access | optional: an AWS Client VPN endpoint into the VPC, with a profile for the AWS VPN Client |
Prerequisites
- An AWS account and the
awsCLI configured (a named profile or the environment). - Terraform 1.5+ or OpenTofu,
kubectl. - A domain (or a subdomain of one) for the platform, for example
aws.example.com, whose zone can live in Route 53. - The
shpyrdCLI (Installation); the AWS VPN Client for the VPN.
1. Network, cluster and VPN
git clone https://github.com/shpyrd-io/shpyrdcd shpyrd/contrib/aws/terraformcp terraform.tfvars.example terraform.tfvarsFill in terraform.tfvars:
profile = "default" # aws CLI profile; "" for the environmentregion = "us-east-1"name = "shpyrd-prod"
kubernetes_version = "1.36"node_instance_type = "t3a.large"node_count = 2# nat_gateway_per_az = false # one shared NAT gateway instead of one per zone
dns_zone = "aws.example.com" # public zone in Route 53; "" for nonevpn = true # Client VPN endpoint + profile: the way to kubectlshared_storage = true # EFS for shared volumes# api_public_access = true # also a public API endpoint, restricted to your addressterraform initterraform apply # about 15 minutesterraform output next_steps prints the rest: the kubectl context script, where the VPN profile was written, the zone's name servers and the full shpyrd cluster init command.
2. Connect the VPN
The Kubernetes API is private: only the VPC and VPN clients reach it. Terraform generated a certificate authority, the server certificate (imported to ACM) and one client certificate, and wrote contrib/aws/terraform/<name>-vpn.ovpn. Import it in the AWS VPN Client (File > Manage Profiles > Add Profile) and connect. The tunnel is split: only the VPC range goes through it, and DNS goes to the VPC resolver so private names resolve.
Connected, you reach what the internet cannot: the API endpoint, the internal front door (projects marked exposure: internal, or the whole platform with --set SHPYRD_PLATFORM_EXPOSURE=internal). The profile is a credential; keep it with the Terraform state (it is git-ignored) and rotate it by tainting tls_private_key.vpn_client.
3. Reach the cluster
cd .. # contrib/aws./kubeconfig.sh # writes the kubectl context eks-<name>kubectl --context eks-shpyrd-prod get nodes4. Delegate the zone
With dns_zone set, Terraform created the zone in Route 53. Delegate it once from the parent zone at your registrar, with the name servers from terraform output dns_zone_nameservers:
aws NS ns-1211.awsdns-23.orgaws NS ns-1671.awsdns-16.co.ukaws NS ns-302.awsdns-37.comaws NS ns-713.awsdns-25.netNothing in the zone is written by Terraform or by hand: ExternalDNS publishes *.aws.example.com as an alias of the external load balancer as soon as the platform is up, and one record per internal hostname pointing at the internal one.
5. Install the platform
Terraform wrote every value the platform needs from the infrastructure into contrib/aws/terraform/<name>.vars — you never copy an identifier by hand. The command terraform output next_steps printed:
shpyrd cluster init --context eks-shpyrd-prod --profile aws --vars-file contrib/aws/terraform/shpyrd-prod.vars \ --set SHPYRD_ACME_EMAIL=you@example.com --enable auth-localWhat the file carries, and where each value comes from:
| Value | Meaning | Source |
|---|---|---|
SHPYRD_DOMAIN | the platform's domain | dns_zone |
SHPYRD_AWS_CLUSTER, SHPYRD_AWS_REGION, SHPYRD_AWS_VPC_ID | what the load balancer controller manages | the cluster; discovered from the cluster itself when absent |
SHPYRD_AWS_LB_EIPS, SHPYRD_LB_IP | the public front door's Elastic IPs (allocation ids for the controller, addresses for the project's Domains page) | the two aws_eip.lb |
SHPYRD_EFS_ID | the file system behind shared volumes | shared_storage |
SHPYRD_DNS_PROVIDER, SHPYRD_DNS_ZONE_ID, SHPYRD_DNS_REGION | Route 53 automation | the hosted zone |
Flags and --set win over the file, so --platform-exposure internal (dashboard and sign-in behind the internal load balancer, VPN only, apps public) or --set SHPYRD_REGISTRY_SIZE=50Gi go on the same command line. On a cluster you did not create with this Terraform, pass the values with --set; the three cluster facts are read from the cluster.
What happens, in order:
| Level | Components |
|---|---|
| rc0 | Prometheus Operator CRDs |
| rc1 | the node-local storage class (for the project disks that still use it), the AWS Load Balancer Controller, cert-manager (with ambient credentials for Route 53), the registry credential, the platform's Service, the snapshot controller and the EBS snapshot class, the gp3 and shpyrd-efs storage classes; the S3 gateway with a bucket |
| rc2 | Let's Encrypt issuers, the platform CA and trust bundle, ingress-nginx behind an internet-facing NLB on the Elastic IPs and the internal one behind an internal NLB (both with pod targets), the registry and the node trust for it, ExternalDNS |
| rc3 | kpack with the Paketo builder, kube-prometheus-stack, the wildcard certificate, the control-plane database |
| rc4 | the shpyrd server, the platform backup schedule (with a backup target) |
The installer waits for the load balancer hostname, for shpyrd.<domain> to resolve on public resolvers and for the certificates. The summary at the end:
Dashboard: https://shpyrd.aws.example.com Registry: in-cluster at 10.100.0.50:5000 (TLS from the platform CA, credential in Secret shpyrd-registry) External LB: k8s-ingressn-ingressn-015ed2971e-ae9f48a7eeaa7d9f.elb.us-east-1.amazonaws.com (ExternalDNS: *.aws.example.com) Internal LB: k8s-ingressn-ingressn-60fb9cbfd6-a7ec35b89089177e.elb.us-east-1.amazonaws.com (ExternalDNS: per host, exposure:internal)Everything you passed is recorded in the cluster: later runs (brew upgrade shpyrd && shpyrd cluster init --context eks-shpyrd-prod --profile aws) need no flags.
6. First sign-in and first project
Configure identities and authorize console and workspace access as described in
Oracle Cloud, first sign-in. Credentials live
in the configured IdP or Dex static configuration, not a Core users API. Use the
eks-shpyrd-prod context for operator commands; the developer CLI uses workspace
sign-in (shpyrd login).
Costs
At the defaults, on demand in us-east-1: the EKS control plane $0.10 per hour, two t3a.large nodes $0.15, two NAT gateways $0.09 plus data (nat_gateway_per_az = false halves it), two Network Load Balancers $0.045, the Client VPN association $0.10 plus $0.05 per connection; about $0.50 per hour all in. EBS gp3 $0.08 per GB-month for the platform's disks, EFS by the space used, the zone $0.50 per month. A development cluster is created for a working session and destroyed after it.
Good to know
- Addresses and hostnames. The public front door has two static Elastic IPs (the A-record targets for a zone apex, shown on the project's Domains page) and a DNS name that ExternalDNS uses for alias records; the internal one has a DNS name only. Load balancers are managed by the AWS Load Balancer Controller with pod targets; an ALB is not used because it would terminate TLS with ACM certificates, which does not fit per-domain certificates from cert-manager.
- Network policy. The VPC CNI enforces it with its own agent;
cluster initrecognises it and installs nothing. - Project disks and databases are EBS volumes (
gp3): they grow withshpyrd volumes resize, have nightly snapshots, and follow their process or database to another node in the zone. Disks and databases made before this version are on the node's own disk (shpyrd-local) until migrated; the class stays installed while any remains.SHPYRD_PROJECT_STORAGE_CLASS=shpyrd-localandSHPYRD_DATABASE_STORAGE_CLASS=shpyrd-localput new ones on the node's disk again, on purpose. - Moving data off a node's disk. Disks and databases made before block storage are on a node's own disk (
shpyrd-local);shpyrd-ctl cluster statuslists them.shpyrd-ctl storage migrate database <namespace>/<name>moves a database by switchover (a pinned one needsshpyrd-ctl cluster unpin <project-id>first);shpyrd-ctl storage migrate volume <project-id> <volume> --yesmoves a volume through the project move, pausing the project for the copy. The old disk is kept for three days; the project's placement page lists and releases it. - Shared volumes are EFS access points (
shared_storage = true). Name the class when you create one:shpyrd volumes create assets --size 20Gi --shared --class shpyrd-efs. - Object storage in a bucket.
contrib/aws/terraform/object-storagecreates an S3 bucket and writes<name>-objects.env.--object-storage-credentials-filewith that file sends every bucket the platform hands out, Postgres backups included, through the S3 gateway to that one bucket. It uses an IAM user's access key, written to that file. - Existing clusters. The profile works on any EKS cluster that has the same add-ons and Pod Identity associations as the Terraform creates (CSI drivers,
kube-system/aws-load-balancer-controller,shpyrd-system/external-dns,cert-manager/cert-manager, andshpyrd-system/shpyrd-serverfor backups), and subnets tagged for the in-tree load balancer discovery. - Upgrading.
brew upgrade shpyrdthenshpyrd cluster initon the context. - Platform backups.
contrib/aws/terraform/backupscreates an S3 bucket that outlives the cluster;backup_bucketin the cluster root grants the platform's service account access through Pod Identity (no keys) and puts the target in the vars file. Nightly archives,shpyrd cluster backupnow,shpyrd cluster restoreon a new cluster: Platform backups.
Tear down
shpyrd cluster destroy --context eks-shpyrd-prod # projects and their data, load balancers, diskscd contrib/aws/terraform && terraform destroy # cluster, network, zone, VPNkubectl config delete-context eks-shpyrd-prodThe zone's delegation at the registrar is the one thing left to remove by hand. The backup bucket (contrib/aws/terraform/backups) is untouched: it is there to restore from; terraform destroy in that directory removes it when the archives are no longer wanted.