> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run on Google Cloud

> Connect Monk to your Google Cloud account

Monk needs a service account JSON key to provision and manage infrastructure in your Google Cloud project. This page walks you through creating one with the right permissions.

## What You Need

* Service account JSON key file
* Optional: project ID (auto-extracted from the key)
* Optional: default region (e.g., `us-central1`)

## Create Credentials

<Steps>
  <Step title="Open the Service Accounts page">
    Log into [GCP Console → IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts).
  </Step>

  <Step title="Create a service account">
    Click **Create Service Account**. Name it something like `monk-deployment`.
  </Step>

  <Step title="Grant roles">
    For a quick start, grant **Compute Admin** and **Service Account User**. For production, create a custom role with the minimum permissions listed below.
  </Step>

  <Step title="Create a JSON key">
    Click the service account name → **Keys** tab → **Add Key** → **Create new key** → **JSON**. Download the file.
  </Step>

  <Step title="Provide to Monk">
    When you deploy to GCP, Monk asks for the key file through a secure form. Select the downloaded JSON. You can also tell your agent:

    ```
    ask Monk to update my GCP credentials
    ```
  </Step>
</Steps>

## Required Permissions

**Predefined roles (simpler, broader):**

* `roles/compute.admin` (Compute Admin)
* `roles/iam.serviceAccountUser` (Service Account User)

For production, use a custom role with only the permissions Monk needs.

**Scope summary:** Compute Engine instances, images, and instance groups. Disks, snapshots, and resource policies (backups). VPC networks, subnets, firewalls, and external IPs. Load balancing: health checks, forwarding rules, backend services, proxies, URL maps. Operations and regions metadata.

<Accordion title="Minimum permissions list">
  ```
  # Disks
  compute.disks.get
  compute.disks.create
  compute.disks.delete
  compute.disks.resize
  compute.disks.update
  compute.disks.createSnapshot
  compute.disks.addResourcePolicies
  compute.disks.removeResourcePolicies

  # Resource Policies (backups)
  compute.resourcePolicies.delete
  compute.resourcePolicies.get
  compute.resourcePolicies.create

  # Snapshots
  compute.snapshots.list
  compute.snapshots.delete
  compute.snapshots.get

  # Health Checks (global + regional)
  compute.healthChecks.create
  compute.healthChecks.delete
  compute.healthChecks.get
  compute.healthChecks.update
  compute.regionHealthChecks.create
  compute.regionHealthChecks.delete
  compute.regionHealthChecks.get
  compute.regionHealthChecks.update

  # Instance Groups
  compute.instanceGroups.create
  compute.instanceGroups.delete
  compute.instanceGroups.get
  compute.instanceGroups.update
  compute.instanceGroups.list
  compute.instanceGroups.addInstances
  compute.instanceGroups.removeInstances
  compute.instanceGroupManagers.update

  # Addresses (global + regional)
  compute.globalAddresses.create
  compute.globalAddresses.delete
  compute.globalAddresses.get
  compute.addresses.list
  compute.addresses.create
  compute.addresses.delete
  compute.addresses.get

  # Target TCP Proxies (global + regional)
  compute.targetTcpProxies.create
  compute.targetTcpProxies.delete
  compute.targetTcpProxies.get
  compute.targetTcpProxies.update
  compute.regionTargetTcpProxies.create
  compute.regionTargetTcpProxies.delete
  compute.regionTargetTcpProxies.get

  # Target HTTP Proxies (global + regional)
  compute.targetHttpProxies.create
  compute.targetHttpProxies.delete
  compute.targetHttpProxies.get
  compute.targetHttpProxies.setUrlMap
  compute.regionTargetHttpProxies.create
  compute.regionTargetHttpProxies.delete
  compute.regionTargetHttpProxies.get
  compute.regionTargetHttpProxies.setUrlMap

  # Target HTTPS Proxies (global + regional)
  compute.targetHttpsProxies.create
  compute.targetHttpsProxies.delete
  compute.targetHttpsProxies.get
  compute.targetHttpsProxies.setSslCertificates
  compute.regionTargetHttpsProxies.create
  compute.regionTargetHttpsProxies.delete
  compute.regionTargetHttpsProxies.get
  compute.regionTargetHttpsProxies.setSslCertificates

  # Backend Services (global + regional)
  compute.backendServices.create
  compute.backendServices.delete
  compute.backendServices.get
  compute.backendServices.update
  compute.backendServices.use
  compute.regionBackendServices.create
  compute.regionBackendServices.delete
  compute.regionBackendServices.get
  compute.regionBackendServices.update

  # SSL Certificates (global + regional)
  compute.sslCertificates.create
  compute.sslCertificates.delete
  compute.sslCertificates.get
  compute.regionSslCertificates.create
  compute.regionSslCertificates.delete
  compute.regionSslCertificates.get

  # URL Maps (global + regional)
  compute.urlMaps.create
  compute.urlMaps.delete
  compute.urlMaps.get
  compute.urlMaps.update
  compute.regionUrlMaps.create
  compute.regionUrlMaps.delete
  compute.regionUrlMaps.get
  compute.regionUrlMaps.update

  # Forwarding Rules (global + regional)
  compute.globalForwardingRules.create
  compute.globalForwardingRules.delete
  compute.globalForwardingRules.get
  compute.forwardingRules.create
  compute.forwardingRules.delete
  compute.forwardingRules.get

  # Zones, Regions, Machine Types, Images
  compute.zones.list
  compute.regions.get
  compute.machineTypes.get
  compute.images.getFromFamily

  # Target Instances
  compute.targetInstances.create
  compute.targetInstances.delete
  compute.targetInstances.get

  # Firewalls
  compute.firewalls.create
  compute.firewalls.delete
  compute.firewalls.get
  compute.firewalls.update

  # Operations
  compute.zoneOperations.get
  compute.regionOperations.get
  compute.globalOperations.get

  # Instances
  compute.instances.use
  compute.instances.get
  compute.instances.list
  compute.instances.create
  compute.instances.delete
  compute.instances.stop
  compute.instances.setTags
  compute.instances.deleteAccessConfig
  compute.instances.addAccessConfig
  compute.instances.detachDisk
  compute.instances.attachDisk
  compute.instances.aggregatedList

  # Networks and Subnetworks
  compute.networks.useExternalIp
  compute.subnetworks.useExternalIp
  compute.subnetworks.get
  compute.subnetworks.create

  # Routers (NAT for proxy-only subnets)
  compute.routers.get
  compute.routers.create

  # Network Endpoint Groups (regional)
  compute.regionNetworkEndpointGroups.get
  compute.regionNetworkEndpointGroups.create
  compute.regionNetworkEndpointGroups.delete
  compute.regionNetworkEndpointGroups.attachNetworkEndpoints
  ```
</Accordion>

<Accordion title="CLI setup (alternative to console)">
  ```bash theme={null}
  # Create service account
  gcloud iam service-accounts create monk-cluster \
    --display-name "Monk Cluster"

  # Create a custom role (save permissions above as monk-gcp-role.yaml)
  gcloud iam roles create MonkClusterRole \
    --project PROJECT_ID \
    --file monk-gcp-role.yaml

  # Bind role to the service account
  gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:monk-cluster@PROJECT_ID.iam.gserviceaccount.com" \
    --role "projects/PROJECT_ID/roles/MonkClusterRole"

  # Create key
  gcloud iam service-accounts keys create monk-gcp-key.json \
    --iam-account "monk-cluster@PROJECT_ID.iam.gserviceaccount.com"
  ```
</Accordion>

## How Credentials Are Stored

Credentials are encrypted at rest in your IDE's secret storage and on your Monk cluster using your cloud provider's KMS — so your infrastructure can manage itself autonomously. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for full details.

## Troubleshooting

**Service account disabled** — check the service account status in IAM & Admin.

**JSON key file malformed** — re-download the key. Make sure you selected JSON format, not P12.

**Missing roles** — if Monk reports permission errors, verify the custom role or predefined roles are bound to the service account.

Ask your agent for help:

```
ask Monk why my GCP credentials are not working
```

<Card title="Deploy your first app" icon="rocket" href="/getting-started/first-deployment" color="#3B82F6">
  Credentials ready — now deploy
</Card>