Skip to main content
Shipyard uses a modular, three-tier Terraform architecture to provision and manage infrastructure on AWS. This layered approach ensures proper dependency management, maintainability, and safe deployments.

​
Three-Tier Architecture

The infrastructure is divided into three layers, each building on the previous one: 
┌─────────────────────────────────────────────────────────────────────────────┐
│                              TERRAFORM LAYERS                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐         │
│  │ 1-infrastructure│───▶│   2-platform    │───▶│    3-apps       │         │
│  └─────────────────┘    └─────────────────┘    └─────────────────┘         │
│         │                       │                      │                    │
│         ▼                       ▼                      ▼                    │
│  • VPC & Subnets         • ALB Controller       • ArgoCD                   │
│  • EKS Cluster           • Cert Manager         • Traefik                  │
│  • Tailscale (VPN)       • External Secrets     • App TLS Certs            │
│  • Vault (KMS)           • Vault Helm           • Vault Policies           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

​
Layer 1: Infrastructure

The foundation layer provisions core AWS infrastructure:
  • VPC & Networking: Virtual Private Cloud, subnets, NAT gateways
  • EKS Cluster: Kubernetes cluster and node groups
  • Tailscale VPN: Secure network access via subnet router
  • Vault Infrastructure: KMS keys and DynamoDB tables for secrets management

​
Layer 2: Platform

The platform layer deploys essential Kubernetes components:
  • AWS Load Balancer Controller: Manages ALBs for ingress
  • Cert Manager: Automated TLS certificate management
  • External Secrets Operator: Syncs secrets from Vault to Kubernetes
  • Vault Helm: Deploys Vault server on Kubernetes

​
Layer 3: Apps

The applications layer deploys user-facing services:
  • ArgoCD: GitOps continuous delivery
  • Traefik: Ingress controller and routing
  • Application TLS Certificates: Automated cert provisioning
  • Vault Policies: Application-specific access controls

​
Layer Dependencies

Each layer depends on outputs from the previous layer: 
bootstrap
    │
    ▼
1-infrastructure ──────────────────┐
    │                              │
    │ Outputs:                     │
    │ • vpc_id                     │
    │ • private_subnet_ids         │
    │ • eks_cluster_endpoint       │
    │ • eks_cluster_name           │
    │ • vault_kms_key_id           │
    │                              │
    ▼                              │
2-platform ◀───────────────────────┘
    │
    │ Outputs:
    │ • vault_addr
    │ • cert_manager_ready
    │
    ▼
3-apps

​
Directory Structure

The Terraform code is organized as follows: 
terraform/dev/
├── bootstrap/                    # State bucket & DynamoDB table
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── post-bootstrap.sh         # Updates backend configs after bootstrap
│
├── 1-infrastructure/             # Core AWS infrastructure
│   ├── backend.tf
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── terraform.tfvars
│   ├── vpc.tf                    # VPC, subnets, NAT gateways
│   ├── eks.tf                    # EKS cluster & node groups
│   ├── tailscale.tf              # Tailscale subnet router
│   └── vault.tf                  # Vault infrastructure (KMS, DynamoDB)
│
├── 2-platform/                   # Kubernetes platform components
│   ├── backend.tf
│   ├── providers.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── alb-controller.tf         # AWS Load Balancer Controller
│   ├── cert-manager.tf           # Certificate management
│   ├── external-secrets.tf       # External Secrets Operator
│   ├── vault-helm.tf             # Vault Helm deployment
│   ├── policies/
│   │   └── aws-load-balancer-controller-policy.json
│   └── scripts/
│       └── vault-bootstrap.sh    # Vault initialization script
│
└── 3-apps/                       # Application layer
    ├── backend.tf
    ├── providers.tf
    ├── variables.tf
    ├── outputs.tf
    ├── argocd.tf                 # ArgoCD deployment
    ├── argocd-appset.tf          # ApplicationSets
    ├── argocd-ingress.tf         # ArgoCD ingress
    ├── traefik.tf                # Traefik ingress controller
    ├── ebs-csi.tf                # EBS CSI driver
    ├── applications-tls.tf       # Application TLS certificates
    └── vault-roles-policies.tf   # Vault policies for apps

​
Deployment Flow

The complete deployment follows this sequence:
1

Bootstrap

Create S3 bucket and DynamoDB table for Terraform state management
2

Infrastructure Layer

Deploy VPC, EKS cluster, Tailscale VPN, and Vault infrastructure
3

Platform Layer

Install Kubernetes platform components and initialize Vault
4

Apps Layer

Deploy ArgoCD, Traefik, and application configurations

​
Next Steps

Prerequisites

Set up required tools and accounts

Bootstrap

Initialize Terraform state backend

Build docs developers (and LLMs) love

Get started for freeTalk to us