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

# Google Cloud Storage

The Google Cloud Storage (GCS) config source loads Orchestrator configuration from an object stored in a GCS bucket. The source is configured entirely through the `MAVERICS_GCP_CONFIG` environment variable.

<Note>
  **Console terminology:** In the Maverics Console, Orchestrator instances and
  configuration delivery are managed through **Deployments**. When working directly
  with YAML, configuration is managed as files delivered via the `-config` flag or
  `MAVERICS_CONFIG` environment variable.
</Note>

## Prerequisites

* **A Google Cloud account** -- with a Cloud Storage bucket containing Orchestrator configuration
* **A service account key JSON** -- with `storage.objects.get` permission (see the [GCS deployment provider](/reference/console/config-publishing/gcs) page for detailed setup steps), or workload identity configured for GCP-hosted deployments

## Overview

When the `MAVERICS_GCP_CONFIG` environment variable is set, the Orchestrator fetches its YAML configuration from the specified GCS bucket and object path. The variable contains a JSON payload with connection details and optional service account credentials. The Orchestrator supports ETag-based change detection for automatic hot-reload.

## Use Cases

* **GCP-native deployments** -- store configuration in GCS alongside other GCP resources with native IAM authentication
* **GCP CI/CD** -- publish validated configuration to GCS as part of Cloud Build or other GCP CI/CD pipelines
* **Multi-cloud with GCS as config store** -- use GCS as a centralized config store accessible from any cloud environment

## Service Account Setup

<Steps>
  <Step title="Create a Read-Only Service Account">
    Follow the same steps described in the [Console GCS setup guide](/reference/console/config-publishing/gcs#create-a-service-account-and-key), but assign the **Storage Object Viewer** role instead of Storage Object Admin. The Orchestrator only needs to read configuration, not write it.

    Alternatively, if running on GCE or GKE, configure workload identity to avoid managing service account keys entirely.
  </Step>

  <Step title="Use the Key in Configuration">
    Copy the entire JSON body of the downloaded key file and use it as the `key` value in the `MAVERICS_GCP_CONFIG` environment variable (see Configuration below).
  </Step>
</Steps>

## Configuration

The GCS config source is configured via the `MAVERICS_GCP_CONFIG` environment variable with a JSON payload:

```bash theme={null}
export MAVERICS_GCP_CONFIG='{
  "bucketName": "my-config-bucket",
  "configurationFilePath": "path/to/config",
  "key": { ... }
}'
maverics
```

<Note>
  When running on GCE or GKE with workload identity, omit the `key` field. The Orchestrator uses the default GCP credential chain (Application Default Credentials).
</Note>

**Workload identity example (recommended for GCP-hosted deployments):**

```bash theme={null}
export MAVERICS_GCP_CONFIG='{
  "bucketName": "my-config-bucket",
  "configurationFilePath": "path/to/config"
}'
maverics
```

## Configuration Reference

The `MAVERICS_GCP_CONFIG` JSON payload supports the following fields:

| Field                   | Type   | Required    | Description                                                                                                                                                                                |
| ----------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bucketName`            | string | Yes         | GCS bucket name                                                                                                                                                                            |
| `configurationFilePath` | string | No          | Directory path prefix within the bucket where the config bundle is stored. The Orchestrator appends `maverics.tar.gz` to this path. If omitted, the bundle is expected at the bucket root. |
| `key`                   | object | Conditional | GCP service account key JSON (not needed with workload identity)                                                                                                                           |

**ETag-based hot-reload:** When `MAVERICS_RELOAD_CONFIG=true` is set, the Orchestrator periodically checks the object's ETag. When the ETag changes (indicating the file was updated), the Orchestrator reloads the configuration automatically.

## Full Environment Example

A complete `maverics.env` file for an Orchestrator using Google Cloud Storage as its config source:

```bash maverics.env theme={null}
MAVERICS_DEBUG_MODE=true
MAVERICS_HTTP_ADDRESS=:443
MAVERICS_TLS_SERVER_CERT_FILE=your-cert.pem
MAVERICS_TLS_SERVER_KEY_FILE=your-private_key.pem
MAVERICS_RELOAD_CONFIG=true
MAVERICS_POLLING_INTERVAL_SECONDS=30
MAVERICS_BUNDLE_PUBLIC_KEY_FILE=./public_key.pem
MAVERICS_GCP_CONFIG='{"bucketName":"<BUCKET_NAME>", "configurationFilePath":"<CONFIG_FILE_PATH>", "key": <SERVICE_ACCOUNT_KEY_JSON>}'
```

Replace the placeholder values with your actual certificate paths, bucket name, config file path, and service account key JSON.

## Troubleshooting

* **Permission denied** -- verify the service account (or workload identity) has `storage.objects.get` permission on the bucket. Check IAM bindings in the GCP Console.
* **Bucket not found** -- confirm the `bucketName` is correct. GCS bucket names are globally unique and case-sensitive.
* **Service account key issues** -- if using a `key` object, ensure it is a valid GCP service account key JSON. The key must have the `storage.objects.get` permission.
* **Config not reloading** -- ensure `MAVERICS_RELOAD_CONFIG=true` is set. Check Orchestrator logs for ETag change detection messages.

## Related Pages

<CardGroup cols={2}>
  <Card title="Config Sources" icon="folder-gear" href="/reference/orchestrator/configuration/config-sources">
    Overview of all configuration sources
  </Card>

  <Card title="Amazon S3" icon="aws" href="/reference/orchestrator/configuration/config-sources/s3">
    Load config from AWS S3
  </Card>

  <Card title="Configuration Reference" icon="code" href="/reference/orchestrator/configuration">
    Complete configuration field reference
  </Card>

  <Card title="GCS Deployment Provider" icon="google" href="/reference/console/config-publishing/gcs">
    Console-side GCS setup and service account key generation
  </Card>
</CardGroup>