Skip to main content
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.
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.

​
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 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

1

Create a Read-Only Service Account

Follow the same steps described in the Console GCS setup guide, 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.
2

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).

​
Configuration

Console UI documentation is coming soon. This section will walk you through configuring this component using the Maverics Console’s visual interface, including step-by-step screenshots and field descriptions.

​
Configuration Reference

The MAVERICS_GCP_CONFIG JSON payload supports the following fields:
FieldTypeRequiredDescription
bucketNamestringYesGCS bucket name
configurationFilePathstringYesPath to the config file within the bucket
keyobjectConditionalGCP 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:
maverics.env
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.

Config Sources

Overview of all configuration sources

Amazon S3

Load config from AWS S3

Configuration Reference

Complete configuration field reference

GCS Deployment Provider

Console-side GCS setup and service account key generation