Azure Integration Setup Guide

This guide walks you through setting up a read-only service principal that allows OpsCompanion to monitor your Microsoft Azure subscriptions using Terraform.

Overview

The Terraform module automates the creation of a service principal with comprehensive read-only permissions across your Azure subscription. This allows OpsCompanion to:

Monitor resources across all Azure services (VMs, Storage, Databases, AKS, etc.)
Collect activity logs for security and compliance monitoring
Access Azure Monitor metrics and logs
Track billing and cost information

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

What Gets Created

Running this Terraform module will create:

Azure AD Application - opscompanion-readonly-app (customizable)
Service Principal - Associated with the application
Client Secret - For authentication
Custom Role Assignment - Reader role with additional monitoring permissions
Role Assignment - Assigned at subscription scope

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. Azure CLI Installed and Configured

# Check if Azure CLI is installed
az --version

# Login to Azure
az login

# List your subscriptions
az account list --output table

# Set the subscription you want to use
az account set --subscription "your-subscription-id"

If not installed, download from: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

3. Required Azure Permissions

Your account needs these permissions:

Application Administrator or Global Administrator - Create app registrations
Owner or User Access Administrator - Assign roles at subscription level

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-azure-integration" {
  source = "github.com/opscompanion/opscompanion-integrations-terraform/azure"

  subscription_id   = "your-subscription-id"
  custom_org_id     = "your-org-id"
  app_name          = "opscompanion-readonly-app"           # Optional, defaults to this value
  custom_role_name  = "OpsCompanion Custom Reader Role"     # Optional, defaults to this value
}

output "application_id" {
  value = module.opscompanion-azure-integration.application_id
}

output "tenant_id" {
  value = module.opscompanion-azure-integration.tenant_id
}

output "client_secret" {
  value     = module.opscompanion-azure-integration.client_secret
  sensitive = true
}

output "service_principal_id" {
  value = module.opscompanion-azure-integration.service_principal_id
}

Replace:

your-subscription-id with your Azure subscription ID
your-org-id with your OpsCompanion organization ID
Optionally customize app_name and custom_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 output values

After the Terraform apply completes, it will output the application credentials. Copy these values - you'll need them to complete the integration in OpsCompanion.

To view the client secret (marked as sensitive):

terraform output -raw client_secret

You should have:

Application ID (Client ID)
Tenant ID
Client Secret
Service Principal ID

Step 7: Complete the integration in OpsCompanion

Navigate to the OpsCompanion dashboard
Go to Manage Tools → Microsoft Azure
Paste the required values:
- Subscription ID
- Tenant ID
- Application ID (Client ID)
- Client Secret

Verification

1. Verify App Registration

# List app registrations
az ad app list --display-name opscompanion-readonly-app

# Get app details
az ad app show --id <application-id>

2. Verify Service Principal

# List service principals
az ad sp list --display-name opscompanion-readonly-app

# Get service principal details
az ad sp show --id <service-principal-id>

3. Verify Role Assignment

# List role assignments for the service principal
az role assignment list --assignee <service-principal-id> --output table

Expected output should include the Reader role or custom role at subscription scope.

4. Test Authentication

You can test authentication using the Azure CLI:

az login --service-principal \
  --username <application-id> \
  --password <client-secret> \
  --tenant <tenant-id>

# Try listing resources
az resource list --output table

Troubleshooting

Error: "Insufficient privileges"

Cause: Your Azure account lacks necessary permissions to create app registrations or assign roles

Solution:

Verify you have Application Administrator or Global Administrator role
Check you have Owner or User Access Administrator role at subscription level
Contact your Azure administrator for assistance

Error: "App registration already exists"

Cause: App registration was created in a previous run

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

Error: "Failed to create client secret"

Cause: App registration limits or permissions issues

Solution:

Check the app registration in Azure Portal
Manually remove old secrets if there are too many
Verify your permissions to manage app credentials

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

Note: If you need to rotate the client secret, run terraform apply and it will create a new secret.

Removing the Integration

To remove the OpsCompanion integration and clean up resources:

terraform destroy

Type yes when prompted. This will:

Delete the app registration
Remove the service principal
Remove role assignments
Clean up all created resources

Security Considerations

Read-Only Access

The service principal has Reader permissions and cannot:

Create, modify, or delete resources
Change RBAC assignments
Access secret values from Key Vault (only metadata)
Modify billing settings or payment methods

Activity Log Monitoring

All actions taken by the service principal are logged to Azure Activity Logs and can be reviewed:

# View service principal activity
az monitor activity-log list \
  --caller <service-principal-id> \
  --max-events 50 \
  --output table

Client Secret Management

The client secret should be:

✅ Stored securely in OpsCompanion
✅ Rotated periodically (recommended: every 90 days)
✅ Never committed to source control
✅ Treated as a sensitive credential

Principle of Least Privilege

The Terraform module grants only the Reader role by default, following the principle of least privilege. Additional permissions are granted only for monitoring and diagnostics.

Customization

Custom App Name

You can customize the app registration name:

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

  subscription_id   = "your-subscription-id"
  custom_org_id     = "your-org-id"
  app_name          = "my-custom-opscompanion-app"
}

Custom Role Name

You can customize the custom role name:

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

  subscription_id   = "your-subscription-id"
  custom_org_id     = "your-org-id"
  custom_role_name  = "My Custom Reader Role"
}

Multiple Azure Subscriptions

To monitor multiple Azure subscriptions, run the Terraform module once for each subscription:

Configure Azure CLI for each subscription
Run terraform apply in separate directories or workspaces
Add each set of credentials 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 service principal has read-only permissions and cannot create, modify, or delete any resources.

Q: How do I monitor multiple Azure subscriptions?

A: Run the Terraform module once for each subscription. Each subscription gets its own service principal.

Q: Can I revoke access later?

A: Yes. Run terraform destroy to remove the app registration and service principal. Access is immediately revoked.

Q: What data does OpsCompanion collect?

A: OpsCompanion collects:

Resource metadata and configuration
Azure Monitor metrics and logs
Activity logs (who did what, when)
Cost and billing data

Not collected:

Application data from databases
File contents from storage accounts
Secret values from Key Vault
Customer data from your applications

Azure Integration Setup Guide

On this page