Kheeper

Boot on GCP

This guide walks through booting your first Kheeper-managed host on Google Cloud Platform.

Prerequisites

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

ORG=$(kheeper orgs list | grep 'user-[0-9a-f]' | awk '{ print $1 }')
PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get project) --format='value(projectNumber)')
HOST=getting-started-gcp

Alternatively you can find your project number (not project ID) in the [GCP Console] (https://console.cloud.google.com/welcome).

Step 1 — Connect your GCP project

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

kheeper clouds create my-gcp --org ${ORG} --project-number ${PROJECT_NUMBER}

Step 2 — Create a GCE instance

First, create a firewall rule to allow HTTPS traffic to instances tagged https.

gcloud compute firewall-rules create allow-https \
  --allow tcp:80,tcp:443 \
  --target-tags allow-https

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

gcloud compute instances create ${HOST} \
  --project $(gcloud config get project) \
  --zone us-central1-a \
  --image-family fedora-bootc \
  --image-project kheeper \
  --machine-type c4-standard-2 \
  --boot-disk-size 40GB \
  --tags=allow-https

Step 3 — Verify

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

kheeper hosts list --org ${ORG}

You should see a host whose instance name matches the VM you created.

Step 4 — 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

Set domain to ${HOST}.${ORG}.us.kheeper.app — every Kheeper host gets a <host>.<org>.us.kheeper.app DNS record (region-scoped) that points at its public IP, so Caddy can request a TLS cert for it automatically.

Step 5 — 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 6 — Activate the release

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

The host will pick up the release within a minute, then pull and reboot.

Step 7 — Verify

Once the host has rebooted, curl the domain you set in the config:

curl https://${HOST}.${ORG}.us.kheeper.app/

Troubleshooting

gcloud compute instances tail-serial-port-output ${HOST}

Clean up

Delete the GCE instance and Kheeper host when you're done:

gcloud compute instances delete ${HOST} --zone us-central1-a --quiet
kheeper hosts delete ${ORG}/${HOST}
Next: Boot on Bare Metal