Kheeper

Boot on AWS

This guide walks through booting your first Kheeper-managed host on Amazon Web Services.

Prerequisites

Set the variables in your shell needed for the remaining steps.

ORG=$(kheeper orgs list | grep 'user-[0-9a-f]' | awk '{ print $1 }')
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
HOST=getting-started-aws
REGION=us-east-2

Step 1 — Create an IAM role for EC2

The instance needs an IAM role so it can call STS GetCallerIdentity during auto-registration. Create a minimal role:

aws iam create-role \
  --role-name kheeper-autoregister \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ec2.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

aws iam create-instance-profile \
  --instance-profile-name kheeper-autoregister

aws iam add-role-to-instance-profile \
  --instance-profile-name kheeper-autoregister \
  --role-name kheeper-autoregister

No additional permissions are needed — GetCallerIdentity requires no IAM permissions.

Step 2 — Connect your AWS account

Link your AWS account to your Kheeper org so that instances in that account can auto-register as hosts.

kheeper clouds create my-aws --org ${ORG} --provider aws --account-id ${ACCOUNT_ID}

Region selection

Kheeper accounts are region-scoped. andy@example.com on us.kheeper.com is a separate account from the same email on eu.kheeper.com. When a new instance boots, the autoregister image needs to know which region owns your AWS account. The recommended way is to set kheeper-region in instance user-data when you launch.

Recommended: user-data.

aws ec2 run-instances --image-id ami-xxx \
  --user-data 'kheeper-region=us.kheeper.com'

Alternative: instance tag (requires enabling tags-in-metadata):

aws ec2 run-instances --image-id ami-xxx \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=kheeper-region,Value=us.kheeper.com}]' \
  --metadata-options 'InstanceMetadataTags=enabled'

If you skip this, the image will poll every kheeper region and pick the one that owns your AWS account; it works, but it logs a rejection in the regions that don't.

Step 3 — Create an EC2 instance

First, create a security group to allow HTTP traffic.

VPC_ID=$(aws ec2 describe-vpcs --filters "Name=isDefault,Values=true" \
  --query 'Vpcs[0].VpcId' --output text --region ${REGION})

SG_ID=$(aws ec2 create-security-group \
  --group-name kheeper-http \
  --description "Allow HTTP" \
  --vpc-id ${VPC_ID} \
  --region ${REGION} \
  --query 'GroupId' --output text)

aws ec2 authorize-security-group-ingress \
  --group-id ${SG_ID} \
  --protocol tcp --port 80 --cidr 0.0.0.0/0 \
  --region ${REGION}

Then launch an instance using the public Kheeper AMI. This is a Fedora bootc image that automatically connects to the Kheeper registry on first boot.

AMI_ID=$(aws ec2 describe-images \
  --owners 223249276674 \
  --filters "Name=name,Values=kheeper-aws-*" "Name=state,Values=available" \
  --query 'sort_by(Images, &CreationDate)[-1].ImageId' \
  --output text --region ${REGION})

INSTANCE_ID=$(aws ec2 run-instances \
  --image-id ${AMI_ID} \
  --instance-type t3.small \
  --iam-instance-profile Name=kheeper-autoregister \
  --security-group-ids ${SG_ID} \
  --user-data 'kheeper-region=us.kheeper.com' \
  --region ${REGION} \
  --query 'Instances[0].InstanceId' --output text)

echo "Launched ${INSTANCE_ID}"

Step 4 — Verify

The instance will boot and auto-register within a few minutes. Check that the host appeared:

kheeper hosts list --org ${ORG}

You should see a host whose instance name matches the instance ID you launched.

Step 5 — Author the config

Generate a starter config from the image's schema and edit it to fit your host. If you used the example Caddy image from the build-and-push guide, it expects domain and name fields:

kheeper releases start config.json --image us.kheeper.com/${ORG}/getting-started:v1

Step 6 — Create a release

Create a release that pairs the image with your config:

kheeper releases create ${ORG}/${HOST}:v1 \
  --image us.kheeper.com/${ORG}/getting-started:v1 \
  --config-file config.json

Step 7 — Activate the release

kheeper hosts activate ${ORG}/${HOST}:v1

The host will pick up the release within a minute, pull and reboot. Verify by hitting the instance's public IP:

IP=$(aws ec2 describe-instances \
  --instance-ids ${INSTANCE_ID} \
  --region ${REGION} \
  --query 'Reservations[0].Instances[0].PublicIpAddress' --output text)

curl http://${IP}/

Troubleshooting

aws ec2 get-console-output --instance-id ${INSTANCE_ID} --region ${REGION} --output text

Clean up

Terminate the EC2 instance and delete the Kheeper host when you're done:

aws ec2 terminate-instances --instance-ids ${INSTANCE_ID} --region ${REGION}
kheeper hosts delete ${ORG}/${HOST}
Next: Backups