Add a backup repository

This page describes how to create a backup repository for cluster workloads in Google Distributed Cloud (GDC) air-gapped.

A backup repository represents a compatible storage location for your backups. A backup repository is also used to store records of backups, backup plans, restore plans, and restores.

Before you begin

To create a backup repository, you must have the following:

  • A compatible endpoint available.
  • A previously created bucket to use as the backup repository.
  • You have granted access for the object storage bucket.

  • The necessary identity and access role:

    • Organization Cluster Backup Admin: manages backup resources such as backup and restore plans in user clusters. Ask your Organization IAM Admin to grant you the Organization Cluster Backup Admin (organization-cluster-backup-admin) role. For more information, see Role definitions.

Create a repository

Create a repository by using the GDC console or the API.

Console

  1. Sign in to the GDC console.
  2. In the navigation menu, click Backup for Clusters. Ensure no project is selected in the project selector.
  3. Click Create repository.
  4. Enter a repository name. The description is optional.
  5. In the Main cluster (read/write) list, choose a cluster.
  6. In the Linked clusters (read only) list, choose the linked clusters.
  7. In the S3 URI endpoint field, enter an endpoint containing the fully-qualified domain name of your object storage site.
  8. In the Bucket name field, enter the name of the fully qualified name of the bucket, which can be found from the status of the GDC bucket custom resource.
  9. In the Bucket region field, enter the region where the bucket was created.
  10. In the Access Key ID list, enter the access key ID.
  11. In the Access key field, enter the access key.
  12. Click Create.

API

To use the backup and restore APIs, you must configure a valid ClusterBackupRepository custom resource to be the location of your backups, and supply the required credentials.

  1. Get the name of the secret that contains S3 credentials:

    export PROJECT_NAME=PROJECT_NAME
export SA_NAME=SA_NAME
kubectl get secrets --namespace $PROJECT_NAME -o json | jq -r --arg USER_NAME "${SA_NAME:?}" '.items[] | select( (.metadata.annotations."object.gdc.goog/subject"==$USER_NAME)) | .metadata.name'

    Make sure to record the secret name returned by the command and use it as the SECRET_NAME value when you create your ClusterBackupRepository custom resource.

    Replace the following:

    • PROJECT_NAME: the name of your project.
    • SA_NAME: the name of the service account used to access object storage.

  2. To get bucket details like FQDN and endpoints, extract the fullyQualifiedName and zonalEndpoints values from the output:

    kubectl get buckets -n PROJECT_NAME BUCKET_NAME -o yaml

  3. Add a ClusterBackupRepository custom resource to use these credentials and apply the new resource to the Management API server. Backup repositories are cluster-scoped:

    apiVersion: backup.gdc.goog/v1
kind: ClusterBackupRepository
metadata:
  name: CLUSTER_BACKUP_REPOSITORY
  namespace: PROJECT_NAME
spec:
  secretReference:
    namespace: PROJECT_NAME
    name: SECRET_NAME
  endpoint: END_POINT
  type: "S3"
  s3Options:
    bucket: BUCKET_FQDN
    region: REGION
    forcePathStyle: FORCE_PATH_STYLE
  importPolicy: IMPORT_POLICY

    Replace the following:

    • CLUSTER_BACKUP_REPOSITORY: the name of the cluster backup repository.
    • PROJECT_NAME: the name of your project.
    • SA_NAME: the name of the service account used to access object storage.
    • SECRET_NAME: the name of the secret returned from the kubectl get secrets command.
    • ENDPOINT: the fully qualified domain name for the storage system, for example, https://objectstorage.google.gdch.test. For the type field, only a value of S3 is supported.
    • BUCKET_FQDN: the fully qualified name of the bucket.
    • REGION: the region where the bucket was created.
    • FORCE_PATH_STYLE: use the forcePathStyle field to force path style URLs for objects. This field must have a value of true or false.
    • IMPORT_POLICY: set to one of the following:
      • ReadWrite: This repository can be used to schedule or create backups, backup plans, and restores.
      • ReadOnly: This repository can only be used to import and view backups. No new backups or resources can be created in this repository, but restores can use and reference read-only backups for restoration. There is no restriction on how often a backup repository can be used as ReadOnly.

Backup repository import policies

All clusters must have at least one ReadWrite repository to successfully use backup and restore features. ReadOnly repositories are optional, have no limit, and are used to gain visibility into other cluster backups for cross-cluster restores.

ReadOnly repositories cannot be used as storage locations for additional backups or for backup plans within the cluster they were imported.

Importing a repository as ReadWrite claims the repository for that cluster, preventing other clusters from importing the same repository as ReadWrite. After importing a ReadWrite repository, all records of previous backups, backup plans, and restores in that repository are imported into the target cluster as local custom resources.

Importing a repository as ReadOnly does not claim the repository, it only imports the backups, backup plans, restores, and restore plans. Backup plans in read-only repositories don't schedule backups, they exist to provide visibility into what backup plans exist in the cluster you are importing from. Removing a ReadOnly repository cleans up any imported resources from the cluster and has no effect on the resources in the storage location as no write operations occur to object storage for read-only repositories.

When a ReadWrite repository is removed from the cluster:

  • All local custom resources associated with that repository, such as backups and restores, are removed from the current cluster.
  • That cluster's claim on the repository is removed, allowing the repository to be used as ReadWrite by another cluster. However, these resources are not removed from the storage endpoint.

What's next