Skip to main content
emisar

Google Cloud Compute diagnostics and recovery

v0.2.5

Google Cloud Compute diagnostics plus governed recovery mutations: VM instance and managed-instance-group reads, instance start/stop/reset/delete, and MIG resize. Load-balancer diagnostics live in the gcp-load-balancing pack. Every action names the target project and zone or region explicitly and uses fixed gcloud commands; mutations return their operation without waiting and are polled with gcp.operation_status.

5 allowed by default 4 need approval by default 1 denied by default
Pack ID
gcp-compute
Vendor
emisar
OS
linux
Actions
10
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
gcloud

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install gcp-compute --hash sha256:235ee27892577692557b32fffaa94d71873b32cae08d5ebbe7602e65d256210d

Setup

Drives the gcloud CLI on the runner host. Authenticate gcloud with a workload identity, attached service account, service-account credential, or operator configuration before loading the pack.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • CLOUDSDK_CONFIG

    Optional gcloud configuration directory.

  • CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE

    Optional path to a credential file that overrides the active gcloud account.

Notes

  • Any credential/config env you set must be allowlisted in the runner's execution.inherit_env ; attached service accounts and workload identity need no credential env.
  • For a credential file, populate a dedicated CLOUDSDK_CONFIG with gcloud auth login --cred-file=... or set CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE ; ordinary gcloud commands do not authenticate from GOOGLE_APPLICATION_CREDENTIALS.
  • Grant least privilege for the actions you enable: reads need Compute Viewer-equivalent permissions plus compute.instances.getSerialPortOutput for serial diagnostics; the lifecycle and resize mutations need roles/compute.instanceAdmin.v1-equivalent permissions on the target instances and groups.
  • This is a remote-target client pack and is never host-auto-suggested merely because gcloud is installed.
  • All actions pass --quiet and an explicit --project, so ambient project configuration cannot redirect a request.

Verify it works

Runs gcp.instance_describe, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify gcp-compute

Install and configure a pack walks through the whole sequence on a host.

Actions 10 total

View on GitHub
  • gcp.instance_delete exec critical Critical — data loss or irreversible

    gcloud compute instances delete

    Permanently delete one Compute Engine instance from its zone. Cannot be undone: local SSDs are always destroyed and attached disks marked auto-delete are destroyed with it. Fails on an instance with deletion protection enabled. Waits until the deletion completes and reports the deleted instance URL on stderr.

    View source on GitHub
  • gcp.instance_describe exec low Low — read-only or trivially reversible

    gcloud compute instances describe

    Show one Compute Engine instance's diagnostic configuration and lifecycle state. Metadata values are deliberately omitted because startup scripts and custom metadata can contain credentials; only the metadata fingerprint is returned.

    View source on GitHub
  • gcp.instance_reset exec high High — service-affecting

    gcloud compute instances reset

    Reset one Compute Engine instance in its zone — a hard power cycle for a hung VM. The guest OS gets no shutdown signal, so unflushed writes are lost; the instance keeps its IPs and disks. Waits for the reset to be issued and returns the instance's lifecycle state.

    View source on GitHub
  • gcp.instance_serial_output exec medium Medium — changes state, easily reversible

    gcloud compute instances get-serial-port-output

    Get bounded serial-port output for one Compute Engine instance. Boot logs can contain application-written sensitive data, so restrict this action by policy. Use the byte offset returned by gcloud to resume a prior read.

    View source on GitHub
  • gcp.instance_start exec high High — service-affecting

    gcloud compute instances start

    Start one stopped Compute Engine instance in its zone. Returns the zonal operation immediately without waiting for the boot; poll gcp.operation_status until it reports DONE.

    View source on GitHub
  • gcp.instance_stop exec high High — service-affecting

    gcloud compute instances stop

    Stop one running Compute Engine instance in its zone. The guest OS is shut down and every workload on the instance goes offline until it is started again. Returns the zonal operation immediately without waiting for the shutdown; poll gcp.operation_status until it reports DONE.

    View source on GitHub
  • gcp.mig_health script low Low — read-only or trivially reversible

    gcloud compute instance-groups managed describe (health summary)

    Show one managed instance group's target size, stability and version state, autohealing policy, update policy, and backing instance group.

    View source on GitHub
  • gcp.mig_instances script low Low — read-only or trivially reversible

    gcloud compute instance-groups managed list-instances

    List up to 500 instances in one zonal or regional managed instance group, including lifecycle state, current action, version, and last-attempt errors.

    View source on GitHub
  • gcp.mig_resize script high High — service-affecting

    gcloud compute instance-groups managed resize

    Resize one zonal or regional managed instance group to an exact instance count. Scaling down deletes surplus instances; size 0 deletes every instance and the group serves nothing until scaled back up. Fails on a group managed by an autoscaler. Waits for the resize to be accepted and returns the group's new target size; instances converge asynchronously (watch with gcp.mig_health).

    View source on GitHub
  • gcp.operation_status script low Low — read-only or trivially reversible

    gcloud compute operations describe

    Show the status, progress, timing, target, warnings, and errors for one global, regional, or zonal Compute Engine operation.

    View source on GitHub
← Back to registry
Pack reference  Publish your own