Boot on GCP

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

Prerequisites

• Install the CLI and log in
• Build and push an image
• A GCP project with Compute Engine enabled
• gcloud CLI authenticated to your project

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 HTTP traffic to instances tagged http. This will be needed for the verification step later.

gcloud compute firewall-rules create allow-http \
  --allow tcp:80 \
  --target-tags http

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 e2-small \
  --tags=http

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

Create a config file with values for the image's template. If you used the example Caddy image from the build-and-push guide, it expects a Name field:

echo '{"Name":"world"}' > config.json

Step 5 — Create a release

Create a release that pairs the image with your config:

kheeper releases create ${ORG}/${HOST}:v1 \
  --image 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, pull and reboot. Verify by hitting the instance's external IP:

IP=$(gcloud compute instances describe ${HOST} \
  --zone us-central1-a \
  --format 'get(networkInterfaces[0].accessConfigs[0].natIP)')

curl http://${IP}/

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}