The information contained in this article has been verified as up-to-date on the date of the original publication of the article.  HashiCorp endeavors to keep this information up-to-date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.

All information contained in this article is for general information purposes only.  Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.

Introduction

This guide provides the full, required procedure to configure HashiCorp Vault Enterprise to automatically upload Raft storage snapshots to a Google Cloud Storage (GCS) bucket. This method uses a dedicated GCP Service Account for authentication, ensuring robust, automated disaster recovery backups.

Expected Outcome

Automated Raft snapshots of the Vault cluster data will be generated and uploaded to the configured GCS bucket at the specified interval (e.g., every 5 minutes), providing a hands-off disaster recovery solution.

Prerequisites

The success of this configuration is dependent on meeting these critical prerequisites:

Identify Your Project ID

Before beginning, use the gcloud CLI to confirm the Project ID.

gcloud config list project
# OR
gcloud projects list

Use Case

A robust, automated disaster recovery solution is required to protect the critical secrets stored in Vault. By leveraging the Auto-Snapshot feature with Google Cloud Storage, the organization can guarantee consistent, offsite backups of the Vault cluster state, minimizing Recovery Point Objective (RPO).

Procedure

The configuration is broken down into three logical phases: Google Cloud Setup, Key Management, and Final Vault Configuration.

Phase 1: Google Cloud Setup

This phase provisions the necessary GCP infrastructure components: the GCS bucket and the Service Account writer role. Additional components may be needed based on your use case.

Step 1: Create the GCS Bucket

Create the destination bucket. We recommend using a unique, timestamped name for the bucket.

# Define variables for use throughout this guide
export GCP_PROJECT_ID="hc-4253855b8fe24f3f81f23e7fd53"
export BUCKET_NAME="vault-backup-$(date +%s)"

gcloud storage buckets create gs://$BUCKET_NAME \
  --project=$GCP_PROJECT_ID \
  --location=US \
  --uniform-bucket-level-access

# Example Output: gs://vault-backup-1760982089

Step 2: Create a Service Account for Vault Backups

Create a dedicated Service Account for least-privilege access.

export SERVICE_ACCOUNT_NAME="vault-backup-writer"

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Vault GCS Backup Writer" \
  --project=$GCP_PROJECT_ID

Step 3: Assign GCS Permissions

Grant the Service Account the ability to write snapshots to the bucket by assigning the storage.objectAdmin role.

gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$GCP_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

# Optional: Add read/list permissions for verification purposes
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$GCP_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.legacyBucketReader"

# Verification
gcloud storage buckets get-iam-policy gs://$BUCKET_NAME \
  --format="flattened(bindings[].members)" | grep vault-backup-writer

Phase 2: Key Management and Transfer

Vault authenticates to GCS using a Service Account JSON key file. This key is highly sensitive and must be handled with extreme care.

Step 4: Create and Securely Download the Service Account Key File

Generate the JSON key file on your local machine or in Cloud Shell.

gcloud iam service-accounts keys create ~/gcp-backup-key.json \
  --iam-account=$SERVICE_ACCOUNT_NAME@$GCP_PROJECT_ID.iam.gserviceaccount.com

# Key file saved to: ~/gcp-backup-key.json

Downloading the Key File from Cloud Shell (UI Method)

If you are executing Step 4 from Google Cloud Shell, use the following UI steps to transfer the key file to your local machine:

1. In your Cloud Shell window, click the three dots (⋮) in the upper-right corner.
2. Click “Download file”.
3. When prompted for a path, paste the full path of the key file (e.g., /home/jason_lopez/gcp-backup-key.json) and click Download.

CRITICAL SECURITY WARNING: This JSON key file grants write access to your Vault backup storage. It must be treated as a sensitive secret. Ensure it is deleted from your local workstation after being copied into the Vault pod.

Step 5: Copy Key File into Vault Pod (Kubernetes)

Run this command from your local machine or Cloud Shell terminal (outside the Vault pod). If Vault is running in Kubernetes, use kubectl cp to transfer the JSON key file into a non-persistent, temporary location (like /tmp) inside the Vault server pod.

IMPORTANT: You must be in the exact file path location where the gcp-backup-key.json file is saved for this command to work (e.g., your local Downloads folder).

# Example command using vault namespace and vault-0 pod
kubectl cp gcp-backup-key.json -n vault vault-0:/tmp/gcp-backup-key.json

Verification: Confirm the file exists inside the Vault container.

Phase 3: Vault Configuration and Verification

This phase configures the Auto-Snapshot feature and confirms the successful upload to GCS.

Step 6: Configure Vault Auto Snapshot

Use the sys/storage/raft/snapshot-auto/config/<name> endpoint to define the backup schedule and target. Run these commands inside the Vault pod shell.

# Enter the Vault shell
kubectl exec -it vault-1-0 -n vault-1 -- sh

# Run the configuration command
vault write sys/storage/raft/snapshot-auto/config/five-minute \
  interval="5m" \
  retain=7 \
  path_prefix="snapshots/" \
  storage_type="google-gcs" \
  google_gcs_bucket="vault-backup-1760982089" \
  google_service_account_key="@/tmp/gcp-backup-key.json"

Step 7: Verify Snapshot Configuration

Confirm the settings were applied successfully.

vault read sys/storage/raft/snapshot-auto/config/five-minute

Step 8: Verify Snapshot Upload

Wait for the interval period (5 minutes) and then verify the file appears in the GCS bucket using the Google Cloud Console.

1. Navigate to the Google Cloud Console and select the appropriate Project.
2. In the navigation menu, select Cloud Storage -> Buckets.
3. Click on the name of your bucket (vault-backup-1760982089).
4. Navigate into the snapshots/ folder.
5. Confirm that snapshot files (.snap extension) are appearing with recent timestamps.

Additional Information

Summary and Troubleshooting

Troubleshooting: Snapshot Status

The sys/storage/raft/snapshot-auto/status/five-minute endpoint shows detailed metadata about the last successful run and any errors. This information is key for troubleshooting.

vault read sys/storage/raft/snapshot-auto/status/five-minute

Example Successful Output:

Key                    Value
---                    -----
consecutive_errors     0
last_snapshot_end      2025-10-24T18:28:40Z
last_snapshot_error    n/a
last_snapshot_start    2025-10-24T18:28:39Z
last_snapshot_url      [https://storage.googleapis.com/vault-backup-1761329428/snapshots/vault-snapshot-1761330520142330379.snap](https://storage.googleapis.com/vault-backup-1761329428/snapshots/vault-snapshot-1761330520142330379.snap)
next_snapshot_start    2025-10-24T18:33:40Z
snapshot_start         2025-10-24T18:28:40Z
snapshot_url           [https://storage.googleapis.com/vault-backup-1761329428/snapshots/vault-snapshot-1761330520142330379.snap](https://storage.googleapis.com/vault-backup-1761329428/snapshots/vault-snapshot-1761330520142330379.snap)

If consecutive_errors is not zero or last_snapshot_error is not n/a, it indicates an issue with file permissions or the Service Account Key file path.

Successful Snapshot Status:

Error Snapshot Status:

Resources

• How to configure automated snapshots for Vault with Integrated Storage in GCP
• Automated snapshots with Raft Integrated Storage on GCP