Actions Runner Controller

Architecture Overview

Actions Runner Controller (ARC) operates as a Kubernetes operator, managing the lifecycle of GitHub Actions runners within a cluster. It consists of several key components:

1. Controller Manager: Orchestrates runner deployments and scaling
2. Runner Pods: Ephemeral pods that execute GitHub Actions jobs
3. Webhook Server: Handles GitHub webhook events for autoscaling (Summerwind variant, legacy)
4. Runner Scale Set Controller: Manages runner scale sets (Runner Scale Set variant, since ~2022)

Summerwind vs Runner Scale Set Variants

Summerwind Variant

• Uses webhook-based autoscaling
• Simpler setup, suitable for smaller deployments
• Requires exposing webhook endpoint to GitHub
• Can be more responsive to sudden job spikes

Runner Scale Set Variant

• Uses polling-based autoscaling
• More scalable, suitable for large enterprise deployments
• No need to expose webhook endpoint
• Potentially higher latency for scaling events
• Supports advanced features like job assignment and runner groups

Requirements

1. Kubernetes Cluster:

   • Must support CustomResourceDefinitions (CRDs)

2. Custom Runner Images:

   • Default images are minimal; you’ll need to build custom images for most workflows
   • Consider using tools like Packer or Docker to create images with pre-installed dependencies

3. Docker-in-Docker Limitations:

   • Running Docker inside runner pods can be challenging
   • Options: a. Use privileged containers (security implications) b. Implement alternative container runtimes (e.g., Kaniko) c. Use host Docker socket (potential resource conflicts)

4. Networking:

   • Outbound internet access for runners to communicate with GitHub
   • Inbound access to webhook server (Summerwind variant only)

5. RBAC:

   • Proper permissions for the controller to manage runner pods and related resources

6. Storage:

   • Persistent volume claims for caching and workspace storage (optional but recommended)

7. Scaling Considerations:

   • Set appropriate resource requests and limits
   • Configure horizontal pod autoscaling for the controller itself

8. Monitoring and Logging:

   • Implement Prometheus metrics collection
   • Set up centralized logging for troubleshooting

When choosing between Summerwind and Runner Scale Set variants, consider your scale, security requirements, and desired level of control over runner management. The Runner Scale Set variant is generally recommended for newer deployments due to its enhanced scalability and feature set.