> Clumio user guide > Set up > Google Cloud Platform (GCP)

Connecting a GCP project using Terraform

Clumio supports onboarding GCP projects for Google Cloud Storage (GCS) backup using Terraform. The template creates a service account in your project and grants it the least-privilege roles Clumio requires. Clumio uses this service account to access the GCS resources managed by the template and to request the additional information within your GCP project needed to perform backups and restores.

After you connect your GCP project to Clumio, you can edit, update, or add protection to your connection at any time.

Prerequisites

Before running the Terraform configuration, ensure the following are in place:

Requirement Details
Terraform Version >= 1.3.0
GCP project An active GCP project with billing enabled
GCP permissions The identity running Terraform must hold the IAM roles listed under "Issue: Insufficient GCP permissions", below.
Clumio API token See "Obtaining a Clumio API access token", below.

Obtaining a Clumio API access token

A Clumio API token is required to authenticate the Terraform provider.

  1. Log in to the Clumio portal.
  2. Navigate to Administration → Access Management → API Tokens in the left-hand sidebar.
  3. Click Generate New Token.
  4. Provide a descriptive name (for example, terraform-gcp-onboarding) and set an appropriate expiry.
  5. Copy the token immediately — it is not shown again.
  6. Store it securely, for example in GCP Secret Manager, AWS Secrets Manager, or a local .tfvars file (ensure this file is git-ignored).

Onboarding steps

  1. From Clumio, select GCP > Connect.
  2. The GCP Projects page appears.
  3. Click the + icon and select Add Project with Terraform.

The Clumio page in the Terraform Registry appears. The page provides instructions on how to use the provider.

How it works

When you run the configuration, Terraform first creates a Clumio connection for your project and the regions you selected, then deploys the resources Clumio requires into your project. Once these resources are in place, Clumio can perform backup and restore on the GCS data in the regions you specified.

The template creates a service account in your project, or uses an existing service account that you supply through customer_service_account_email. All of the permissions defined in the template are granted to this service account. The service account, in turn, allows a Clumio service account to impersonate it and generate short-lived access tokens, which Clumio uses to access and protect your data.

The resources deployed into your project include:

  • The service account described above, which holds all permissions granted by the template.
  • A set of Clumio custom roles scoped to GCS backup, restore, and inventory.
  • The IAM bindings required to read and protect your GCS data.
  • A Pub/Sub topic for change notifications.
  • A Cloud Asset Inventory feed for GCS change ingestion.

Deployment steps

  1. Initialize Terraform and download providers/modules 

    terraform init

  2. Preview the planned changes 

    terraform plan \
  -var="clumio_api_token=<your_token>" \
  -var="project_id=<your_gcp_project_id>"

  3. Apply the configuration 

    terraform apply \
  -var="clumio_api_token=<your_token>" \
  -var="project_id=<your_gcp_project_id>"

Tip

For production deployments, store sensitive variables in a terraform.tfvars file (excluded from version control) or inject them via environment variables using the TF_VAR_ prefix:

export TF_VAR_clumio_api_token="<your_token>"

After the apply completes, return to the Clumio portal and confirm the project appears as connected on the GCP Connect page.

Debugging and troubleshooting

Issue: "Onboarding in progress. Please try again in some time"

Symptom: terraform apply fails at clumio_gcp_connection.this with a retryable error indicating that onboarding for the requested region is still in progress.

Cause: Clumio is still provisioning the resources required to support the requested region.

Resolution: Wait a couple of minutes and re-run terraform apply. If the error persists for more than 10 minutes, contact Clumio support with your project ID and the requested region.

Issue: Insufficient GCP permissions

Symptom: Error: googleapi: Error 403: Permission denied on resource ...

Resolution: Ensure the principal executing Terraform has the following IAM roles on the target project:

Role Purpose
roles/serviceusage.serviceUsageAdmin Enable required Google APIs (cloudasset, pubsub, storage, storagetransfer, storageinsights, monitoring, iamcredentials)
roles/iam.serviceAccountAdmin Create the service account and manage its IAM policy bindings
roles/iam.roleAdmin Create the Clumio custom project roles (GCSInvPermission, GCSBackupPermissions, GCSBucketIamPolicy, GCSRestorePermissions, GCSDeltaTopicPermission, GCSDeltaFedSAPolicy)
roles/resourcemanager.projectIamAdmin Bind custom roles and Google service agents at the project level
roles/pubsub.admin Create the customer-delta Pub/Sub topic and set its IAM policy
roles/cloudasset.owner Create the Cloud Asset Inventory project feed for GCS change ingestion
roles/storage.admin Read the GCS project service account and manage bucket IAM bindings used by backup/restore

Issue: Invalid Clumio API token

Symptom: Error: 401 Unauthorized — Invalid or expired API token

Resolution:

  1. Verify the token is active in the Clumio portal under Administration → Access Management → API Tokens.
  2. Ensure clumio_api_base_url matches the region where the token was generated.
  3. Regenerate the token if it has expired and re-run terraform apply.

Reference

Resource Link
Clumio Terraform provider https://registry.terraform.io/providers/clumio-code/clumio
Clumio GCP Terraform template https://github.com/clumio-code/terraform-clumio-gcp-template
×

Loading...