Manage AI Governance with Terraform & IaC

Infrastructure-as-code (IaC) brings reproducibility and auditability to your AI governance deployment. This guide covers Terraform patterns for managing Keeptrusts gateways, configurations, and multi-environment promotion.

Use this page when

• You want to manage Keeptrusts configurations, gateways, and webhooks as Terraform resources.
• You need multi-environment promotion (dev → staging → production) with Terraform workspaces.
• You are implementing drift detection to alert when deployed configs diverge from repository state.
• You want to combine Keeptrusts resources with cloud infrastructure (AWS, GCP, Azure) in a single plan.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Architecture overview

Terraform workspace
  → keeptrusts_configuration resource (policy YAML)
  → keeptrusts_gateway resource (gateway instance)
  → keeptrusts_webhook resource (event forwarding)
  → cloud provider resources (compute, networking, storage)
  → state stored in remote backend (S3, GCS, Terraform Cloud)

All Keeptrusts resources are managed declaratively alongside the cloud infrastructure they depend on.

Prerequisites

• Terraform 1.5+
• Keeptrusts API key with admin permissions
• Remote state backend configured (S3, GCS, or Terraform Cloud)

Provider configuration

terraform {
  required_providers {
    keeptrusts = {
      source  = "keeptrusts/keeptrusts"
      version = "~> 1.0"
    }
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  backend "s3" {
    bucket = "myorg-terraform-state"
    key    = "keeptrusts/terraform.tfstate"
    region = "us-east-1"
  }
}

provider "keeptrusts" {
  api_url = var.keeptrusts_api_url
  api_key = var.keeptrusts_api_key
}

Managing configurations

Define a policy configuration

resource "keeptrusts_configuration" "production" {
  name        = "production-policy"
  description = "Production AI governance policy"

  policy_yaml = file("${path.module}/policies/production.yaml")

  labels = {
    environment = "production"
    team        = "platform"
  }
}

Policy YAML as a template

Use Terraform's templatefile for environment-specific policies:

resource "keeptrusts_configuration" "main" {
  name = "${var.environment}-policy"

  policy_yaml = templatefile("${path.module}/policies/base-policy.yaml.tpl", {
    max_tokens        = var.max_tokens
    blocked_topics    = var.blocked_topics
    escalation_email  = var.escalation_email
    retention_hours   = var.retention_hours
  })
}

Gateway deployment

ECS-based gateway

resource "aws_ecs_task_definition" "gateway" {
  family                   = "keeptrusts-gateway-${var.environment}"
  requires_compatibilities = ["FARGATE"]
  network_mode             = "awsvpc"
  cpu                      = 512
  memory                   = 1024

  container_definitions = jsonencode([{
    name  = "kt-gateway"
    image = "keeptrusts/gateway:${var.kt_version}"
    command = ["gateway", "run", "--listen", "0.0.0.0:41002", "--policy-config", "/etc/keeptrusts/policy-config.yaml"]
    portMappings = [{
      containerPort = 41002
      protocol      = "tcp"
    }]
    environment = [
      { name = "KEEPTRUSTS_API_URL", value = var.keeptrusts_api_url },
    ]
    secrets = [
      { name = "KEEPTRUSTS_API_TOKEN", valueFrom = aws_secretsmanager_secret.kt_api_key.arn },
    ]
    healthCheck = {
      command     = ["CMD-SHELL", "curl -f http://localhost:41002/health || exit 1"]
      interval    = 30
      timeout     = 5
      retries     = 3
      startPeriod = 10
    }
    logConfiguration = {
      logDriver = "awslogs"
      options = {
        "awslogs-group"         = aws_cloudwatch_log_group.gateway.name
        "awslogs-region"        = var.aws_region
        "awslogs-stream-prefix" = "gateway"
      }
    }
  }])
}

Webhook management

resource "keeptrusts_webhook" "slack_alerts" {
  url          = var.slack_webhook_url
  description  = "Slack alerts for policy violations"
  event_types  = ["event.blocked", "escalation.created"]
  active       = true
}

resource "keeptrusts_webhook" "siem_forwarder" {
  url          = var.siem_endpoint
  description  = "Forward all events to SIEM"
  event_types  = ["event.*"]
  active       = true
}

Multi-environment promotion

Workspace-per-environment

environments/
  ├── dev/
  │   ├── main.tf
  │   ├── terraform.tfvars
  │   └── policies/
  ├── staging/
  │   ├── main.tf
  │   ├── terraform.tfvars
  │   └── policies/
  └── production/
      ├── main.tf
      ├── terraform.tfvars
      └── policies/

Shared module pattern

# modules/keeptrusts-stack/main.tf
variable "environment" {}
variable "keeptrusts_api_url" {}
variable "keeptrusts_api_key" { sensitive = true }
variable "policy_path" {}

resource "keeptrusts_configuration" "main" {
  name        = "${var.environment}-policy"
  policy_yaml = file(var.policy_path)
}

# environments/production/main.tf
module "keeptrusts" {
  source             = "../../modules/keeptrusts-stack"
  environment        = "production"
  keeptrusts_api_url = var.keeptrusts_api_url
  keeptrusts_api_key = var.keeptrusts_api_key
  policy_path        = "${path.module}/policies/production.yaml"
}

Drift detection

Detect when manual console changes diverge from Terraform state:

# Run plan to detect drift
terraform plan -detailed-exitcode

# Exit code 0 = no changes, 1 = error, 2 = changes detected

Automate drift detection in CI:

# .github/workflows/drift-detection.yml
name: Keeptrusts Drift Detection
on:
  schedule:
    - cron: '0 */6 * * *'

jobs:
  detect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - name: Terraform Plan
        env:
          TF_VAR_keeptrusts_api_key: ${{ secrets.KEEPTRUSTS_API_TOKEN }}
        run: |
          terraform init
          terraform plan -detailed-exitcode
        continue-on-error: true
      - name: Alert on drift
        if: steps.plan.outcome == 'failure'
        run: |
          curl -X POST "$SLACK_WEBHOOK" \
            -d '{"text":"⚠️ Keeptrusts config drift detected. Run terraform apply to reconcile."}'

State management best practices

Practice	Recommendation
State backend	Use remote backend (S3 + DynamoDB lock, GCS, Terraform Cloud)
State locking	Always enable to prevent concurrent modifications
Sensitive values	Mark API keys as sensitive = true in variables
Import existing	Use terraform import keeptrusts_configuration.main <config-id>
State isolation	Separate state files per environment

Validating with kt CLI

Combine Terraform-managed resources with CLI validation:

# After terraform apply, validate the deployed config
kt policy lint --file policies/production.yaml

# Tail events to confirm the gateway is active
kt events tail --limit 10 --format json

# Export events for audit
kt export create --format csv --window 24h

Troubleshooting

Issue	Cause	Fix
Provider authentication fails	Invalid or expired API key	Rotate key and update TF_VAR_keeptrusts_api_key
Drift detected on every plan	Computed fields not in state	Add lifecycle { ignore_changes = [...] } for server-set fields
Import fails with 404	Wrong resource ID	Use /v1/configurations API to look up the correct ID
State lock timeout	Previous run did not release lock	Force unlock: terraform force-unlock <lock-id>

For AI systems

• Canonical terms: Keeptrusts Terraform provider (keeptrusts/keeptrusts), keeptrusts_configuration, keeptrusts_gateway, keeptrusts_webhook, templatefile, drift detection, remote state.
• Key config: Provider api_url and api_key, policy_yaml = file(...), lifecycle { ignore_changes } for server-set fields.
• CLI commands: terraform plan, terraform apply, terraform import, kt policy lint, kt events tail.
• Best next pages: Kubernetes deployment, CI/CD pipeline, AWS deployment.

For engineers

• Prerequisites: Terraform 1.5+, Keeptrusts API key with admin permissions, remote state backend (S3, GCS, or Terraform Cloud).
• Validate: terraform plan shows expected resource changes, kt policy lint passes on the YAML file Terraform references, kt events tail after apply.
• State: Always use remote backend with locking (DynamoDB for S3, native for Terraform Cloud) to prevent concurrent modifications.
• Import existing: terraform import keeptrusts_configuration.main <config-id> to bring existing resources under Terraform management.

For leaders

• Reproducibility: Every environment is created from the same code — no manual console clicks, no undocumented changes.
• Audit trail: Terraform state + Git history provide a complete record of who changed what, when, and why.
• Drift detection: Scheduled terraform plan alerts when production diverges from the declared state, preventing configuration sprawl.
• Multi-environment consistency: Use variables and workspaces to promote the same governance policies through dev, staging, and production.

Next steps

• Deploy on Kubernetes for container orchestration
• Integrate into CI/CD for automated plan and apply
• Deploy on AWS for cloud-native infrastructure