required permissions.md

What Permissions Does the GCP Deployment Require?

Overview

Connecting your GCP environment to Archera provisions IAM permissions and supporting resources that allow Archera to access billing data, monitor commitments, and deliver optimization recommendations. When full procurement capabilities are enabled, Archera can also place and manage GCP Marketplace commitment orders on your behalf.

Archera supports two access modes:

Access mode	Description
Visibility Only	Read-only access for monitoring, analytics, and recommendations.
Full Access (default)	Read access plus the ability to place, modify, and cancel commitment purchases through the GCP Marketplace on your behalf.

All resources are provisioned via Terraform, either directly or through GCP Infrastructure Manager. The permissions are the same regardless of installation method.

Archera service account

Archera authenticates to your GCP environment using an Archera-managed service account:

application@archera.iam.gserviceaccount.com

This service account resides in Archera's GCP project, not yours. During onboarding, the Terraform configuration grants this service account a custom IAM role at the organization level, along with specific predefined roles at the billing account level. Archera does not create any service accounts inside your organization.

Temporary deployment service account

When installing via GCP Infrastructure Manager, a temporary service account is created in your project to execute the Terraform deployment. This account requires broad permissions, including Owner, Organization Administrator, and Billing Admin, so that it can create the resources and bindings required by the integration.

This temporary service account is not used by Archera for ongoing operations. The deployment script removes it after deployment completes; if you run the Terraform directly, delete the temporary account once deployment is complete.

API enablement

The following APIs are enabled in your billing project during onboarding:

API	Purpose
`bigquery.googleapis.com`	Run queries against your billing, pricing, and CUD export datasets.
`bigquerydatatransfer.googleapis.com`	Support scheduled transfer and export of billing data.
`billingbudgets.googleapis.com`	Access billing budget metadata.
`cloudbilling.googleapis.com`	Access billing account information and metadata.
`cloudcommerceconsumerprocurement.googleapis.com`	View and manage GCP Marketplace procurement orders.
`cloudresourcemanager.googleapis.com`	Read organization, folder, and project hierarchy.
`config.googleapis.com`	Run the Terraform deployment via Infrastructure Manager.
`iam.googleapis.com`	Create the custom IAM role and apply role bindings.
`recommender.googleapis.com`	View and manage CUD recommendations.
`storage.googleapis.com`	Provision the billing-data staging bucket.
`storagetransfer.googleapis.com`	Copy billing, pricing, and CUD data for analysis.

Custom IAM role

A custom organization-level IAM role named archera_application is created and bound to the Archera service account.

All permissions are scoped to the minimum required for Archera's functionality and are read-only unless explicitly noted. Write permissions are only included when Visibility Only mode is disabled.

BigQuery reservations and commitments

These permissions allow Archera to view BigQuery reservation and capacity commitment details for optimization recommendations.

bigquery.bireservations.get
bigquery.capacityCommitments.list
bigquery.reservationAssignments.list
bigquery.reservations.get
bigquery.reservations.list

Compute Engine commitments and reservations

These permissions allow Archera to monitor Compute Engine committed use discounts (CUDs) and VM reservations.

compute.commitments.get
compute.commitments.list
compute.reservations.get
compute.reservations.list

Consumer Procurement orders

These permissions allow Archera to view and, in Full Access mode, manage GCP Marketplace orders.

Read permissions are always granted:

consumerprocurement.orderAttributions.get
consumerprocurement.orderAttributions.list
consumerprocurement.orders.get
consumerprocurement.orders.list

Write permissions are granted only in Full Access mode:

Permission	Purpose
`consumerprocurement.orderAttributions.update`	Update order attribution metadata.
`consumerprocurement.orders.cancel`	Cancel pending or active orders.
`consumerprocurement.orders.modify`	Modify existing order parameters.
`consumerprocurement.orders.place`	Place new procurement orders.

Additional procurement roles are applied at the billing account level. See Billing account IAM permissions.

Resource Manager

These permissions allow Archera to understand your GCP organization structure for cost and commitment attribution. They do not permit modifications to your organization, folders, or projects.

resourcemanager.folders.get
resourcemanager.folders.list
resourcemanager.organizations.get
resourcemanager.projects.get
resourcemanager.projects.list

Spend-based CUD recommendations

Read permissions are always granted:

recommender.spendBasedCommitmentRecommendations.get
recommender.spendBasedCommitmentRecommendations.list
recommender.spendBasedCommitmentInsights.get
recommender.spendBasedCommitmentInsights.list
recommender.spendBasedCommitmentRecommenderConfig.get

Write permissions are granted only in Full Access mode:

recommender.spendBasedCommitmentRecommendations.update
recommender.spendBasedCommitmentInsights.update
recommender.spendBasedCommitmentRecommenderConfig.update

Resource-based CUD recommendations

Read permissions are always granted:

recommender.usageCommitmentRecommendations.get
recommender.usageCommitmentRecommendations.list
recommender.commitmentUtilizationInsights.get
recommender.commitmentUtilizationInsights.list

Write permissions are granted only in Full Access mode:

recommender.usageCommitmentRecommendations.update
recommender.commitmentUtilizationInsights.update

Monitoring and Service Usage

These permissions are required for CUD recommendation analysis.

monitoring.timeSeries.list
serviceusage.consumerpolicy.analyze
serviceusage.consumerpolicy.get
serviceusage.contentsecuritypolicy.get
serviceusage.effectivemcppolicy.get
serviceusage.effectivepolicy.get
serviceusage.groups.list
serviceusage.groups.listExpandedMembers
serviceusage.groups.listMembers
serviceusage.mcppolicy.get
serviceusage.operations.get
serviceusage.quotas.get
serviceusage.services.get
serviceusage.services.list
serviceusage.services.use
serviceusage.values.test

Billing account IAM permissions

In addition to the custom organization-level role, Archera requires predefined roles at the billing account level. Billing account roles are required because billing accounts may exist outside the organization resource hierarchy, where organization-level custom roles cannot be applied.

Read roles are always granted:

Role	Purpose
`roles/consumerprocurement.orderViewer`	List and view procurement orders on the billing account.
`roles/billing.viewer`	View CUD recommendations scoped to the billing account.

Write roles are granted only in Full Access mode:

Role	Purpose
`roles/consumerprocurement.orderAdmin`	Place, modify, and cancel procurement orders.
`roles/billing.admin`	Manage CUD recommendations for the billing account.

Cloud Storage bucket

A GCS bucket is provisioned for temporary staging of billing and pricing data before transfer to Archera's infrastructure.

Property	Value
Bucket name	`archerastorage_{billing_account_id}`
Location	`US`
Storage class	`STANDARD`
Object lifecycle	Objects are automatically deleted after 7 days.
Access control	Uniform bucket-level access; public access prevented.

The following IAM bindings are scoped to this bucket only:

Role	Purpose
`roles/storage.legacyBucketOwner`	Granted to the Archera service account to manage the staging bucket lifecycle.
`roles/storage.legacyBucketReader`	Granted to the Storage Transfer Service for bucket metadata reads.
`roles/storage.objectViewer`	Granted to the Storage Transfer Service for object reads during data transfers.

BigQuery permissions

Archera requires read access to the BigQuery billing export datasets configured during onboarding, including detailed usage cost, pricing, and CUD exports, to analyze spending and generate recommendations.

Project-level

Role	Purpose
`roles/bigquery.jobUser`	Execute BigQuery queries against billing data in the billing project only.

Dataset-level

Role	Purpose
`roles/bigquery.dataViewer`	Read-only access to the billing export datasets configured during onboarding, such as `billing_export` and `billing_export_cud`.

Access is scoped to the specific datasets you configure. Archera has no access to any other datasets in your project.

Security summary

Archera's GCP integration follows the principle of least privilege:

A custom IAM role at the organization level ensures only the specific permissions listed above are granted.
BigQuery access is scoped to individual billing export datasets, not the entire project.
The Cloud Storage bucket is used solely for temporary staging, with a 7-day automatic deletion rule.
All write permissions are optional and only granted when Full Access mode is enabled.
The deployment service account is temporary and is removed after installation.
Archera's application service account is externally managed. No service accounts are created inside your organization.

Troubleshooting

Organization policy constraints

If your organization enforces IAM policy member restrictions, deployment may fail with:

One or more users named in the policy do not belong to a permitted customer.

To resolve:

If iam.managed.allowedPolicyMembers is enforced, add serviceAccount:application@archera.iam.gserviceaccount.com to the allowedMemberSubjects list.
If iam.allowedPolicyMemberDomains is enforced, add Archera's customer ID C02c8qgso to the allowedValues list.