Google Cloud Storage

The Google Cloud Storage integration backs up and restores GCS buckets, and can host a Kloset store in a bucket. A backup captures the bucket contents, including objects, metadata and prefix hierarchies, and stores them in a Kloset store with encryption and deduplication.

The integration includes three connectors:

Requirements

• A GCS bucket, or a custom endpoint for local testing.
• Credentials for that bucket, unless they are detected automatically. See Authentication.

Installation

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

$ plakar pkg add gcs

$ plakar pkg show

$ plakar pkg build gcs

$ plakar pkg add -allow-unsigned ./gcs_v1.0.0_darwin_arm64.ptar

$ plakar pkg show

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

Authentication

The integration authenticates automatically when possible. For example, when the gcloud CLI is installed and authenticated locally, no explicit credentials are needed. When automatic authentication is not available, provide one of the following:

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

When using a custom endpoint for local testing, combine it with no_auth=true or explicit credentials as appropriate.

Configuration

All three connectors use the gcs:// protocol. The source connector retrieves objects from a bucket through the GCS API. The destination connector writes them back to a bucket. The store connector keeps all Kloset store data, including snapshots, chunks and metadata, as objects in a bucket.

Backup flow

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

Restore flow

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

Store flow

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

Shared configuration

The following options apply to the source, destination and store connectors.

Credentials are required only when automatic authentication is not available. See Authentication.

Example

Back up a bucket:

$ 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"

Restore a snapshot to a bucket:

$ 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>

Host a Kloset store in a bucket, 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

Limitations and scope

GCS object storage is flat, and directory structures are simulated using prefixes. Empty directories are not preserved unless they contain objects.

See also

• Creating a Kloset Store
• Managing packages