AWS Integration Setup Guide

This guide walks you through setting up a read-only IAM role that allows OpsCompanion to monitor your Amazon Web Services accounts using Terraform.

Overview

The Terraform module automates the creation of an IAM role with comprehensive read-only permissions across your AWS account. This allows OpsCompanion to:

Monitor resources across all AWS services (EC2, S3, RDS, Lambda, etc.)
Collect CloudTrail logs for security and compliance monitoring
Access CloudWatch metrics and logs
Track billing and cost information

Important: The IAM role is configured with read-only permissions and cannot make changes to your infrastructure.

What Gets Created

Running this Terraform module will create:

IAM Role - opscompanion-readonly-role (customizable)
IAM Policy - Read-only policy attached to the role
Trust Relationship - Allows OpsCompanion to assume the role using an external ID

Prerequisites

Before running the Terraform module, ensure you have:

1. Terraform Installed

# Check if Terraform is installed
terraform --version

If not installed, download from: https://www.terraform.io/downloads

2. AWS CLI Installed and Configured

# Check if AWS CLI is installed
aws --version

# Check your AWS credentials
cat ~/.aws/credentials

If not configured, run:

aws configure

3. Required AWS Permissions

Your AWS account needs these permissions:

iam:CreateRole - Create IAM roles
iam:AttachRolePolicy - Attach policies to roles
iam:CreatePolicy - Create IAM policies

Recommended role: AdministratorAccess or IAMFullAccess

4. Your OpsCompanion Organization ID

You'll need your organization ID from OpsCompanion. You can find this in your organization settings.

Installation Steps

Step 1: Create a new Terraform file

Create a new file called main.tf in your project directory and add the following module configuration:

module "opscompanion-aws-integration" {
  source = "github.com/opscompanion/opscompanion-integrations-terraform/aws"

  role_name     = "opscompanion-readonly-role"  # Optional, defaults to this value
  custom_org_id = "your-org-id"
}

output "role_arn" {
  value = module.opscompanion-aws-integration.role_arn
}

Replace:

your-org-id with your OpsCompanion organization ID
Optionally customize role_name to match your naming conventions

Step 2: Navigate to the directory where the file is located

cd /path/to/your/terraform/directory

Step 3: Initialize Terraform

Run the command:

terraform init

This will download the OpsCompanion integration module and initialize your Terraform workspace.

Step 4: Review the changes

Run the command:

terraform plan

This will show you what resources will be created. Review the output to ensure it matches your expectations.

Step 5: Execute the Terraform configuration

Run the command:

terraform apply

Type yes when prompted to confirm the changes.

Step 6: Copy the IAM Role ARN

After the Terraform apply completes, it will output the IAM role ARN. Copy this value - you'll need it to complete the integration in OpsCompanion.

Outputs:

role_arn = "arn:aws:iam::123456789012:role/opscompanion-readonly-role"

Step 7: Complete the integration in OpsCompanion

Navigate to the OpsCompanion dashboard
Go to Manage Tools → Amazon Web Services (AWS)
Paste the IAM role ARN

Verification

1. Verify IAM Role Creation

# List IAM roles
aws iam list-roles | grep opscompanion

# Get role details
aws iam get-role --role-name opscompanion-readonly-role

2. Verify Attached Policies

# List attached policies
aws iam list-attached-role-policies --role-name opscompanion-readonly-role

Expected output should include read-only policies.

3. Verify Trust Relationship

# Get the trust policy
aws iam get-role --role-name opscompanion-readonly-role --query 'Role.AssumeRolePolicyDocument'

Should show a trust relationship with the OpsCompanion AWS account and your organization's external ID.

4. Test Role Assumption

You can test that the role can be assumed (requires OpsCompanion credentials):

aws sts assume-role \
  --role-arn arn:aws:iam::YOUR_ACCOUNT_ID:role/opscompanion-readonly-role \
  --role-session-name test-session \
  --external-id YOUR_ORG_ID

Troubleshooting

Error: "Permission denied"

Cause: Your AWS account lacks necessary IAM permissions

Solution:

Verify you have IAM admin permissions
Check your AWS credentials: aws sts get-caller-identity
Ensure you're using the correct AWS profile

Error: "Role already exists"

Cause: IAM role was created in a previous run

Solution: This is normal. Terraform will update the existing role configuration. Run terraform apply again.

Error: "Access denied on AssumeRole"

Cause: Trust relationship or external ID mismatch

Solution:

Verify the external ID matches your OpsCompanion organization ID
Check the trust policy on the IAM role
Ensure the OpsCompanion AWS account is authorized in the trust relationship

Updating the Integration

If you need to update the integration configuration:

Modify your main.tf file
Run terraform plan to review changes
Run terraform apply to apply changes

Removing the Integration

To remove the OpsCompanion integration and clean up resources:

terraform destroy

Type yes when prompted. This will:

Delete the IAM role
Remove attached policies
Clean up all created resources

Security Considerations

Read-Only Access

The IAM role has read-only permissions and cannot:

Create, modify, or delete resources
Change IAM policies or users
Access secret values from Secrets Manager (only metadata)
Modify billing settings or payment methods

CloudTrail Monitoring

All actions taken by the IAM role are logged to CloudTrail and can be reviewed:

# View role activity
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=Username,AttributeValue=opscompanion-readonly-role \
  --max-results 50

External ID Protection

The IAM role requires an external ID for assumption, which:

✅ Prevents confused deputy attacks
✅ Ensures only your OpsCompanion organization can assume the role
✅ Can be rotated if compromised

Principle of Least Privilege

The Terraform module grants only read-only permissions by default, following the principle of least privilege.

Customization

Custom Role Name

You can customize the IAM role name by changing the role_name parameter:

module "opscompanion-aws-integration" {
  source = "github.com/opscompanion/opscompanion-integrations-terraform/aws"

  role_name     = "my-custom-opscompanion-role"
  custom_org_id = "your-org-id"
}

Multiple AWS Accounts

To monitor multiple AWS accounts, run the Terraform module once for each account:

Configure AWS credentials for each account
Run terraform apply in separate directories or workspaces
Add each role ARN to OpsCompanion

Support

Getting Help

Documentation: https://opscompanion.ai/docs
Community: https://discord.gg/TdMZTqSFTq
Email: support@opscompanion.ai

Frequently Asked Questions

Q: Can OpsCompanion modify my resources?

A: No. The IAM role has read-only permissions and cannot create, modify, or delete any resources.

Q: How do I monitor multiple AWS accounts?

A: Run the Terraform module once for each AWS account. Each account gets its own IAM role.

Q: Can I revoke access later?

A: Yes. Run terraform destroy to remove the IAM role. Access is immediately revoked.

Q: What data does OpsCompanion collect?

A: OpsCompanion collects:

Resource metadata and configuration
CloudTrail audit logs (who did what, when)
CloudWatch metrics and logs
Cost and billing data

Not collected:

Application data from databases
File contents from S3 buckets
Secret values from Secrets Manager
Customer data from your applications

AWS Integration Setup Guide

On this page