Deploy the Operata AWS stacks with Terraform

Deploy the full suite of Operata Cloud Collector v3 stacks with Terraform. Operata publishes pre-synthesized Terraform JSON files (.tf.json) — you download one file per stack, set a handful of variables, and run terraform apply. You need Terraform and AWS credentials, nothing else. There’s no CDK, npm, or other build tooling involved. Before you start, know that:

Each stack takes around 5–15 minutes to deploy.
Terraform state is stored locally by default. For team environments, configure a remote backend (S3, for example) before you deploy.
Keep your Operata API key out of version control — pass it inline or store it in a secrets manager.

Before you start

Requirement	Notes
Terraform	v1.8 or later — install guide. The templates don’t set `required_version`, so an older CLI isn’t blocked, but Operata tests against 1.8 and up.
AWS provider	Pinned to exactly `5.100.0` in `required_providers`, not a range. If you run a provider mirror or an air-gapped registry, stock that version before you run `terraform init`.
AWS credentials	In the target account, with permission to create IAM, Lambda, Kinesis, EventBridge, Secrets Manager, and CloudWatch Logs resources — and, for `clrules`, CloudFormation and Amazon Connect rule resources
Operata Group ID	How to find your Operata Group ID
Operata API key	How to create an API key
Terraform templates	Download one per stack from Available stacks below.

Available stacks

Stacks are independent — deploy them in any combination.

Stack	What it collects	Template	VPC variant
Contact Trace Records (CTR)	CTR data from your Amazon Connect Kinesis stream	Download	Download
Contact Lens Data (CLD)	Contact Lens output from S3	Download	Download
Contact Flow Logs (CFL)	Contact flow logs from CloudWatch	Download	Download
Lex V2 Logs	Lex V2 conversation logs from CloudWatch	Download	Download
Contact Lens Rules (CLR)	Real-time and post-call Contact Lens rules, deployed into your Amazon Connect instance via nested CloudFormation stacks	Download	—

Choose a VPC variant only if your AWS account requires Lambda functions to run inside a VPC — typically enterprise or regulated environments. VPC variants take two extra variables: a VPC ID and a list of private subnet IDs. If you’re not sure which you need, ask whoever manages your AWS account. The standard (non-VPC) variant is usually the right choice.

Deploy a stack

Deploy only the stacks you need, in any order. Each section below is a complete, ready-to-run deploy block. Fill in your own values — Group ID, API key, ARNs, and log group names — before you run it.

Resource names are fixed. Every template hard-codes prod into its secret names, resource names, and — for clrules — its CloudFormation stack name. There’s no environment variable to set. Deploying the same stack twice into one AWS account and region collides on those names.

Contact Trace Records (CTR)

mkdir -p ~/operata/ctr
cd ~/operata/ctr
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-contact-trace-records.tf.json
cat > terraform.tfvars <<EOF
aws_region                     = "ap-southeast-2"
operata_group_id               = "<your-operata-group-id>"
operata_api_key                = "<your-operata-api-key>"
ctr_kinesis_stream_arn         = "arn:aws:kinesis:ap-southeast-2:111111111111:stream/..."
connect_instance_friendly_name = "Prod"
agent_data_s3_bucket_name      = ["", ""]
EOF
terraform init
terraform apply

The pipe filters on { "data": { "Channel": ["VOICE"] } }, so it forwards voice contacts only. Chat and task contacts never reach Operata. See IAM policies for the full pipe configuration. agent_data_s3_bucket_name takes a two-element list in the format ["bucket-name", "prefix/"]. Enter those values if you have an agent data S3 bucket set up. Otherwise leave it as ["", ""]. To remove the stack, run terraform destroy. For the VPC variant:

mkdir -p ~/operata/ctr-vpc
cd ~/operata/ctr-vpc
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-contact-trace-records-vpc.tf.json
cat > terraform.tfvars <<EOF
aws_region                            = "ap-southeast-2"
operata_group_id                      = "<your-operata-group-id>"
operata_api_key                       = "<your-operata-api-key>"
ctr_kinesis_stream_arn                = "arn:aws:kinesis:ap-southeast-2:111111111111:stream/..."
connect_instance_friendly_name        = "Prod"
agent_data_s3_bucket_name             = ["", ""]
enrichment_lambda_vpc_id              = "vpc-0123456789abcdef0"
enrichment_lambda_vpc_private_subnets = ["subnet-aaaa", "subnet-bbbb"]
EOF
terraform init
terraform apply

Contact Lens Data (CLD)

mkdir -p ~/operata/cld
cd ~/operata/cld
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-contact-lens-data.tf.json
cat > terraform.tfvars <<EOF
aws_region                       = "ap-southeast-2"
operata_group_id                 = "<your-operata-group-id>"
operata_api_key                  = "<your-operata-api-key>"
contact_lens_data_s3_bucket_name = "<your-contact-lens-bucket>"
EOF
terraform init
terraform apply

To remove the stack, run terraform destroy. For the VPC variant:

mkdir -p ~/operata/cld-vpc
cd ~/operata/cld-vpc
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-contact-lens-data-vpc.tf.json
cat > terraform.tfvars <<EOF
aws_region                                       = "ap-southeast-2"
operata_group_id                                 = "<your-operata-group-id>"
operata_api_key                                  = "<your-operata-api-key>"
contact_lens_data_s3_bucket_name                 = "<your-contact-lens-bucket>"
s3_kinesis_integrator_lambda_vpc_id              = "vpc-0123456789abcdef0"
s3_kinesis_integrator_lambda_vpc_private_subnets = ["subnet-aaaa", "subnet-bbbb"]
EOF
terraform init
terraform apply

Contact Flow Logs (CFL)

cf_log_group is the CloudWatch log group Amazon Connect delivers flow logs to — /aws/connect/<your-instance-alias>. Find yours in the CloudWatch console, or see Contact flow logs.

mkdir -p ~/operata/cfl
cd ~/operata/cfl
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-contact-flow-logs.tf.json
cat > terraform.tfvars <<EOF
aws_region                     = "ap-southeast-2"
operata_group_id               = "<your-operata-group-id>"
operata_api_key                = "<your-operata-api-key>"
cf_log_group                   = "/aws/connect/operata-prod"
connect_instance_friendly_name = "Prod"
EOF
terraform init
terraform apply

To remove the stack, run terraform destroy. For the VPC variant:

mkdir -p ~/operata/cfl-vpc
cd ~/operata/cfl-vpc
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-contact-flow-logs-vpc.tf.json
cat > terraform.tfvars <<EOF
aws_region                             = "ap-southeast-2"
operata_group_id                       = "<your-operata-group-id>"
operata_api_key                        = "<your-operata-api-key>"
cf_log_group                           = "/aws/connect/operata-prod"
connect_instance_friendly_name         = "Prod"
cfl_decoder_lambda_vpc_id              = "vpc-0123456789abcdef0"
cfl_decoder_lambda_vpc_private_subnets = ["subnet-aaaa", "subnet-bbbb"]
EOF
terraform init
terraform apply

Lex V2 Logs

mkdir -p ~/operata/lexv2
cd ~/operata/lexv2
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-lexv2-logs.tf.json
cat > terraform.tfvars <<EOF
aws_region         = "ap-southeast-2"
operata_group_id   = "<your-operata-group-id>"
operata_api_key    = "<your-operata-api-key>"
lex_log_group_name = "/aws/lex/<your-bot>/conversation-logs"
EOF
terraform init
terraform apply

To remove the stack, run terraform destroy. For the VPC variant:

mkdir -p ~/operata/lexv2-vpc
cd ~/operata/lexv2-vpc
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-lexv2-logs-vpc.tf.json
cat > terraform.tfvars <<EOF
aws_region                                = "ap-southeast-2"
operata_group_id                          = "<your-operata-group-id>"
operata_api_key                           = "<your-operata-api-key>"
lex_log_group_name                        = "/aws/lex/<your-bot>/conversation-logs"
lex_enrichment_lambda_vpc_id              = "vpc-0123456789abcdef0"
lex_enrichment_lambda_vpc_private_subnets = ["subnet-aaaa", "subnet-bbbb"]
EOF
terraform init
terraform apply

Contact Lens Rules (clrules)

Deploy this stack if your Operata configuration uses Contact Lens event processing. clrules deploys two sets of Amazon Connect rules into your instance — one for real-time Contact Lens analysis and one for post-call. This Terraform stack wraps the Operata Contact Lens Rules CloudFormation template in an aws_cloudformation_stack resource. Running terraform apply provisions a nested CloudFormation stack named operata-contact-lens-rules-prod in your account, which in turn creates the Connect rules.

mkdir -p ~/operata/clrules
cd ~/operata/clrules
curl -O https://operata-customer-assets.s3.amazonaws.com/ccv3-templates/cloud-collector-v3-contact-lens-rules.tf.json
cat > terraform.tfvars <<EOF
aws_region                  = "ap-southeast-2"
amazon_connect_instance_arn = "arn:aws:connect:ap-southeast-2:111111111111:instance/<your-instance-id>"
EOF
terraform init
terraform apply

The apply takes around 25 seconds. Rule creation is serialized to respect the Amazon Connect CreateRule API rate limit of 2 requests per second. Confirm the rules landed:

aws connect list-rules \
  --region ap-southeast-2 \
  --instance-id <your-instance-id> \
  --publish-status PUBLISHED \
  --query 'RuleSummaryList[?starts_with(Name, `operata_`)] | length(@)'

To remove the stack, run terraform destroy. clrules creates no AWS Secrets Manager secrets, so no force-deletion step is required afterwards.

Verify

1. Place a test contact

Make or receive a short test call in your Amazon Connect instance. On an inbound call, close the contact before you check for data, or it won’t appear. Data can take up to five minutes to reach Operata after the call ends.

2. Check API activity

Open Group Settings → Integrations → API Management and look for a recent Last Used timestamp on the API key.

Recent activity — your stack is sending data. Continue to step 3.
No recent activity — stop here. Check that operata_api_key and operata_group_id in your terraform.tfvars match your Operata account, then test again. If there’s still no activity, contact Operata support.

3. Check the data view for your stack

CTR — open Calls and Logs → Details / Summary and confirm the test call appears.
Contact Lens (CLD) — open Dashboards → Conversational Analytics and confirm data appears. Filter by the test agent’s name or sort by most recent call.

If nothing appears after 10 minutes, work through Troubleshooting.

Upgrade an existing stack

To apply a newer Operata release to a stack you’ve already deployed:

Download the new .tf.json file into the same working directory, replacing the previous file. Filenames carry no version tag, so the latest release is always at the same URL.
Run terraform plan and confirm only the expected resources change — typically the Lambda zip key and a few metadata fields.
Run terraform apply.

If unexpected resources appear in the plan, contact Operata before you continue.

State in the working directory tracks resource identity, so the upgrade happens in place. Terraform doesn’t replace the EventBridge pipe, the Kinesis stream, or the IAM resources. For clrules, terraform apply triggers a CloudFormation stack update on the nested operata-contact-lens-rules-prod stack, which diffs and updates only the changed rules. Each stack upgrades independently. Collection pauses for roughly 2–5 minutes per stack while the apply runs, and calls handled in that window don’t reach Operata — so schedule upgrades outside peak contact center hours where you can.

Redeploy after a destroy

AWS Secrets Manager schedules secrets for deletion with a 30-day recovery window — terraform destroy doesn’t remove them immediately. Run terraform apply again before that window expires and the apply fails with:

InvalidRequestException: You can't create this secret because a secret with this name is already scheduled for deletion.

To unblock an immediate redeploy, force-delete the affected secrets after the destroy:

aws secretsmanager delete-secret \
  --region ap-southeast-2 \
  --secret-id /cloud-collector-v3/ctr/apiToken-prod \
  --force-delete-without-recovery

--force-delete-without-recovery removes the secret permanently. Use it only when you intend to recreate it immediately.

Secrets created per stack:

Stack	Secrets
`clrules`	None
CTR	`/cloud-collector-v3/ctr/apiToken-prod`
CLD	`/cloud-collector-v3/cld/apiToken-prod`
CFL	`/cloud-collector-v3/cfl/apiToken-prod`, `/cloud-collector-v3/cfl/redactionPolicyCache-prod`
Lex V2 Logs	`/cloud-collector-v3/lex/apiToken-prod`, `/cloud-collector-v3/lex/redactionPolicyCache-prod`

Troubleshooting

Work through these before you contact Operata support. EventBridge Pipe fails to create on the first apply. This is an IAM eventual-consistency issue. The role and policies are created correctly, but EventBridge runs an upfront access check before IAM has finished propagating. Run terraform apply again — Terraform leaves the role in place and retries only the pipe. Secret already scheduled for deletion. Force-delete the affected secrets from the CLI (see Redeploy after a destroy), then apply again. CLD deploys cleanly but no data appears in Operata. The EventBridge Pipe shows RUNNING but no Contact Lens summaries arrive. Check that Contact Lens is enabled on your Amazon Connect instance and that calls run with Contact Lens analysis turned on. Terraform inline_policy deprecation warning. Terraform may print a deprecation warning on aws_iam_role.inline_policy. It’s a provider-level notice. The configuration applies cleanly and the warning has no functional impact.

Get help

If you hit an issue, or you’re not sure which stacks or environment apply to your setup, email help@operata.com or send a message from inside the Operata app.

Install CTR collection — the CloudFormation path for the same collector.
Install Contact Lens — Contact Lens prerequisites and configuration.
IAM policies — the permissions each stack needs.
Troubleshoot the integration — missing records, deployment failures, secret management.

​Before you start

​Available stacks

​Deploy a stack

​Contact Trace Records (CTR)

​Contact Lens Data (CLD)

​Contact Flow Logs (CFL)

​Lex V2 Logs

​Contact Lens Rules (clrules)

​Verify

​1. Place a test contact

​2. Check API activity

​3. Check the data view for your stack

​Upgrade an existing stack

​Redeploy after a destroy

​Troubleshooting

​Get help

​Related

Before you start

Available stacks

Deploy a stack

Contact Trace Records (CTR)

Contact Lens Data (CLD)

Contact Flow Logs (CFL)

Lex V2 Logs

Contact Lens Rules (clrules)

Verify

1. Place a test contact

2. Check API activity

3. Check the data view for your stack

Upgrade an existing stack

Redeploy after a destroy

Troubleshooting

Get help

Related