/gke-backup-dr

name: gke-backup-dr
description: >-
  Configures Backup for GKE: the BackupRestore cluster addon, BackupPlan and
  RestorePlan resources, restore workflows, and CMEK-encrypted backups. Use
  for backup policies, disaster recovery, or GKE cluster restores. Don't use
  for database backups.
metadata:
  category: Storage

GKE Backup & Disaster Recovery

Protects stateful GKE workloads using Backup for GKE. Backup for GKE can capture both Kubernetes resource metadata (manifests, configurations, and secrets) and the underlying persistent volume (PV) data — but volume data and secrets are **only** captured when the backup plan explicitly enables them (see the flags below).

CLI Reference

# Enable the BackupRestore addon (Slow cluster-level update)
gcloud container clusters update {cluster_name} \
  --update-addons=BackupRestore=ENABLED --location={location} --quiet

# Create Backup Plan
gcloud beta container backup-restore backup-plans create {plan_name} \
  --project={project_id} --location={location} \
  --cluster=projects/{project_id}/locations/{location}/clusters/{cluster_name} \
  --all-namespaces \
  --include-volume-data --include-secrets \
  --backup-retain-days={days} --cron-schedule="{cron}" --quiet

# Trigger Manual Backup
gcloud beta container backup-restore backups create {backup_name} \
  --backup-plan={plan_name} --location={location} --quiet

# Create Restore Plan
gcloud beta container backup-restore restore-plans create {restore_plan_name} \
  --location={location} \
  --cluster=projects/{project_id}/locations/{location}/clusters/{target_cluster_name} \
  --backup-plan=projects/{project_id}/locations/{location}/backupPlans/{source_backup_plan_name} \
  --all-namespaces \
  --cluster-resource-conflict-policy=use-existing-version \
  --namespaced-resource-restore-mode=fail-on-conflict --quiet

# Execute Restore
gcloud beta container backup-restore restores create {restore_name} \
  --restore-plan={restore_plan_name} --location={location} \
  --backup=projects/{project_id}/locations/{location}/backupPlans/{source_backup_plan_name}/backups/{backup_name} \
  --quiet

# Verify Restore Status
gcloud beta container backup-restore restores describe {restore_name} \
  --restore-plan={restore_plan_name} --location={location}

> [!WARNING] **`--include-volume-data` and `--include-secrets` BOTH DEFAULT TO > FALSE.** If you omit them, the backup plan silently produces **config-only > backups** with no persistent volume snapshots and no Secrets. Always pass both > flags explicitly when the goal is full workload protection.

Notes:

• The `backup-restore` command group requires the `gcloud beta` component

(`gcloud components install beta`).

• `--cluster` requires the full resource path

`projects/{project_id}/locations/{location}/clusters/{cluster_name}` (or `projects/{project_id}/zones/{zone}/clusters/{cluster_name}` for zonal clusters), not a bare cluster name.

• Restore plans require exactly one namespaced-resource scope flag:

`--all-namespaces`, `--selected-namespaces={ns1},{ns2}`, `--excluded-namespaces=...`, `--selected-applications=...`, or `--no-namespaces`.

Restore Safety (CRITICAL)

A restore writes into a **live cluster** and, depending on the conflict policy, can overwrite or delete existing resources:

• `--cluster-resource-conflict-policy=use-existing-version` keeps existing

cluster-scoped resources (safe default); `use-backup-version` **deletes** the existing version first — deleting a CRD deletes all of its CRs.

• `--namespaced-resource-restore-mode=fail-on-conflict` aborts on any conflict

(safe default); `merge-skip-on-conflict` skips conflicting resources; `merge-replace-on-conflict` and `merge-replace-volume-on-conflict` **overwrite** existing resources or volumes; `delete-and-restore` **deletes entire conflicting namespaces** (and all resources in them) before restoring.

**Rules:**

1. Validate the restore in a non-production target cluster first. 2. Prefer the safe defaults (`use-existing-version` + `fail-on-conflict`) unless the user explicitly needs to revert live resources. 3. **Always obtain explicit user confirmation before executing a restore into a production cluster**, and state which conflict policy is in effect and what it may overwrite or delete.

Best Practices

1. **CMEK Encryption**: Encrypt backup plans using Customer-Managed Encryption Keys: `--encryption-key=projects/{project_id}/locations/{location}/keyRings/{ring}/cryptoKeys/{key}`. 2. **Scope**: Prefer backing up specific namespaces rather than the entire cluster: `--selected-namespaces={ns1},{ns2}` (instead of `--all-namespaces`). 3. **Application Consistency**: Recommend quiescing the database or pausing application writes (e.g. using pre-backup hooks or database-specific tools) prior to backups to ensure data integrity. 4. **CSI Volume Snapshots**: Ensure that stateful backups utilize GKE's CSI (Container Storage Interface) driver for volume snapshots to capture persistent volume data. 5. **Service Terminology**: Always explicitly refer to the service as **Backup for GKE** in your response. This distinguishes it from the broader (but complementary) Google Cloud **Backup and Disaster Recovery (DR) Service**, ## Golden Path Backup Defaults

The recommended production golden path configuration for Backup for GKE:

• **Addon**: BackupRestore addon enabled

(`--update-addons=BackupRestore=ENABLED`).

• **Volume Inclusion**: `--include-volume-data` explicitly passed (enabled,

since the service default is false).

• **Secret Inclusion**: `--include-secrets` explicitly passed (enabled, since

the service default is false).

• **Retention**: Defined retention period (e.g. 30 days via

`--backup-retain-days=30`).

• **Encryption**: CMEK enabled (`--encryption-key=...`).

Recent Changes

• **Cross-project backup and restore (G