Kheeper

Working with GCP

Kheeper integrates with Google Cloud Platform so that GCE instances automatically register as hosts when they boot.

Overview

The GCP integration works through cloud connections. You link your GCP project to your Kheeper org, then any GCE instance launched from the Kheeper base image in that project automatically registers as a host in your org.

Connecting your GCP project

Link a GCP project to your org using its project number:

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get project) --format='value(projectNumber)')

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

You can connect multiple GCP projects to the same org:

kheeper clouds create staging --org myorg --project-number 111111111111
kheeper clouds create production --org myorg --project-number 222222222222

List your cloud connections:

kheeper clouds list --org myorg

Launching instances

Launch GCE instances using the public Kheeper base image:

gcloud compute instances create my-instance \
  --image-family fedora-bootc \
  --image-project kheeper \
  --machine-type e2-small \
  --zone us-central1-a

The base image is a Fedora bootc image. On first boot, the instance contacts the Kheeper registry using its GCE instance identity to prove which project it belongs to. The registry matches the project number to your cloud connection and registers the instance as a host in your org.

Auto-registration

When a GCE instance boots:

  1. The instance presents its GCE identity token to the Kheeper registry
  2. The registry verifies the token with Google and extracts the project number
  3. The registry looks up which org is connected to that project
  4. A host is created in that org, named after the instance

The host name is derived from the GCE instance name. If a name collision occurs, a random suffix is appended.

If an instance is deleted and recreated with the same name, it re-registers and updates the existing host record.

Deploying to GCE hosts

Once an instance has registered, deploy to it like any other host:

# Create a release
kheeper releases create myorg/my-instance:v1 \
  --image kheeper.com/myorg/webapp:v1 \
  --config-file config.json

# Activate it
kheeper hosts activate myorg/my-instance:v1

See Working with Hosts and Configuring Images for details.

Multiple zones and regions

The Kheeper base image is available globally. Launch instances in any GCE zone:

gcloud compute instances create us-west \
  --image-family fedora-bootc \
  --image-project kheeper \
  --zone us-west1-b

gcloud compute instances create eu-west \
  --image-family fedora-bootc \
  --image-project kheeper \
  --zone europe-west1-b

Both instances register as hosts in the same org, as long as they're in a connected project.

Cleaning up

Delete the GCE instance and the Kheeper host:

gcloud compute instances delete my-instance --zone us-central1-a --quiet
kheeper hosts delete myorg/my-instance

Deleting the GCE instance stops the machine. Deleting the Kheeper host removes it from the registry.

Next: Working with Bare Metal