Self-Hosted Runners (Feature Guide)
Run Controlinfra scans in your own infrastructure for enhanced security and unlimited scans.
Why Self-Hosted Runners?
| Benefit | Description |
|---|---|
| Security | Cloud credentials (AWS, Azure, GCP) never leave your network |
| Compliance | Meet regulatory requirements (SOC2, HIPAA, PCI) |
| Unlimited Scans | No quota limits |
| Network Access | Scan private resources |
| Custom Environment | Your Terraform version, custom providers |
Architecture
Cloud Runner (Default)
┌─────────────────────────────────────────────────────────┐
│ Controlinfra Cloud │
│ ┌─────────────┐ ┌───────────────────────────────┐ │
│ │ Cloud │ │ │ │
│ │ Runner │───▶│ Your AWS Resources │ │
│ │ │ │ │ │
│ └─────────────┘ └───────────────────────────────┘ │
│ │ │
│ AWS Credentials │
│ stored here │
└─────────────────────────────────────────────────────────┘Self-Hosted Runner
┌─────────────────────────────────────────────────────────┐
│ Your Infrastructure │
│ ┌─────────────┐ ┌───────────────────────────────┐ │
│ │ Self-Hosted │ │ │ │
│ │ Runner │───▶│ Your AWS Resources │ │
│ │ │ │ │ │
│ └──────┬──────┘ └───────────────────────────────┘ │
│ │ │
│ IAM Role │
│ (no keys) │
└─────────┼───────────────────────────────────────────────┘
│ Results only
▼
┌─────────────────────────────────────────────────────────┐
│ Controlinfra Cloud │
│ • Dashboard │
│ • AI Analysis │
│ • Notifications │
└─────────────────────────────────────────────────────────┘Getting Started
For detailed setup instructions, see: Self-Hosted Runners Setup Guide
Quick Overview
- Create IAM Role with
ReadOnlyAccess+ Terraform state S3 permissions - Launch EC2 Instance with the IAM role attached
- Install Dependencies (Terraform, Git)
- Register Runner in Controlinfra
- Install Agent and start
Required Permissions
The runner needs:
- ReadOnlyAccess (AWS managed policy) for drift detection
- S3 access to your Terraform state bucket (
s3:GetObject,s3:PutObject,s3:ListBucket) - DynamoDB access for state locking (if used)
See AWS Credentials Guide for detailed policy examples.
Supported Platforms
Self-hosted runners can be deployed on any of the three major cloud providers or on-premise:
| Platform | Deployment | Credentials |
|---|---|---|
| AWS | EC2 Instance with IAM Role | Instance Profile, AssumeRole, or Access Keys |
| Azure | Virtual Machine with Managed Identity | Azure CLI, Managed Identity, or Service Principal |
| GCP | Compute Instance with Service Account | Application Default Credentials or Service Account Key |
| On-Premise | Any Linux/macOS server | Static credentials for target cloud provider |
Auto-Update
Runners support automatic updates driven by the heartbeat mechanism:
- On each heartbeat, the runner checks for script updates from the Controlinfra API
- When an update is available, the runner downloads and applies the new version automatically
- A job lock safety mechanism ensures updates never interrupt an in-progress scan -- the update waits until the current job completes
- No manual intervention required; runners stay current with the latest features and fixes
Runner Features
Multiple Runners
Run multiple runners for:
- High Availability: Redundant scanning
- Environment Isolation: Separate prod/staging
- Geographic Distribution: Multi-region
┌─────────────────────────────────────────────────────────┐
│ Controlinfra Cloud │
└───────────────────────┬─────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Runner: prod │ │ Runner: staging│ │ Runner: eu │
│ us-east-1 │ │ us-east-1 │ │ eu-west-1 │
└───────────────┘ └───────────────┘ └───────────────┘Runner Labels
Tag runners to route scans appropriately:
yaml
Runner: prod-runner
Labels:
- production
- us-east-1
- high-security
Runner: staging-runner
Labels:
- staging
- us-east-1Then in repository settings:
yaml
Repository: production-infra
Runner: Self-hosted
Labels: production, us-east-1Auto-Selection
Controlinfra automatically selects the best runner:
- Matches labels if specified
- Chooses least busy runner
- Falls back to cloud runner if none available
Runner Management
Dashboard
View all runners in Settings → Runners:
┌─────────────────────────────────────────────────────────┐
│ Self-Hosted Runners │
├─────────────────────────────────────────────────────────┤
│ ● prod-runner │ Online │ us-east-1 │ 5 min ago │
│ ● staging-runner │ Online │ us-east-1 │ 2 min ago │
│ ○ backup-runner │ Offline│ us-west-2 │ 3 hrs ago │
├─────────────────────────────────────────────────────────┤
│ [+ Add Runner] │
└─────────────────────────────────────────────────────────┘Runner States
| State | Icon | Description |
|---|---|---|
| Online | 🟢 | Ready to accept scans |
| Busy | 🟡 | Currently running a scan |
| Offline | 🔴 | Not connected |
| Error | ⚠️ | Error state, needs attention |
Actions
| Action | Description |
|---|---|
| View Logs | See runner activity |
| Edit Labels | Update routing labels |
| Regenerate Token | New authentication token |
| Remove | Delete runner registration |
Authentication Methods
Self-hosted runners unlock authentication options that aren't available with the cloud runner — anything that requires the scanner to run inside your cloud account (Instance Profile, Managed Identity, Workload Identity) is only usable from a self-hosted runner.
| Method | Description | Best For |
|---|---|---|
| Instance Profile (AWS) | Use the runner's EC2 IAM role directly | Single AWS account setups |
| Assume Role (AWS) | Runner assumes a different IAM role | Cross-account, multi-tenant |
| Access Keys (AWS) | Traditional access keys (also works with cloud) | Quick setup |
| Managed Identity (Azure) | Use the VM's assigned identity | Single Azure subscription |
| Service Principal (Azure) | Azure AD app credentials | Cross-subscription |
| Application Default Credentials (GCP) | Use the instance's service account | Single GCP project |
| Service Account Key (GCP) | JSON key file for a GCP service account | Cross-project |
Trust requirements per method
For who Controlinfra authenticates as, what (if anything) needs to be trusted on Controlinfra's side, and which methods require a self-hosted runner, see the canonical "Trust requirements at a glance" tables:
Recommended: Instance Profile or Assume Role
For production environments, avoid storing access keys. Instance Profile and Assume Role provide:
- No credentials to rotate
- Better audit trails
- Temporary, auto-expiring credentials
For detailed setup instructions, see AWS Authentication Guide.
Security Considerations
No Credential Exposure
With self-hosted runners:
- Cloud credentials (AWS, Azure, GCP) stay in your network
- Use IAM roles, Managed Identities, or Service Accounts instead of static keys
- Controlinfra only receives scan results
Network Security
Recommended setup:
- Runner in private subnet
- NAT Gateway for outbound
- No inbound access required
- Security group: outbound HTTPS only
Audit Trail
All runner activity is logged:
- Scan requests
- Results uploaded
- Errors and failures
Performance
Scan Speed
Self-hosted runners can be faster:
- Direct network access to AWS
- No credential exchange latency
- Configurable instance size
Scaling
For high scan volume:
yaml
# Multiple runners share load
prod-runner-1 (labels: production)
prod-runner-2 (labels: production)
prod-runner-3 (labels: production)Resource Requirements
| Workload | Instance Type | Notes |
|---|---|---|
| Light | t3.small | Few scans/day |
| Medium | t3.medium | Regular scans |
| Heavy | t3.large+ | Many concurrent scans |
Troubleshooting
Runner Won't Connect
- Check network connectivity:bash
curl https://api.Controlinfra.com/health - Verify token is correct
- Check firewall rules
Scans Failing
- Check Terraform is installed
- Verify IAM permissions
- Review runner logs
Runner Goes Offline
- Check EC2 instance status
- Verify runner service is running
- Check for resource exhaustion
Cost Optimization
EC2 Costs
- Use Spot Instances for non-critical scans
- Right-size based on workload
- Use Reserved Instances for steady usage
Comparison
| Approach | Pros | Cons |
|---|---|---|
| Cloud Runner | No infrastructure | Quota limits |
| Self-Hosted | Unlimited, secure | EC2 costs |
Next Steps
- Setup Guide - Detailed installation
- AWS Credentials - IAM configuration
- Scheduling - Automate scans