Skip to main content

How to authenticate StackQL to Google Cloud

StackQL authenticates to Google Cloud with a service account key, supplied as JSON content in the GOOGLE_CREDENTIALS environment variable.

Steps​

  1. Create a service account and grant it a role on the target project (roles/viewer suffices for read-only querying), then create and download a JSON key:
gcloud iam service-accounts keys create stackql-key.json \
  --iam-account=stackql-sa@my-project.iam.gserviceaccount.com
  1. Export the key content:
export GOOGLE_CREDENTIALS=$(cat ./stackql-key.json)

An alternative is passing the key by path with the --auth flag, which is useful for server and MCP deployments:

stackql shell \
  --auth='{"google": {"type": "service_account", "credentialsfilepath": "/path/to/stackql-key.json"}}'
  1. Pull the Google provider (first use only):
REGISTRY PULL google;
  1. Verify with a query:
SELECT name, status, machineType
FROM google.compute.instances
WHERE project = 'my-project';

This uses the aggregated_list access method, which requires only project and returns instances across all zones. The zonal list method requires both project and zone; SHOW METHODS IN google.compute.instances shows each method's required parameters.

Where the credentials apply​

The same variable (or --auth object) works across stackql shell, stackql exec, stackql srv, and stackql mcp. For Claude Desktop and similar MCP clients, set GOOGLE_CREDENTIALS in the env block of the server configuration. In CI, source the key from the platform's secret store - never commit it.