Before you begin

Prepare these items before opening the guided setup. See Docs authority & product state for how these docs relate to your customer agreement and deployed configuration.

Choose an authorized operator

An authorized developer, Engineer, or Admin can complete the engineering active-use path. Use the least-privileged role that can perform each task.

Task	Required role or permission
Create the tenant and configure IdP federation	Admin with tenant and identity settings access
Confirm product entitlement	Admin with subscription settings access
Register a source or upload a provider export file	Engineer or Admin with connector settings access
Create cloud-side read-only resources	Cloud administrator for setup only
Deploy and run readiness probes	Engineer with deployment access

The setup identity may create roles and assignments. Venturi’s standing cloud identity remains read-only.

Install local tools

Tool	Version	Check
Terraform	1.5 or later	terraform version
Cloud CLI	Current supported release	aws --version, gcloud version, or az version
python3	Any supported Python 3 release	python3 --version
curl	Any supported release	curl --version

The Google Cloud and Azure module verifiers (scripts/verify.sh) parse JSON with python3, and the Google Cloud verifier sends its write probe with curl. You download each cloud’s module as a pinned Terraform artifact from guided setup, so no source-control client is needed.

Authenticate to the exact account, project, or subscription you intend to connect:

AWSGoogle CloudAzure

Bash

aws sts get-caller-identity

The setup principal needs permission to create the IAM role and add its inline policies: iam:CreateRole, iam:PutRolePolicy, iam:TagRole for the role’s tags, and iam:PutRolePermissionsBoundary if you set or change permission_boundary_arn. It also needs the IAM read and delete actions that Terraform uses to refresh and destroy the role. The local boundary check on Deploy runs as the same principal and needs iam:ListAttachedRolePolicies, iam:ListRolePolicies, iam:GetRolePolicy, and iam:SimulatePrincipalPolicy.

The generated role trusts only the Venturi principal that presents your tenant’s external ID, so your own credentials cannot assume it; the local check inspects the role’s policies instead. Venturi assumes it with 15-minute sessions (DurationSeconds=900, the AWS minimum); the role keeps the 1-hour default maximum session duration. Each AssumeRole event in your CloudTrail records the session expiration.

When you revoke access with terraform destroy, Terraform deletes the role’s inline policies and then the role. AWS evaluates a session’s permissions on every request, so a session issued before revocation loses access once the policy deletion propagates, which AWS notes can take a few minutes. Its credentials expire no later than 15 minutes after issue in any case.

Bash

gcloud auth login
gcloud auth application-default login
gcloud config set project "<project_id>"

Terraform uses the Application Default Credentials; the module verifier uses the gcloud CLI’s own credentials from gcloud auth login.

The setup principal needs these roles on the project for the apply:

• roles/iam.workloadIdentityPoolAdmin creates the Workload Identity pool and provider.
• roles/iam.serviceAccountAdmin creates the Venturi service account and its Workload Identity binding.
• roles/resourcemanager.projectIamAdmin grants the read-only project roles to that service account.

When you set billing_dataset_id, the apply also grants read access on that billing-export dataset, so the setup principal needs permission to change access on the dataset, such as roles/bigquery.dataOwner on it. The dataset must be in the same project as project_id: the module connects 1 project and cannot grant access to a billing-export dataset in another project. Workload Identity Federation is the default; do not create an exported service-account key.

Workload Identity Federation and service-account impersonation need the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs. The module does not enable APIs, so enable any that are not already on, as a principal with serviceusage.services.enable, such as roles/serviceusage.serviceUsageAdmin:

Bash

gcloud services enable iam.googleapis.com cloudresourcemanager.googleapis.com \
  iamcredentials.googleapis.com sts.googleapis.com --project "<project_id>"

The module verifier on Deploy reads the project IAM policy, lists the service account’s keys, and lists the project’s Workload Identity pools. The setup roles above already read the project IAM policy (roles/resourcemanager.projectIamAdmin) and list pools (roles/iam.workloadIdentityPoolAdmin). The identity that runs the verifier also needs:

• roles/iam.serviceAccountViewer on the project lists the service account’s keys (iam.serviceAccountKeys.list). Without it, the verifier stops with FAIL: could not list keys.
• roles/iam.serviceAccountTokenCreator on the Venturi service account lets the verifier impersonate it for the BigQuery write probe. Grant it only for the verification run and remove it afterward. Without it, the write probe reports SKIP, which does not fail the local check: automated credential validation runs the denied-write probes as Venturi’s identity.

A principal other than the setup principal that runs the verifier also needs permission to read the project IAM policy (resourcemanager.projects.getIamPolicy) and to list Workload Identity pools, for example through roles/iam.workloadIdentityPoolViewer. Without the pool-list permission, the verifier prints MISS WIF pool, which fails the check.

The local check passes only when the verifier’s project-scope role lines are exactly role: roles/monitoring.viewer, role: roles/logging.viewer, and role: roles/serviceusage.serviceUsageConsumer. Its allowlist also prints roles/bigquery.dataViewer, roles/iam.serviceAccountTokenCreator, and roles/iam.workloadIdentityUser as OK, so treat any other role: line as a security finding. See Verify & confirm.

To exercise the write probe locally, add the impersonation grant before you run the verifier. A new grant can take a few minutes to take effect.

Bash

gcloud iam service-accounts add-iam-policy-binding "<service_account_email>" \
  --member="user:<your_email>" --role="roles/iam.serviceAccountTokenCreator"

Remove the grant after the verification run:

Bash

gcloud iam service-accounts remove-iam-policy-binding "<service_account_email>" \
  --member="user:<your_email>" --role="roles/iam.serviceAccountTokenCreator"

Bash

az login
az account set --subscription "<subscription_id>"

The setup principal needs a grant in Microsoft Entra ID and a separate grant in Azure RBAC:

Principal	Microsoft Entra ID	Azure subscription
Human operator	The Application Developer role, which registers the application and creates its service principal and credentials as their owner; Cloud Application Administrator or Application Administrator also works	Owner, User Access Administrator, or Role Based Access Control Administrator, so the apply can create role assignments; if not Owner, set ARM_SKIP_PROVIDER_REGISTRATION=true before terraform init
CI service principal	The Microsoft Graph application permission Application.ReadWrite.OwnedBy, with admin consent; it manages only applications that the CI principal owns	The same role-assignment authority as a human operator

Application.ReadWrite.OwnedBy is an application permission for a non-interactive principal; it is not a role you assign to a person. Microsoft Entra roles and Azure roles are separate: the Global Administrator role alone does not grant access to the subscription. Before the apply, a Global Administrator must elevate access or hold an Azure role from the table above on the subscription.

The module pins the azurerm provider at ~> 3.80, which by default tries to register every Azure resource provider it supports that is not yet registered on the subscription. Owner can register resource providers; User Access Administrator and Role Based Access Control Administrator cannot, so with either of those roles, run export ARM_SKIP_PROVIDER_REGISTRATION=true before terraform init. The module’s own resources are Microsoft Entra ID objects and role assignments, which need no additional resource provider.

Prepare a separate verification identity as well: a member user who holds only the Reader role on the subscription. The module verifier on Deploy runs its write probes as the signed-in identity, so it must run as this Reader-only identity, never as the setup principal. Member users can read application registrations and service principals by default, which the verifier also needs.

Federation is the default and creates no client secret. If you enable the client-secret fallback, the secret has a 90-day TTL and its value is stored in Terraform state even though the module does not output it, so keep that state in an encrypted, access-controlled backend.

Gather customer-owned values

• AWS: CUR bucket, prefix, region, and whether Bedrock inventory is needed.
• Google Cloud: project ID, project number, and a billing-export dataset in that same project.
• Azure: tenant ID, subscription ID, and whether Azure OpenAI telemetry uses APIM or Event Hubs.
• Provider export path: a supported provider export file from the period you want to inspect.
• Provider API path: customer-provided provider-account credentials, read-only wherever the provider offers read-only credentials. The Anthropic and OpenAI connectors require an Admin API key.

Venturi tenant, connector, federation, and external-ID setup artifacts are generated in-product. Customer-provided provider-account credentials or provider exports are entered in-product. Credentials remain tenant-local and are validated for read-only access wherever the provider offers read-only credentials. No Venturi-human response or emailed setup value is required.

Cloud onboarding uses no long-lived cloud credentials by default; the optional Azure client-secret fallback is the only cloud exception. Provider-account credentials for provider APIs work differently: Venturi stores them as encrypted credential references, and they remain valid until you rotate or revoke them. Scope every provider-account credential to read-only access where the provider allows it, and rotate it according to the provider’s policy. OpenAI organization Admin keys support selectable permissions; use only the required read permissions, including Usage: Read for usage and cost reporting and Audit Logs Scope: Read when audit logs are selected. Anthropic Admin API credentials can also authorize management operations. Venturi independently restricts both connectors to GET requests on the approved endpoint allowlist. See the provider credential matrix.

Success evidence

• The guided setup opens for the authorized operator.
• The selected tenant and entitlement are visible.
• Local tool and cloud identity checks succeed.
• The operator can continue to Organization setup.

Recovery

Correct the local tool, cloud account, or role shown by the failed preflight and rerun it. If access cannot be restored in-product, use Support as an optional escalation path.

Continue to the quickstart

Give feedback on this page

Sign in to send feedback. Opens in a new tab.

Copy page details

Docs feedback: Before you begin
Page: https://docs.venturi.systems/prerequisites/