Skip to main content
emisar

Google Cloud Compute diagnostics and recovery

v0.2.6

Google Cloud Compute diagnostics plus governed recovery mutations: VM paginated project-wide instance inventory 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, where needed, zone or region explicitly and uses fixed gcloud commands or bounded HTTPS reads; mutations return their operation without waiting and are polled with gcp.operation_status.

6 allowed by default 4 need approval by default 1 denied by default
Pack ID
gcp-compute
Vendor
emisar
OS
linux
Actions
11
Required binaries. Install these on the host before relying on the pack. An action that calls a missing binary fails at run time.
gcloud curl jq

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below before copying it into the runner's packs dir. That hash covers the exact bytes this page was built from, so a tampered copy is rejected. The command reloads a running daemon itself, so you don't need to restart it manually.

on the runner host 
sudo emisar pack install gcp-compute --hash sha256:0cff4151828dcf6ea77720b475ad25f3512e2d520524cb501590d753efb80a76

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.
  • Operator endpoint overrides and CURL_CA_BUNDLE also require execution.inherit_env allowlisting.
  • 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.
  • CLI actions pass --quiet and an explicit --project; the inventory read fixes the project in its HTTPS URL. Ambient project configuration cannot select a different target.
  • The inventory read uses gcloud authentication and curl over HTTPS. It sends a quota-project header only for an explicitly configured concrete billing/quota_project; that opt-in requires serviceusage.services.use on the quota project. It returns full labels but excludes metadata values and other unrequested instance fields.

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 11 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: can disrupt service

    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: can disrupt service

    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: can disrupt service

    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.instances script low Low: read-only or trivially reversible

    List a project's Compute Engine instances

    Read one bounded project-wide page of instances across zones, including unmanaged and stopped VMs. Return name, zone, status, machine type, internal and external IP addresses, and full labels. IPv6 addresses are the first addresses of their assigned ranges, not single-address range claims. Metadata, descriptions, disks, and service accounts are omitted. Continue with next_page_cursor and the same project; pagination is not a snapshot.

    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: can disrupt service

    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