AWS EC2

Orchard's EC2 provider launches one EC2 instance per grove using cloud-init for bootstrap, then connects over SSH once the instance is ready.

The provider is activated by setting orchard.nursery.aws.region in application.yml.

Prerequisites

AMI — a vanilla Ubuntu LTS AMI in your target region (cloud-init handles the rest)
EC2 key pair — used for SSH access; the key pair name and private key path must both be configured
Security group — must allow inbound SSH (port 22) from the host running the Orchard server
Subnet — the VPC subnet to launch instances into
IAM credentials — the Orchard server process must have IAM credentials with ec2:RunInstances, ec2:DescribeInstances, ec2:StartInstances, ec2:TerminateInstances, ec2:DescribeRegions, and ec2:CreateTags permissions (the last is required because Orchard tags every instance it launches — see Failure Behavior)

Configuration

code

orchard:
  nursery:
    provider: aws
    aws:
      region: us-east-1
      ami-id: ami-0c55b159cbfafe1f0        # Ubuntu 22.04 LTS (update per region)
      key-pair-name: orchard-key
      security-group-id: sg-0123456789abcdef0
      subnet-id: sub-0123456789abcdef0
      ssh-key-path: /etc/orchard/ssh/id_ed25519
      ip-mode: AUTO                         # AUTO | PUBLIC | PRIVATE
      instance-type-mapping:
        2: t3.small
        4: t3.medium
        8: t3.xlarge

Key	Required	Default	Description
`region`	Yes	`us-east-1`	AWS region
`ami-id`	Yes	—	Base AMI (Ubuntu LTS recommended)
`key-pair-name`	Yes	—	EC2 key pair name for SSH access
`security-group-id`	Yes	—	Security group allowing inbound SSH
`subnet-id`	Yes	—	VPC subnet for instance placement
`ssh-key-path`	Yes	—	Path to the Orchard SSH private key; the matching `.pub` file must also exist
`ip-mode`	No	`AUTO`	`AUTO` prefers public IP, falls back to private; `PUBLIC` requires a public IP; `PRIVATE` always uses private IP (Orchard must be inside the VPC)
`instance-type-mapping`	No	`2→t3.small`, `4→t3.medium`, `8→t3.xlarge`	Maps grove CPU core count to EC2 instance type

SSH Key Setup

Orchard injects an SSH public key into each instance via cloud-init. The key pair must be registered in EC2, and the private key file must be readable by the Orchard server process:

code

ssh-keygen -t ed25519 -f /etc/orchard/ssh/id_ed25519 -N ""
# Register the public key in EC2 as 'orchard-key':
aws ec2 import-key-pair \
  --key-name orchard-key \
  --public-key-material fileb:///etc/orchard/ssh/id_ed25519.pub

IP Mode

Mode	Behavior
`AUTO`	Prefer public IP; fall back to private IP if no public IP exists
`PUBLIC`	Require a public IP; fail provisioning if none exists
`PRIVATE`	Always use private IP — Orchard server must run inside the VPC

Failure Behavior

If provisioning fails, the grove moves to BLIGHTED state and the EC2 instance is not automatically terminated. Clean up leaked instances via the AWS console or CLI using the orchard:grove-id tag that Orchard applies to every instance.

Cloud Providers

Docker Compose