Open in ChatGPTOpen in Claude

Connect a GCS archive bucket

This guide shows you how to configure a Google Cloud Storage (GCS) bucket to archive your Coralogix telemetry data in the US3 (us-central1) environment. For AWS environments, see Connect an S3 archive bucket.

Note

GCS archiving is currently available for the US3 environment only (us3.coralogix.com, region: us-central1). Contact your Coralogix representative for availability in other environments.

What you need

• A GCP project with the Cloud Storage API active.
• Permission to create buckets and manage Identity and Access Management (IAM) policies in your GCP project.

Choose a configuration method:

Terraform

1.

Access the GCS archive module in the Coralogix Terraform Registry.

2.

Create a Terraform file with the following variables.

Variable	Description
gcp_region	GCP region for the archive buckets. Must match the region associated with your Coralogix account.
coralogix_service_account	Coralogix archive service account email for your environment.
logs_bucket_name	Name for the logs and traces archive bucket. Omit if not needed.
metrics_bucket_name	Name for the metrics archive bucket. Omit if not needed.

Notes:

• Bucket names must be globally unique and follow GCP bucket naming guidelines.
• You cannot use the same bucket for both metrics and logs.
• Optional inputs such as storage_class, project_id, labels, and force-destroy flags are documented in the module README.

module "gcs-archive" {
  source = "coralogix/google/coralogix//modules/v2/gcs-archive"

  gcp_region                = "us-central1"
  coralogix_service_account = "coralogix-archive-us3@coralogix-prod-saas-service.iam.gserviceaccount.com"
  logs_bucket_name          = "my-coralogix-logs-archive"
  metrics_bucket_name       = "my-coralogix-metrics-archive"
}

3.

[Optional] Add CMEK encryption with logs_kms_key_name and metrics_kms_key_name. The Cloud KMS key must be in the same region as the bucket. The module grants the project's GCS service agent roles/cloudkms.cryptoKeyEncrypterDecrypter on the key.

module "gcs-archive" {
  source = "coralogix/google/coralogix//modules/v2/gcs-archive"

  gcp_region                = "us-central1"
  coralogix_service_account = "coralogix-archive-us3@coralogix-prod-saas-service.iam.gserviceaccount.com"
  logs_bucket_name          = "my-coralogix-logs-archive"
  metrics_bucket_name       = "my-coralogix-metrics-archive"
  logs_kms_key_name         = "projects/my-project/locations/us-central1/keyRings/my-ring/cryptoKeys/my-key"
  metrics_kms_key_name      = "projects/my-project/locations/us-central1/keyRings/my-ring/cryptoKeys/my-key"
}

4.

Create the archive buckets by saving the file and running:

terraform init

terraform apply

Manual

Step 1. Create a bucket

In the Google Cloud Console, navigate to Cloud Storage, then Buckets, and create a bucket with the following settings:

1.

Enter a name for your bucket (for example, my-company-cx-logs). Bucket names must be globally unique.

2.

Under Location type, select Region.

Under Region, select us-central1 (Iowa). The bucket region must match your Coralogix domain.

3.

Under Default storage class, keep the default: Standard.

Warning

Do not use Nearline, Coldline, or Archive storage classes. These incur retrieval fees every time Coralogix queries your archive. See Storage costs.

4.

Under Access control, leave Uniform selected and keep Enforce public access prevention enabled.

5.

Click Create.

Step 2. Grant bucket permissions to Coralogix

Coralogix needs Storage Object Admin access to write and read archive data. This is a cross-project IAM grant if Coralogix runs in a different GCP project than your bucket — GCP supports this natively.

1.

In the GCP Console, open your bucket and select the Permissions tab.

2.

Click Grant Access.

3.

In the New principals field, enter the Coralogix archive service account for the US3 environment:

Coralogix GCP environment	Service account
US3 (us3.coralogix.com)	coralogix-archive-us3@coralogix-prod-saas-service.iam.gserviceaccount.com

4.

Under Assign roles, select Storage Object Admin (roles/storage.objectAdmin).

5.

Click Save. The bucket is now ready to use.

Step 3. Connect the bucket in Coralogix

1.

In Coralogix, select Data Flow, then click Setup Archive.

2.

Choose from two bucket options: one for logs and traces (CX data) and one for metrics. You cannot use the same bucket for both.

Enter the name of your GCS bucket.

3.

Click Save. This activates your archive storage. Learn more in Archive retention policy.

How authentication works

Coralogix on GCP uses HMAC keys to authenticate with GCS through the S3-compatible API:

• The Coralogix archive service authenticates with an HMAC access key ID and secret that map to the Coralogix GCP service account.
• HMAC keys work like AWS AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, so Coralogix can use the same S3-compatible archive path on AWS and GCP.
• Coralogix manages the HMAC keys. You do not generate or provide them. Grant the Coralogix service account permissions on your bucket with Terraform or the manual steps above.

Bucket paths across teams

Coralogix can store data for multiple teams in the same bucket. Logs and traces use a separate directory path per team:

gs://BUCKET_NAME/PREFIX/OBJECT.suffix

Team 0 example:

gs://my-bucket-name/cx/parquet/v1/team_id=0/dt=2025-06-29/hr=07/my-object-name.parquet

Team 1 example:

gs://my-bucket-name/cx/parquet/v1/team_id=1/dt=2025-06-29/hr=07/my-object-name.parquet

Customer-managed encryption keys (CMEK)

If your GCS bucket uses a customer-managed encryption key (CMEK), grant the project's GCS service agent roles/cloudkms.cryptoKeyEncrypterDecrypter on the Cloud KMS key. The GCS service agent performs encrypt and decrypt operations for the bucket.

Note

The Cloud KMS key must be in the same region as your GCS bucket. Cross-region CMEK is not supported.

Tip

If you used the Terraform module and set logs_kms_key_name or metrics_kms_key_name, the module grants this permission automatically. Use the steps below only for manual setup.

1.

Ensure the bucket uses a CMEK for default encryption. In the GCP Console, open Cloud Storage, then Buckets, select your bucket, and under Configuration confirm that a Cloud KMS key is set as the default encryption key.

2.

Identify the GCS service agent for your project. It has the form service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com. You can also run:

gcloud storage service-agent --project=PROJECT_ID

3.

In the GCP Console, open Security, then Key Management. Select the key ring and key used for bucket encryption.

4.

Click Grant Access. In New principals, enter the GCS service agent email. Assign Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter).

5.

Confirm the GCS service agent appears on the key permissions list with that role.

Storage costs

Use the Standard storage class for Coralogix archive buckets. GCS offers Standard, Nearline, Coldline, and Archive classes; non-Standard classes charge retrieval fees when Coralogix queries your archive from the UI.

Warning

Approximate retrieval fees (see GCS pricing for current rates):

• Nearline: $0.01 per GiB
• Coldline: $0.02 per GiB
• Archive: $0.05 per GiB

These charges apply each time data is read, including archive queries in Coralogix.

GCS Class A and Class B API operations are also billed to your GCP project. Review GCS pricing for operation costs per storage class.