---
title: "Google Cloud Storage (GCS) Bucket"
description: "Configure GCS for deployment"
source: "Guardian Platform"
---
## Overview

The Guardian Platform requires Google Cloud Storage (GCS) for blob storage.

**Required buckets:**

- **Governance artifacts bucket** – Stores governance-related documents and artifacts
- **Integrity store bucket** – Stores cryptographic proofs and audit trails

**This guide covers:**

- Creating GCS buckets with proper configuration (gcloud CLI or Console)
- Setting up a service account with storage permissions
- Configuring the Helm chart for GCS storage

## Prerequisites

- Google Cloud Platform (GCP) account with an active project
- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and configured (for CLI method)
- Permissions to create buckets and service accounts in the GCP project

## Helm Configuration

Add the following to the `values.yaml` and `secrets.yaml` files. Placeholders will be filled in throughout the steps below.

`values.yaml`:

```yaml
governance-service:
  config:
    storageProvider: gcs
    gcsBucketName: "<governance-bucket-name>" # Filled in after step 2

integrity-service:
  config:
    integrityAppBlobStoreType: gcs
    integrityAppBlobStoreGcsBucket: "<integrity-bucket-name>" # Filled in after step 2
    integrityAppBlobStoreGcsFolder: "rootstore"
```

`secrets.yaml`:

```yaml
global:
  secrets:
    create: true
    storage:
      gcs:
        secretName: platform-gcs
        values:
          serviceAccountJson: | # Filled in after step 5
            <service-account-json>
```

## Quick Start (CLI Method - Recommended)

Create the buckets and a service account that can reach them with the gcloud CLI, in five steps.

### 1. Authenticate and Configure Project

Login to Google Cloud:

```bash
gcloud auth login
```

Set the following variables — they will be used throughout this guide. Replace the values with the ones for the deployment:

```bash
PROJECT_ID="your-gcp-project-id"
GOVERNANCE_BUCKET="governance-artifacts-bucket"  # Must be globally unique
INTEGRITY_BUCKET="integrity-store-bucket"        # Must be globally unique
SERVICE_ACCOUNT_NAME="guardian-platform"
REGION="us-east1"
```

Set the active project:

```bash
gcloud config set project $PROJECT_ID
```

Update `values.yaml` with the chosen bucket names.

`values.yaml` -> governance-service.config:

```yaml
gcsBucketName: "<governance-bucket-name>"
```

`values.yaml` -> integrity-service.config:

```yaml
integrityAppBlobStoreGcsBucket: "<integrity-bucket-name>"
```

### 2. Create GCS Buckets

Create the governance artifacts bucket:

```bash
gcloud storage buckets create gs://$GOVERNANCE_BUCKET \
  --location=$REGION \
  --uniform-bucket-level-access \
  --public-access-prevention
```

Create the integrity store bucket:

```bash
gcloud storage buckets create gs://$INTEGRITY_BUCKET \
  --location=$REGION \
  --uniform-bucket-level-access \
  --public-access-prevention
```

Optionally enable versioning for data protection:

```bash
gcloud storage buckets update gs://$GOVERNANCE_BUCKET --versioning
```

```bash
gcloud storage buckets update gs://$INTEGRITY_BUCKET --versioning
```

Verify both buckets were created:

```bash
gcloud storage buckets list --filter="name:$GOVERNANCE_BUCKET OR name:$INTEGRITY_BUCKET"
```

### 3. Create Service Account

```bash
gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Guardian Platform Service Account" \
  --description="Service account for Guardian Platform to access GCS buckets"
```

Set the service account email as a variable for use in subsequent commands:

```bash
SERVICE_ACCOUNT_EMAIL="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
```

### 4. Grant Bucket Permissions

Grant Storage Object Admin on the governance bucket:

```bash
gcloud storage buckets add-iam-policy-binding gs://$GOVERNANCE_BUCKET \
  --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
  --role="roles/storage.objectAdmin"
```

Grant Storage Object Admin on the integrity bucket:

```bash
gcloud storage buckets add-iam-policy-binding gs://$INTEGRITY_BUCKET \
  --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
  --role="roles/storage.objectAdmin"
```

Verify permissions were applied:

```bash
gcloud storage buckets get-iam-policy gs://$GOVERNANCE_BUCKET \
  --flatten="bindings[].members" \
  --filter="bindings[].members:$SERVICE_ACCOUNT_EMAIL"
```

### 5. Create Service Account Key

Download the service account key as a JSON file:

```bash
gcloud iam service-accounts keys create gcs-key.json \
  --iam-account=$SERVICE_ACCOUNT_EMAIL
```

Paste the contents of `gcs-key.json` into `secrets.yaml` as-is, indented under a block scalar. The services read the value as a JSON key file, so don't base64-encode it.

`secrets.yaml` -> global.secrets.storage.gcs.values:

```yaml
serviceAccountJson: |
  <contents of gcs-key.json>
```

Keep `gcs-key.json` until you finish [Verification](#verification).

## Alternative: Web UI Setup

<details>
<summary>Click to expand Google Cloud Console instructions</summary>

### Using the Google Cloud Console

#### 1. Create GCS Buckets

- Navigate to Cloud Storage Browser
- Click "Create Bucket"
- Enter a globally unique name for governance artifacts bucket
- Choose a location (region or multi-region)
- Select "Uniform" access control
- Enable "Public access prevention"
- Click "Create"
- Repeat for integrity store bucket

Update `values.yaml` with the bucket names.

`values.yaml` -> governance-service.config:

```yaml
gcsBucketName: "<governance-bucket-name>"
```

`values.yaml` -> integrity-service.config:

```yaml
integrityAppBlobStoreGcsBucket: "<integrity-bucket-name>"
```

#### 2. Create Service Account

- Navigate to IAM & Admin > Service Accounts
- Click "Create Service Account"
- Enter name: "guardian-platform"
- Enter description: "Service account for Guardian Platform"
- Click "Create and Continue"
- Skip role assignment at this step (bucket-specific permissions are added next)
- Click "Done"

#### 3. Grant Bucket Permissions

- Navigate to Cloud Storage Browser
- For each bucket (governance artifacts and integrity store):
  - Click on the bucket name
  - Navigate to "Permissions" tab
  - Click "Grant Access"
  - Enter the service account email (e.g. `guardian-platform@PROJECT_ID.iam.gserviceaccount.com`)
  - Select role: "Storage Object Admin"
  - Click "Save"

#### 4. Create Service Account Key

- Navigate to IAM & Admin > Service Accounts
- Click on the service account name
- Navigate to "Keys" tab
- Click "Add Key" > "Create new key"
- Select "JSON" format
- Click "Create" (the key will download automatically)
- Paste the contents of the downloaded JSON file into `secrets.yaml` as-is, indented under a block scalar

`secrets.yaml` -> global.secrets.storage.gcs.values:

```yaml
serviceAccountJson: |
  <contents of the downloaded key file>
```

</details>

## Verification

Activate the service account credentials locally. For the Console method, use the path to the downloaded key file:

```bash
gcloud auth activate-service-account \
  --key-file=gcs-key.json
```

List objects in the governance artifacts bucket (should be empty initially):

```bash
gcloud storage ls gs://$GOVERNANCE_BUCKET
```

List objects in the integrity store bucket (should be empty initially):

```bash
gcloud storage ls gs://$INTEGRITY_BUCKET
```

Test write access on both buckets:

```bash
echo "test" > test.txt
gcloud storage cp test.txt gs://$GOVERNANCE_BUCKET/
gcloud storage rm gs://$GOVERNANCE_BUCKET/test.txt
gcloud storage cp test.txt gs://$INTEGRITY_BUCKET/
gcloud storage rm gs://$INTEGRITY_BUCKET/test.txt
rm test.txt
```

Return to normal authentication:

```bash
gcloud auth revoke $SERVICE_ACCOUNT_EMAIL
gcloud auth login
```

If the commands succeed without errors, the configuration is correct. Delete the key file now that its contents are in `secrets.yaml`:

```bash
rm gcs-key.json
```

## Security Best Practices

- **Least Privilege:** Grant only the minimum required permissions (Storage Object Admin on specific buckets, not project-wide)
- **Rotate Keys:** Regularly rotate service account keys and update Kubernetes secrets
- **Enable Versioning:** Enable object versioning to protect against accidental deletion
- **Audit Logging:** Enable Cloud Audit Logs for access monitoring
- **Encryption:** GCS encrypts data at rest by default; consider customer-managed encryption keys (CMEK) for additional control

## Official Documentation

- [gcloud storage CLI Reference](https://cloud.google.com/sdk/gcloud/reference/storage)
- [Cloud Storage Overview](https://cloud.google.com/storage/docs/introduction)
- [Service Accounts Best Practices](https://cloud.google.com/iam/docs/best-practices-service-accounts)
- [Cloud Storage Security Best Practices](https://cloud.google.com/storage/docs/best-practices)
- [Helm Chart Examples](https://github.com/eqtylab/deployment/tree/main/charts/guardian-platform/examples)

## Related

- [Object Storage](./object-storage.mdx) — how GCS compares with the other storage providers
- [Backup and Restore](./backup-and-restore.mdx#object-storage) — object versioning and a second copy for both buckets
- [External Database](./external-database.mdx#other-managed-postgresql-providers) — connection notes for Cloud SQL for PostgreSQL
- [Deployment Troubleshooting](./troubleshooting.mdx#attachments-fail) — first checks when attachments fail
- [Chart Values](./chart-values.mdx) — the full values and secrets files these settings go into