Terraform Provider

Manage a11ops resources as code

The a11ops Terraform provider enables you to manage workspaces, integrations, and configurations as code. Perfect for GitOps workflows and infrastructure automation.

Installation

Configure the Provider

Add the a11ops provider to your Terraform configuration:

terraform {
  required_providers {
    a11ops = {
      source  = "a11ops/a11ops"
      version = "~> 1.0"
    }
  }
}

# Configure the a11ops Provider
provider "a11ops" {
  api_key = var.a11ops_api_key
  # Optional: Override default API endpoint
  # api_url = "https://api.a11ops.com"
}

Authentication

Set your API key as an environment variable:

# Set via environment variable (recommended)
export TF_VAR_a11ops_api_key="your-api-key-here"

# Or define in terraform.tfvars (don't commit!)
a11ops_api_key = "your-api-key-here"

Available Resources

Workspace Resource

Create and manage a11ops workspaces:

resource "a11ops_workspace" "production" {
  name        = "Production"
  description = "Production environment alerts"
  
  settings = {
    alert_retention_days = 30
    timezone            = "America/New_York"
  }
  
  tags = {
    environment = "production"
    managed_by  = "terraform"
  }
}

# Output the workspace API key
output "production_api_key" {
  value     = a11ops_workspace.production.api_key
  sensitive = true
}

Integration Resource

Configure webhook integrations:

resource "a11ops_integration" "prometheus" {
  workspace_id = a11ops_workspace.production.id
  name         = "Prometheus AlertManager"
  type         = "prometheus"
  
  config = {
    # Integration-specific configuration
    severity_mapping = {
      critical = "critical"
      warning  = "medium"
      info     = "low"
    }
  }
}

# Use the webhook URL in other resources
output "prometheus_webhook_url" {
  value = a11ops_integration.prometheus.webhook_url
}

Team Member Resource

Manage workspace team members:

resource "a11ops_team_member" "oncall_engineer" {
  workspace_id = a11ops_workspace.production.id
  email        = "oncall@company.com"
  role         = "admin"
  
  notification_preferences = {
    critical_alerts = true
    high_alerts     = true
    medium_alerts   = false
    low_alerts      = false
  }
}

# Add multiple team members
variable "team_members" {
  type = list(object({
    email = string
    role  = string
  }))
  default = [
    { email = "alice@company.com", role = "admin" },
    { email = "bob@company.com", role = "member" },
    { email = "charlie@company.com", role = "viewer" }
  ]
}

resource "a11ops_team_member" "team" {
  for_each = { for member in var.team_members : member.email => member }
  
  workspace_id = a11ops_workspace.production.id
  email        = each.value.email
  role         = each.value.role
}

Alert Rules Resource

Configure alert routing and filtering rules:

resource "a11ops_alert_rule" "critical_escalation" {
  workspace_id = a11ops_workspace.production.id
  name         = "Critical Alert Escalation"
  enabled      = true
  
  conditions = {
    severity = ["critical"]
    tags = {
      environment = "production"
    }
  }
  
  actions = {
    escalate_after_minutes = 5
    notify_slack_channel   = "#incidents"
    create_incident        = true
  }
}

resource "a11ops_alert_rule" "business_hours" {
  workspace_id = a11ops_workspace.production.id
  name         = "Business Hours Routing"
  
  conditions = {
    severity = ["low", "medium"]
    time_range = {
      days  = ["mon", "tue", "wed", "thu", "fri"]
      start = "09:00"
      end   = "17:00"
      timezone = "America/New_York"
    }
  }
  
  actions = {
    notify_email = "daytime-oncall@company.com"
  }
}

Complete Example

Here's a complete example setting up a11ops for a production environment:

# main.tf
terraform {
  required_providers {
    a11ops = {
      source  = "a11ops/a11ops"
      version = "~> 1.0"
    }
  }
}

provider "a11ops" {
  api_key = var.a11ops_api_key
}

# Variables
variable "a11ops_api_key" {
  description = "API key for a11ops"
  type        = string
  sensitive   = true
}

variable "environment" {
  description = "Environment name"
  type        = string
  default     = "production"
}

# Create workspace
resource "a11ops_workspace" "main" {
  name        = "${var.environment} Alerts"
  description = "Alert management for ${var.environment}"
  
  settings = {
    alert_retention_days = var.environment == "production" ? 90 : 30
    timezone            = "UTC"
  }
}

# Add team members
locals {
  team_members = {
    "john@company.com"  = "admin"
    "jane@company.com"  = "admin"
    "ops@company.com"   = "member"
    "view@company.com"  = "viewer"
  }
}

resource "a11ops_team_member" "team" {
  for_each = local.team_members
  
  workspace_id = a11ops_workspace.main.id
  email        = each.key
  role         = each.value
}

# Configure Prometheus integration
resource "a11ops_integration" "prometheus" {
  workspace_id = a11ops_workspace.main.id
  name         = "Prometheus - ${var.environment}"
  type         = "prometheus"
}

# Configure Grafana integration
resource "a11ops_integration" "grafana" {
  workspace_id = a11ops_workspace.main.id
  name         = "Grafana - ${var.environment}"
  type         = "grafana"
}

# Alert routing rules
resource "a11ops_alert_rule" "page_critical" {
  workspace_id = a11ops_workspace.main.id
  name         = "Page for Critical Alerts"
  
  conditions = {
    severity = ["critical"]
  }
  
  actions = {
    page_oncall = true
    escalate_after_minutes = 10
  }
}

# Outputs for use in other configurations
output "workspace_id" {
  value = a11ops_workspace.main.id
}

output "workspace_api_key" {
  value     = a11ops_workspace.main.api_key
  sensitive = true
}

output "webhook_urls" {
  value = {
    prometheus = a11ops_integration.prometheus.webhook_url
    grafana    = a11ops_integration.grafana.webhook_url
  }
  sensitive = true
}

Best Practices

State Management

  • Use remote state backend (S3, Terraform Cloud) for team collaboration
  • Enable state locking to prevent concurrent modifications
  • Encrypt state files as they contain sensitive API keys

Secret Management

  • Never commit API keys to version control
  • Use environment variables or secret management tools
  • Mark sensitive outputs with sensitive = true

Module Organization

  • Create reusable modules for common configurations
  • Use workspace-specific variable files
  • Implement proper naming conventions

Importing Existing Resources

Import existing a11ops resources into Terraform:

# Import an existing workspace
terraform import a11ops_workspace.production workspace_123abc

# Import an existing integration
terraform import a11ops_integration.prometheus integration_456def

# Import a team member
terraform import a11ops_team_member.john "workspace_123abc/john@company.com"

CI/CD Integration

GitHub Actions Example

name: Deploy a11ops Infrastructure

on:
  push:
    branches: [main]
    paths:
      - 'terraform/a11ops/**'

jobs:
  terraform:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.0
      
      - name: Terraform Init
        run: terraform init
        working-directory: ./terraform/a11ops
      
      - name: Terraform Plan
        run: terraform plan -out=tfplan
        working-directory: ./terraform/a11ops
        env:
          TF_VAR_a11ops_api_key: ${{ secrets.A11OPS_API_KEY }}
      
      - name: Terraform Apply
        if: github.ref == 'refs/heads/main'
        run: terraform apply -auto-approve tfplan
        working-directory: ./terraform/a11ops
        env:
          TF_VAR_a11ops_api_key: ${{ secrets.A11OPS_API_KEY }}

Start Managing Infrastructure as Code

Use Terraform to version control and automate your a11ops configuration.

Terraform RegistryMore Integrations