Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Fdata-flow%2Fgcs-archive.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Fdata-flow%2Fgcs-archive.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.) # 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](https://coralogix.com/docs/user-guides/data-flow/s3-archive/connect-s3-archive.md). 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[​](#what-you-need "Direct link to 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. * To configure the archive bucket in Coralogix, you need `METRICS.DATA-SETUP#LOW:UPDATECONFIG` (Data Admin, Platform Admin). Choose a configuration method: * Terraform * Manual 1 . Access the GCS archive module in the [Coralogix Terraform Registry](https://registry.terraform.io/modules/coralogix/google/coralogix/latest/submodules/gcs-archive). 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](https://cloud.google.com/storage/docs/buckets#naming). * 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](https://github.com/coralogix/terraform-coralogix-google/tree/master/modules/v2/gcs-archive). ``` 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 ``` ### Step 1. Create a bucket[​](#step-1-create-a-bucket "Direct link to Step 1. Create a bucket") In the [Google Cloud Console](https://console.cloud.google.com/), 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](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain.md). 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](#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[​](#step-2-grant-bucket-permissions-to-coralogix "Direct link to 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[​](#step-3-connect-the-bucket-in-coralogix "Direct link to 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](https://coralogix.com/docs/user-guides/data-flow/s3-archive/archive-retention-policy.md). ## How authentication works[​](#how-authentication-works "Direct link to How authentication works") Coralogix on GCP uses **HMAC keys** to authenticate with GCS through the [S3-compatible API](https://cloud.google.com/storage/docs/interoperability): * 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[​](#bucket-paths-across-teams "Direct link to 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)[​](#customer-managed-encryption-keys-cmek "Direct link to 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[​](#storage-costs "Direct link to Storage costs") Use the **Standard** storage class for Coralogix archive buckets. GCS offers [Standard, Nearline, Coldline, and Archive](https://cloud.google.com/storage/docs/storage-classes) classes; non-Standard classes charge retrieval fees when Coralogix queries your archive from the UI. Warning Approximate retrieval fees (see [GCS pricing](https://cloud.google.com/storage/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](https://cloud.google.com/storage/pricing) for operation costs per storage class.