Google Cloud Storage

The Google Cloud Storage integration enables backup and restoration of GCS buckets. All bucket contents including objects, metadata, and prefix hierarchies are captured and stored in a Kloset store with encryption and deduplication.

The Google Cloud Storage integration provides three connectors:

The Google Cloud Storage package can be installed using pre-built binaries or compiled from source.

$ plakar pkg add gcs

$ plakar pkg list

$ plakar pkg build gcs

$ plakar pkg add ./gcs_v1.0.0_darwin_arm64.ptar

$ plakar pkg list

To list, upgrade, or remove the package, see managing packages guide.

The integration will authenticate automatically when possible, for example if the gcloud CLI is installed and configured locally. Otherwise, credentials can be provided explicitly. At least one of the following must be provided when auto-authentication is not available:

• credentials_file - path to a service account JSON credentials file
• credentials_json - inline service account credentials JSON
• no_auth=true for public buckets or testing

These options apply to all three connectors (source, storage, destination).

The source connector retrieves objects from GCS buckets and stores them in a Kloset store with encryption and deduplication.

flowchart LR

subgraph Source["GCS Bucket"]
  FS["Objects"]
end

subgraph Plakar["Plakar"]
  Connector["Retrieve objects via
GCS API"]
  Transform["Encrypt & deduplicate"]
  Connector --> Transform
end

Source --> Connector

Store["Kloset Store"]
Transform --> Store

Register the source and run a backup:

$ plakar source add my-gcs-bucket \
  gcs://bucket_name \
  credentials_file=<PATH_TO_CREDENTIALS_FILE>

$ plakar at /var/backups backup "@my-gcs-bucket"

To back up a specific prefix within a bucket:

$ plakar at /var/backups backup "@my-gcs-bucket:path"

The storage connector uses Google Cloud Storage as the backend for a Kloset store. All Plakar data — snapshots, chunks, metadata — is stored as objects.

flowchart LR

subgraph Sources["Any Source"]
  FS["Data"]
end

subgraph Plakar["Plakar"]
  Transform["Encrypt & deduplicate"]
  Connector["Store via
GCS API"]
  Transform --> Connector
end

Sources --> Transform

subgraph Storage["GCS Bucket"]
  Store["Kloset Store"]
end

Connector --> Store

Register the store, initialize it, and run a backup:

$ plakar store add my-gcs-store \
  gcs://bucket_name \
  credentials_file=<PATH_TO_CREDENTIALS_FILE>

$ plakar at "@my-gcs-store" create
$ plakar at "@my-gcs-store" backup /var/www

Restores objects from a Kloset store back to a GCS bucket.

flowchart LR

Store["Kloset Store"]

subgraph Plakar["Plakar"]
  Transform["Decrypt & reconstruct"]
  Connector["Restore via
GCS API"]
  Transform --> Connector
end

Store --> Transform

subgraph Destination["GCS Bucket"]
  FS["Objects"]
end

Connector --> Destination

Register the destination and restore a snapshot:

$ plakar destination add my-gcs-restore \
  gcs://bucket_name \
  credentials_file=<PATH_TO_CREDENTIALS_FILE>

$ plakar at /var/backups restore -to "@my-gcs-restore" <snapshot_id>

• GCS object storage is flat; directory structures are simulated using prefixes.
• Empty directories are not preserved unless they contain objects.
• When the gcloud CLI is installed and authenticated, no explicit credentials are needed.
• When using a custom endpoint for local testing, combine it with no_auth=true or explicit credentials as appropriate.