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 | AWS credentials 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 read permissions
- Launch EC2 Instance with the IAM role
- Install Dependencies (Terraform, Git)
- Register Runner in Controlinfra
- Install Agent and start
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 |
Security Considerations
No Credential Exposure
With self-hosted runners:
- AWS credentials stay in your VPC
- Use IAM roles instead of access 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