actuated-events

Boot up / start-up VMs or hosts that run as actuated agents.

In order to reduce the ongoing costs of cloud VMs, the actuated agent can be set to shutdown a host after a period of inactivity.

This service allows you to start those VMs on demand via a webhook sent from the actuated control-plane.

TLS verification is not strictly necessary, since the webhook is harmless and in the worst case, the VMs could be started unintentionally.

Configuration

Set the following environment variables:

• ZONE: GCP zone where VMs are located (required)
• PROJECT: GCP project ID (required)
• VM_NAMES: Comma-separated list of VM names to manage (required)
• PORT: HTTP server port (default: 8080)

Optional:

• GOOGLE_APPLICATION_CREDENTIALS_JSON: JSON credentials for authentication when running outside GCP or without workload identity.

Usage

Service account permissions

When running on a GCP VM, the service automatically uses the VM's attached service account for authentication. Ensure the VM's service account has the following IAM permissions:

• compute.instances.get
• compute.instances.start
• compute.zoneOperations.get

Running on a GCP VM (quick start):

# Set required environment variables
export ZONE="us-central1-a"
export PROJECT="my-project"
export VM_NAMES="vm1,vm2,vm3"

# Install Go
curl -sLS https://get.arkade.dev | sudo sh
arkade system install go

export PATH=$PATH:$(go env GOPATH)/bin

# Clone the repository
git clone https://github.com/self-actuated/actuated-events.git --depth=1
cd actuated-events

# Build and run the binary
go build

# Allow binding to port 80

sudo setcap cap_net_bind_service=+ep ./actuated-events

# Run in tmux or install via systemd service

./actuated-events

Running in GCP Kubernetes with workload identity:

git clone https://github.com/self-actuated/actuated-events.git --depth=1
cd actuated-events

Create/update values-custom.yaml:

gcp:
+  zone: "us-east1-a"
+  project: "test-project"
+  vmNames: "test-vm1,test-vm2"

# Set the GCP service account annotation
serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: "[email protected]"

Set up Ingress:

ingress:
+  enabled: true
+  className: "nginx"
+  hosts:
+    - host: "actuated.example.com"
+      paths:
+        - path: /
+          pathType: Prefix

Install the chart:

helm upgrade --install actuated-events ./helm/actuated-events \
  -f values-custom.yaml

Running outside of GCP with static credentials:

As per the instructions for running on a GCP VM, however set the value of GOOGLE_APPLICATION_CREDENTIALS_JSON to the JSON credentials of a service account with the required permissions.

API Endpoints

POST /webhook

Triggers VM start operations for all configured VMs.

Request body:

{
  "event": "job_queued"
}

Response:

{
  "status": "success",
  "message": "Processed 3 VMs"
}

GET /health

Health check endpoint.

Response:

{
  "status": "healthy"
}

Docker Build

docker build -t actuated-events .