README.mdβ’62.1 kB
# ARC Config MCP Server
> **π AI-Powered [GitHub Actions Runner Controller](https://docs.github.com/en/actions/concepts/runners/actions-runner-controller) Management**
>
> A comprehensive TypeScript MCP (Model Context Protocol) server that transforms complex ARC operations into conversational AI interactions. Deploy, monitor, and manage GitHub Actions runners with natural language commands.
> **π― QUICK START**: Add to your MCP client: `ghcr.io/tsviz/arc-config-mcp:latest` β Ask AI: *"Install ARC in my cluster"* β Done! β¨
[](https://github.com/tsviz/arc-config-mcp/releases)
[](https://ghcr.io/tsviz/arc-config-mcp)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
**π Quick Links**: [Installation](#-quick-start) β’ [π₯ Healthcare Demo](docs/HEALTHCARE_DEMO_WORKFLOW.md) β’ [π¬ Demo Guide](docs/DEMO_QUICK_REFERENCE.md) β’ [Policy Validation Guide](docs/POLICY_VALIDATION_GUIDE.md) β’ [Policy Rule Integration](docs/POLICY_RULE_INTEGRATION.md) β’ [Hybrid Workflows](docs/HYBRID_WORKFLOW_CLARITY.md) β’ [Tool Catalog](#%EF%B8%8F-complete-tool-catalog) β’ [Roadmap](ROADMAP.md) β’ [Contributing](#-contributing)
## π― What is ARC Config MCP Server?
ARC Config MCP Server is an enterprise-grade automation tool that bridges the gap between complex Kubernetes-based GitHub Actions runner management and intuitive AI-powered operations. Instead of memorizing kubectl commands and YAML configurations, simply tell the AI what you want to accomplish.
**π NOW SUPPORTS ARC 0.13.0** with advanced container modes, dual-stack networking, Azure Key Vault integration, and OpenShift support!
## π Key Features
### π€ **Natural Language Operations**
Transform complex ARC tasks into simple conversations:
- *"Install ARC with container mode optimization"*
- *"Scale runners to handle 50 concurrent jobs"*
- *"Set up dual-stack networking for IPv6 support"*
- *"Configure Azure Key Vault for secure secret management"*
### β‘ **ARC 0.13.0 Enhancements**
- **π₯ Container Mode**: `kubernetes-novolume` eliminates ReadWriteMany storage requirements
- **π Dual-Stack Networking**: IPv4/IPv6 support with automatic fallback
- **π Azure Key Vault Integration**: Secure secret management without workflow exposure
- **π’ OpenShift Support**: Enterprise-grade deployment with Security Context Constraints
- **π Enhanced Metrics**: New `workflow_name` and `target` labels for better monitoring
### π **Enterprise-Ready Capabilities**
- **Intelligent Installation**: Zero-configuration ARC deployment with smart defaults
- **Real-time Monitoring**: Live status dashboards and proactive health monitoring
- **Enterprise Security**: Built-in policy validation and compliance enforcement with 20+ security rules
- **π Guided Workflows**: Auto-fix tool now prompts for drift detection to maintain GitOps sync
- **Automated Policy Remediation**: Auto-fix feature generates corrected configs for 6+ common violations
- **Compliance Reporting**: Generate SOC2/enterprise compliance reports with scoring and recommendations
- **Cost Intelligence**: Automatic scaling and resource optimization
- **Self-Healing**: Automated troubleshooting and remediation
- **Platform Support**: Kubernetes, OpenShift, AKS, EKS, GKE compatibility
## π Quick Start
### π― Step 1: Connect to MCP Client
**Use with AI assistants like GitHub Copilot in VS Code**
Add this configuration to your MCP client settings (e.g., `~/.mcp.json` or VS Code settings):
```json
{
"mcpServers": {
"arc-config": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "${HOME}/.kube:/home/node/.kube:ro",
"-v", "/path/to/your/project/configs:/app/configs",
"-e", "GITHUB_TOKEN",
"ghcr.io/tsviz/arc-config-mcp:latest"
]
}
}
}
```
> **π‘ Configuration Path**: Replace `/path/to/your/project/configs` with your actual project path (e.g., `/Users/username/projects/my-arc-project/configs`)
### π― Step 2: Choose Your Workflow
The MCP server supports **three deployment workflows** to match your team's needs:
| Workflow | Best For | Config Files | Auto-Apply | Version Control |
|----------|----------|--------------|------------|-----------------|
| **Recommended** (Default) | Most teams | β
Saved | β Manual* | β
Yes |
| **Direct Apply** | Quick testing | β Not saved | β
Automatic | β No |
| **Full GitOps** | Enterprise teams | β
Saved | β CI/CD handles it | β
Yes + CI/CD |
*\*You review the generated config, then tell the AI to apply it (e.g., "apply it" or "deploy it")*
**π‘ Choosing a workflow:** The default (Recommended) balances safety and convenience. For quick experiments, use Direct Apply. For production deployments, stick with Recommended or Full GitOps to maintain audit trails and enable rollbacks.
### π― Step 3: Start Using Natural Language
**β¨ That's it!** Talk to your AI assistant to manage ARC:
```text
"Install ARC controller in my cluster"
"Deploy 10-20 autoscaling runners for my organization"
"Show me the status of my runners"
"Scale up to handle more load"
```
> **π Learn More**: See [Understanding Workflows](#-understanding-workflows) below to choose the best approach for your team.
## π¬ Live Demo: Healthcare Compliance in 5 Minutes
Want to see the power of AI-driven ARC management? Check out our **[Healthcare Demo Workflow](docs/HEALTHCARE_DEMO_WORKFLOW.md)** where we:
1. **Deploy 20-40 auto-scaling runners** with a single command
2. **Generate HIPAA-compliant policies** automatically
3. **Auto-fix security violations** with AI remediation
4. **Ensure zero configuration drift** with GitOps validation
**Final Result**: Production-ready healthcare environment with 85% compliance score!
```text
User: "Deploy 20-40 runners"
β β
ARC installed, runners deployed with auto-scaling
User: "Generate arc policies for healthcare production"
β β
HIPAA/SOC2/ISO27001 policies created
User: "Auto-fix any policy violations"
β β
55.6% β 72.2% compliance improvement
User: "Run drift detection"
β β
Drift detected & auto-fixed (configs regenerated)
```
π― **Perfect for demos, POCs, and training sessions!**
π **[Full Demo Guide](docs/DEMO_QUICK_REFERENCE.md)** β’ **[Technical Workflow](docs/HEALTHCARE_DEMO_WORKFLOW.md)**
---
<a id="understanding-workflows"></a>
## π Understanding Workflows
The MCP server offers three ways to deploy and manage ARC, each suited for different needs:
### π― Recommended Workflow (Default)
**Perfect for most teams** - Combines AI convenience with version control best practices.
**How it works:**
1. AI generates configuration files in `configs/` directory
2. You review the YAML files (they're in your project!)
3. Apply using AI commands: *"Apply the runner configuration"*
4. Changes are tracked in Git for audit trail
**Benefits:**
- β
Version control for all infrastructure
- β
Review changes before applying
- β
Easy rollback via Git
- β
Team collaboration via Pull Requests
- β
Still simple to use with AI
**Example:**
```text
You: "Deploy 20-40 runners for my-org"
AI: β
Created configs/runner-sets/my-org-runners.yaml
π Review the file, then say "apply it" when ready
You: "Apply it"
AI: β
Applied to cluster! 20 runners starting...
```
> **π Detailed Guide**: [Workflow Guide](docs/WORKFLOW_GUIDE.md) | [Visual Guide](docs/HYBRID_WORKFLOW_VISUAL_GUIDE.md)
### β‘ Direct Apply Workflow
**Best for quick testing** - Deploy immediately without saving configuration files.
**How it works:**
1. AI deploys directly to cluster
2. No config files created
3. Fastest approach
**Tradeoffs:**
- β No version control
- β No audit trail
- β Can't review before applying
- β
Fastest for testing
**Example:**
```text
You: "Install ARC controller with direct mode"
AI: β
Installing directly to cluster...
β
Done in 45 seconds!
```
### π’ Full GitOps Workflow
**Best for enterprise teams** - Integrates with ArgoCD, Flux, or CI/CD pipelines.
**How it works:**
1. AI generates configuration files only
2. You commit to Git
3. Your GitOps tool (ArgoCD/Flux) applies automatically
4. Never applies directly to cluster
**Benefits:**
- β
Full GitOps compliance
- β
Automated deployments via CI/CD
- β
Policy enforcement before apply
- β
Complete audit trail
**Example:**
```text
You: "Generate runner config for my-org in gitops mode"
AI: β
Created configs/runner-sets/my-org-runners.yaml
π Commit to Git - your GitOps tool will handle deployment
```
> **π GitOps Guide**: [Setting up ArgoCD/Flux](docs/WORKFLOW_GUIDE.md#gitops-integration)
---
## π οΈ Alternative Installation Methods
### π³ Docker Standalone
```bash
# Pull and run the latest version
docker run -p 3000:3000 ghcr.io/tsviz/arc-config-mcp:latest
# With custom configuration
docker run -p 3000:3000 \
-e GITHUB_TOKEN=your_token \
-e KUBECONFIG_PATH=/kubeconfig \
-v ~/.kube/config:/kubeconfig:ro \
ghcr.io/tsviz/arc-config-mcp:latest
```
### π οΈ Local Development
```bash
git clone https://github.com/tsviz/arc-config-mcp.git
cd arc-config-mcp
npm install
npm run build
npm start -- --stdio # For MCP protocol connection
```
---
## π Natural Language Examples
Transform complex ARC operations into simple conversations:
### π₯ ARC 0.13.0 Enhanced Examples
```text
π§ "Install ARC with the new container mode to eliminate storage issues"
π€ β
Installing ARC controller with kubernetes-novolume container mode...
π¦ Helm chart: actions-runner-controller v0.13.0
π₯ Container mode: kubernetes-novolume (no RWX storage needed!)
π Enhanced metrics: workflow_name and target labels enabled
π Security: JIT token secure mode enabled
β±οΈ Installation completed in 52 seconds
π§ "Set up dual-stack networking for IPv6 support"
π€ β
Configuring dual-stack networking for ARC runners...
π IPv4/IPv6: Dual-stack support enabled
π Fallback: IPv4 only if IPv6 unavailable
π‘οΈ Network policies: Updated for dual-stack
π DNS config: Optimized for both protocols
β±οΈ Network configuration completed in 30 seconds
π§ "Configure Azure Key Vault integration for secure secrets"
π€ β
Setting up Azure Key Vault CSI integration...
π Key Vault: Connected to production vault
π« Workload Identity: Configured for secure access
π« Workflow context: Secrets isolated from workflows
π Secret Provider Class: Created and validated
β±οΈ Azure Key Vault integration completed in 75 seconds
π§ "Deploy runners optimized for OpenShift with enterprise security"
π€ β
Deploying OpenShift-optimized ARC runners...
π’ Platform: OpenShift Security Context Constraints applied
π€ Security: Non-root user with restricted capabilities
π·οΈ SELinux: Multi-Category Security labels configured
π Pod Security: Restricted standard enforced
β±οΈ OpenShift deployment completed in 95 seconds
```
### π‘ Traditional Examples
```text
π§ "Install ARC in my dev cluster with basic security settings"
π€ β
Installing ARC controller with development security profile...
π¦ Helm chart: actions-runner-controller v0.13.0
π Security: Basic validation enabled
π Namespace: arc-systems
β±οΈ Installation completed in 45 seconds
π§ "Scale my repo runners to handle the evening build rush"
π€ β
Analyzing current load and scaling runners...
π Current: 3 runners, Target: 8 runners
π Load factor: 85% β 45%
π° Cost impact: +$12/hour (estimated)
β±οΈ Scaling completed in 90 seconds
π§ "Show me why my runners keep failing"
π€ π Analyzing runner health and recent failures...
β Issue found: Insufficient CPU resources
π‘ Recommendation: Increase runner resource limits
π οΈ Auto-fix available: Update resource quotas
π Policy violation: Resource limits below minimum
π§ "Check ARC policies and fix what you can"
π€ β
Running policy validation and auto-remediation...
π Compliance Score: 55.6% (10/18 policies passing)
π§ Auto-fixing 3 violations (CPU limits, memory requests, labels)
π Generated: configs/runner-sets/my-runners-fixed.yaml
π‘ Manual fixes needed: 2 violations (see recommendations)
β±οΈ Auto-fix completed in 18 seconds
π§ "Validate policies and apply fixes to the cluster"
π€ β
Running policy validation with cluster remediation...
π Initial Compliance: 44.4% (8/18 policies passing)
π§ Applied 4 fixes to cluster (resources, security contexts)
π Saved audit trail: configs/runner-sets/production-runners-fixed.yaml
β
Final Compliance: 77.8% (14/18 policies passing)
β±οΈ Validation and remediation completed in 32 seconds
```
## ποΈ Architecture Overview
```
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β AI Client β β MCP Server β β Kubernetes β
β (Copilot) βββββΊβ (This Repo) βββββΊβ (ARC Runs) β
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β²
β
βββββββββββββββββββ
β GitHub API β
β (Runner Mgmt) β
βββββββββββββββββββ
```
### Components
- **Natural Language Processor**: Converts human intent to structured operations
- **ARC Policy Engine**: Validates configurations against 18 built-in enterprise policies
- **Configuration Manager**: GitOps-ready config generation with version control support
- **Kubernetes Orchestrator**: Manages cluster resources and deployments
- **GitHub Integration**: Handles runner registration and lifecycle
- **Monitoring Hub**: Tracks performance and health metrics
## π οΈ Complete Tool Catalog
> **π Full Documentation**: See [TOOLS.md](TOOLS.md) for comprehensive tool documentation with examples and parameters.
### π― Core Operations
| Tool | Purpose | Example Usage |
| ---------------------------- | -------------------------- | ---------------------------- |
| `arc_install_controller` | Deploy ARC to Kubernetes | Install with custom config |
| `arc_get_status` | Comprehensive health check | Monitor all components |
| `arc_scale_runners` | Horizontal runner scaling | Handle load spikes |
| `arc_manage_runners` | Full lifecycle management | Create/update/delete runners |
| `arc_cleanup_installation` | Safe ARC cleanup/uninstall | Remove ARC with AI guidance |
| `arc_analyze_cleanup_state` | Pre-cleanup analysis | Analyze before removing ARC |
> **π‘οΈ Safety Note**: Cleanup functionality is **disabled by default**. Set `CLEANUP_ARC=true` environment variable to enable. See [Cleanup Documentation](docs/CLEANUP_FUNCTIONALITY.md) for details.
### π Configuration Management Tools
Use these tools with the [Recommended Workflow](#-recommended-workflow-default) for version-controlled deployments.
| Tool | Purpose | Example Usage |
| ------------------------------ | ------------------------------ | --------------------------------- |
| `arc_install_controller_hybrid`| Install ARC with config files | Generate controller configuration |
| `arc_deploy_runners_hybrid` | Deploy runners with versioning | Generate and apply runner configs |
| `arc_apply_config` | Apply existing config files | Deploy from repository configs |
| `arc_list_configs` | List stored configurations | View all config files |
| `arc_detect_drift` | Compare config vs deployed | Find configuration drift |
### π€ AI-Powered Features
| Tool | Purpose | Example Usage |
| ------------------------------ | ------------------------ | ---------------------------- |
| `arc_process_natural_language` | Convert speech to action | "Scale up for deployment" |
### π Security & Compliance
| Tool | Purpose | Example Usage |
| -------------------------- | ------------------------------------ | ---------------------------- |
| `arc_validate_policies` | Validate & auto-fix policy violations (generates fixed configs in `configs/`)| Compliance reports, config-based remediation |
### ποΈ Legacy Tools
| Tool | Purpose | Status |
| -------------------------- | ------------------------ | ----------- |
| `deploy_github_runners` | Original deployment tool | Deprecated |
## πΊοΈ Roadmap & Future Tools
The following tools are planned for future releases to enhance ARC management capabilities:
### π Security & Compliance (High Priority)
| Tool | Purpose | Priority | Complexity |
| -------------------------- | ------------------------------------ | -------- | ---------- |
| `arc_audit_logs` | Security audit log analysis | High | Medium |
| `arc_manage_secrets` | Secret rotation and management | Medium | High |
| `arc_configure_networking` | Network policy management | Medium | Medium |
### π― Operations & Monitoring (Medium Priority)
| Tool | Purpose | Priority | Complexity |
| -------------------------- | -------------------------------------- | -------- | ---------- |
| `arc_troubleshoot_issues` | Automated diagnostics for common issues| High | High |
| `arc_optimize_costs` | Resource and cost optimization | Medium | Medium |
| `arc_generate_reports` | Operational reports and metrics | Medium | Low |
| `arc_performance_tuning` | Auto-tune runner performance settings | Low | High |
### π Advanced Features (Lower Priority)
| Tool | Purpose | Priority | Complexity |
| -------------------------- | -------------------------------------- | -------- | ---------- |
| `arc_backup_config` | Configuration backup and restore | Medium | Low |
| `arc_upgrade_components` | Automated ARC version upgrades | Medium | High |
| `arc_migrate_runners` | Migrate runners between clusters | Low | High |
| `arc_disaster_recovery` | DR planning and execution | Low | Very High |
> **π‘ Want to contribute?** These tools are tracked as GitHub issues. Check the [Issues](https://github.com/tsviz/arc-config-mcp/issues) page for details and implementation discussions.
## π Prerequisites & Requirements
### System Requirements
- **Node.js**: 18.0+ (LTS recommended)
- **Kubernetes**: 1.24+ (tested up to 1.30)
- **Memory**: 512MB+ for server
- **Storage**: 100MB for installation
### Kubernetes Permissions
The server requires these cluster permissions:
- **Namespaces**: List, create, watch
- **Deployments**: Full CRUD operations
- **Services**: Create, update, delete
- **ConfigMaps/Secrets**: Manage runner configurations
- **RBAC**: Create service accounts and roles
### GitHub Requirements
- **Personal Access Token** with scopes:
- `repo` (for repository access)
- `admin:org` (for organization runners)
- `workflow` (for Actions management)
- **Organization/Repository** admin permissions
- **GitHub Actions** enabled
## π§ Installation & Configuration
### Environment Configuration
Create a `.env` file with your settings:
```bash
# GitHub Configuration
GITHUB_TOKEN=ghp_your_personal_access_token
GITHUB_ORG=your-organization
GITHUB_REPO=your-repository
# Kubernetes Configuration
KUBECONFIG_PATH=/path/to/kubeconfig
ARC_NAMESPACE=arc-systems
RUNNER_NAMESPACE=arc-runners
# MCP Server Configuration
MCP_PORT=3000
LOG_LEVEL=info
ENABLE_METRICS=true
# Security Settings
ENABLE_POLICY_VALIDATION=true
SECURITY_PROFILE=standard # basic|standard|strict
AUTO_FIX_VIOLATIONS=false
CLEANUP_ARC=false # Enable ARC cleanup/uninstall functionality (disabled by default for safety)
# Performance Tuning
MAX_CONCURRENT_OPERATIONS=5
OPERATION_TIMEOUT=300
RETRY_ATTEMPTS=3
```
### VS Code + GitHub Copilot Integration
1. **Configure MCP Server** (already shown above):
The JSON configuration from the Quick Start section works directly with VS Code + GitHub Copilot.
2. **Enable MCP in GitHub Copilot**:
Add to your VS Code settings:
```json
{
"github.copilot.enable": {
"*": true,
"mcp": true
}
}
```
3. **Start using natural language commands** with GitHub Copilot to manage your ARC infrastructure!
### Production Deployment
#### Kubernetes Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: arc-config-mcp
namespace: mcp-system
spec:
replicas: 2
selector:
matchLabels:
app: arc-config-mcp
template:
metadata:
labels:
app: arc-config-mcp
spec:
containers:
- name: mcp-server
image: ghcr.io/tsviz/arc-config-mcp:latest
ports:
- containerPort: 3000
env:
- name: GITHUB_TOKEN
valueFrom:
secretKeyRef:
name: github-credentials
key: token
- name: LOG_LEVEL
value: "info"
resources:
requests:
memory: "256Mi"
cpu: "100m"
limits:
memory: "512Mi"
cpu: "500m"
```
#### Docker Compose
```yaml
version: '3.8'
services:
arc-mcp:
image: ghcr.io/tsviz/arc-config-mcp:latest
ports:
- "3000:3000"
environment:
- GITHUB_TOKEN=${GITHUB_TOKEN}
- LOG_LEVEL=info
volumes:
- ~/.kube/config:/app/.kube/config:ro
restart: unless-stopped
```
## π¨ Usage Patterns & Examples
### π₯ ARC 0.13.0 Advanced Patterns
#### 1. Container Mode Optimization
```text
π§ "Upgrade my existing ARC to use the new container mode"
π€ I'll migrate you to kubernetes-novolume container mode:
1οΈβ£ Analyzing current deployment...
π Current: kubernetes mode with PVC storage
π RWX storage usage: 15 GB across 8 runners
π° Storage cost: $45/month
2οΈβ£ Planning migration to kubernetes-novolume...
β‘ Benefits: No RWX storage dependency
π Performance: ~30% faster job startup
π° Cost savings: $45/month storage eliminated
π§ Lifecycle hooks: preStart/preStop configured
3οΈβ£ Executing migration...
π Creating new runner deployment with container mode
π¦ Adding workspace lifecycle hooks
π Rolling out updated configuration
π§Ή Cleaning up legacy PVC resources
β
Migration complete!
π― Container mode: kubernetes-novolume active
β‘ Job startup time: Reduced by 28 seconds
πΎ Ephemeral storage: 10Gi per runner
```
#### 2. Dual-Stack Networking Setup
```text
π§ "Configure my runners for IPv6 support"
π€ Setting up dual-stack networking for future-ready infrastructure:
1οΈβ£ Evaluating network requirements...
π Current: IPv4 only
π Target: IPv4/IPv6 dual-stack
π GitHub API: IPv6 endpoints available
2οΈβ£ Configuring dual-stack support...
π§ DNS policy: ClusterFirst with IPv6
π‘οΈ Network policies: Updated for dual protocols
π·οΈ Service configuration: Dual-stack enabled
π‘ Ingress: IPv4/IPv6 load balancing
3οΈβ£ Testing connectivity...
β
IPv4 GitHub API: Connected
β
IPv6 GitHub API: Connected
π Fallback mechanism: IPv4 verified
π Latency: IPv6 -12ms vs IPv4
β
Dual-stack networking active!
π Protocols: IPv4 + IPv6 with automatic fallback
π Performance: Optimized routing selection
π‘οΈ Security: Enhanced network isolation
```
#### 3. Azure Key Vault Integration
```text
π§ "Secure my secrets using Azure Key Vault instead of Kubernetes secrets"
π€ Implementing Azure Key Vault CSI integration:
1οΈβ£ Validating Azure setup...
π Key Vault: arc-secrets-prod detected
π€ Workload Identity: Configured for AKS
π« Service Principal: Permissions verified
π¦ CSI Driver: secrets-store-csi-driver v1.4.1
2οΈβ£ Creating SecretProviderClass...
π·οΈ Name: arc-azure-keyvault
π Secrets: github-token, webhook-secret
π‘οΈ Access: Workload Identity federation
π Mount path: /mnt/secrets
3οΈβ£ Updating runner deployment...
π¦ Volume: CSI secrets-store driver
π Security: No secrets in workflow context
π Rotation: Automatic on key vault update
π Monitoring: Secret access auditing
β
Azure Key Vault integration complete!
π Secrets: Managed externally in Azure
π« Context isolation: Secrets hidden from workflows
π Auto-rotation: 90-day lifecycle
π Audit trail: All access logged
```
### π‘ Traditional Deployment Patterns
#### 1. First-Time ARC Installation
```text
π§ "I need to set up GitHub Actions runners in my new cluster"
π€ I'll help you install ARC with best practices:
1οΈβ£ Checking cluster compatibility...
β
Kubernetes 1.28 detected
β
Sufficient resources available
β
RBAC permissions verified
2οΈβ£ Installing ARC controller...
π¦ Adding Actions Runner Controller Helm repository
βοΈ Configuring with security defaults
π Deploying to namespace: arc-systems
3οΈβ£ Setting up runner infrastructure...
π₯ Creating runner group: default-runners
π Configuring GitHub webhook authentication
π Enabling monitoring and metrics
β
Installation complete!
π Controller endpoint: https://arc.your-cluster.com
π Grafana dashboard: https://monitoring.your-cluster.com/arc
π Next steps: Configure your first runner set
```
### 2. Scaling for High Load
```text
π§ "Our deployment pipeline is slow, we need more runners during business hours"
π€ I'll set up intelligent scaling for your deployment pipeline:
π Current Analysis:
β’ 3 active runners
β’ 12 queued jobs
β’ Average wait time: 8 minutes
π― Optimization Plan:
β’ Scale to 8 runners immediately
β’ Configure auto-scaling: 3-15 runners
β’ Business hours boost: 9AM-6PM EST
β’ Weekend scale-down: 1-3 runners
βοΈ Implementing changes...
β
HorizontalPodAutoscaler configured
β
Schedule-based scaling rules applied
β
Cost optimization policies enabled
π° Cost Impact:
β’ Current: ~$180/month
β’ Optimized: ~$245/month (+36%)
β’ ROI: 2.5x faster deployments
```
### 3. Troubleshooting Runner Issues
```text
π§ "My runners keep dying and I don't know why"
π€ Let me analyze your runner health:
π Diagnostic Results:
β 3 runners crashed in last hour
β OOMKilled events detected
β CPU throttling at 95%
π― Root Cause: Resource constraints
β’ Memory limit: 2Gi (insufficient)
β’ CPU limit: 1000m (too low for builds)
β’ Recommended: 4Gi memory, 2000m CPU
π οΈ Auto-fix Available:
1. Update resource quotas
2. Configure memory overcommit protection
3. Add resource monitoring alerts
Would you like me to apply these fixes? [y/N]
```
### 4. Security Compliance Check
```text
π§ "Check if our ARC setup meets SOC2 requirements"
π€ Running comprehensive policy validation and compliance audit...
οΏ½ Analyzing ARC Resources:
β
Controller: Healthy and compliant
π RunnerScaleSets: 3 found
π Security Policies: 23 rules evaluated
π Compliance Report:
β
Security Policies: 18/20 passed (90%)
β οΈ Compliance Policies: 8/10 passed (80%)
β
Performance Policies: 5/5 passed (100%)
π΄ Critical Issues Found:
1. Privileged runner detected (arc-sec-002)
2. Missing resource limits (arc-perf-001)
π High Priority Issues:
1. GitHub token secret not configured (arc-sec-003)
2. Runner not scoped to repository (arc-comp-001)
π‘ Auto-Fix Available:
π§ 2 violations can be automatically fixed
π οΈ Remediation Plan:
1. Remove privileged flag from runner pods
2. Add resource limits (CPU: 2000m, Memory: 4Gi)
3. Configure GitHub token secret reference
4. Scope runners to specific repositories
π Overall Compliance Score: 78/100
Target for SOC2: 95/100
Would you like me to auto-fix the applicable violations? [y/N]
```
## β‘ Quick Command Reference
Common commands you'll use frequently with this MCP server:
### Policy & Compliance
```text
# Basic validation
"Check ARC policies"
"Validate my runners against compliance rules"
# Generate compliance report
"Show me a compliance report for arc-runners namespace"
"Generate compliance report as JSON"
# Auto-fix violations (generates config files for review)
"Fix policy violations"
"Auto-fix compliance issues"
# Auto-fix and apply to cluster immediately
"Fix violations and apply to cluster"
"Auto-remediate and deploy fixes"
```
### Installation & Deployment
```text
# Install ARC controller
"Install ARC in my cluster"
"Deploy ARC controller with production settings"
# Deploy runners with config versioning
"Deploy runners for my-org repository"
"Create runner set for enterprise-repo with 5 minimum runners"
# Apply existing configurations
"Apply the my-runners config"
"Deploy config from configs/runner-sets/production.yaml"
```
### Monitoring & Status
```text
# Check overall health
"Show ARC status"
"What's the health of my runners?"
# Detect configuration drift
"Check for config drift"
"Compare deployed state with my config files"
# View logs and troubleshoot
"Show me runner logs"
"Why are my runners failing?"
```
### Scaling & Management
```text
# Scale runners
"Scale my-runners to 10"
"Increase runner capacity for evening builds"
# Manage lifecycle
"Update runner image to latest"
"Delete old runner sets"
```
### Configuration Management
```text
# List configurations
"Show all my configs"
"List runner configurations"
# Review generated configs before applying
"Generate runner config but don't apply"
"Create configuration for review only"
```
> **π‘ Pro Tip**: All commands are natural language - no need to memorize exact syntax!
## π Security & Best Practices
### π‘οΈ Security Framework
Our security model implements defense-in-depth principles:
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Security Layers β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β π Authentication β GitHub tokens, RBAC, mTLS β
β π‘οΈ Authorization β Fine-grained permissions β
β π Audit Logging β All operations tracked β
β π¦ Container Securityβ Image scanning, non-root users β
β π Network Policies β Zero-trust networking β
β π Secrets Managementβ Encrypted storage, rotation β
β π Monitoring β Real-time threat detection β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
### π¨ Security Policies
The server includes built-in security policies:
#### **Critical Security Rules**
- Container images must be from approved registries
- No privileged containers allowed
- Resource limits must be specified
- Network policies required for all namespaces
#### **Access Control Policies**
- GitHub tokens must have minimal required scopes
- Kubernetes RBAC follows least-privilege principle
- MCP client authentication required in production
#### **Operational Security**
- All operations are logged and auditable
- Sensitive data is masked in logs
- Failed operations trigger security alerts
### π Secure Configuration Example
```yaml
# Security-hardened ARC configuration
apiVersion: v1
kind: ConfigMap
metadata:
name: arc-security-config
data:
security_profile: "strict"
audit_logging: "enabled"
network_policies: "enforced"
image_scanning: "required"
resource_quotas: "mandatory"
# Policy definitions
allowed_registries: |
- ghcr.io
- gcr.io
- docker.io/library
mandatory_labels: |
- app.kubernetes.io/name
- app.kubernetes.io/version
- security.policy/compliant
```
**β οΈ Security Notice**: This tool provides administrative access to Kubernetes clusters and GitHub repositories. Always follow your organization's security policies and use appropriate access controls.
---
## π Policy Validation & Auto-Fix
### π‘οΈ Enterprise Policy Engine
The ARC MCP Server includes a comprehensive policy engine that validates your GitHub Actions Runner deployments against **18 built-in policies** covering security, compliance, performance, cost optimization, and operational best practices.
#### **Policy Categories**
| Category | Rules | Description |
|----------|-------|-------------|
| π **Security** | 6 rules | Prevent privileged runners, enforce security contexts, validate secrets |
| π **Compliance** | 2 rules | Repository scoping, runner group requirements |
| π **Performance** | 4 rules | Resource limits, container mode optimization |
| π° **Cost** | 2 rules | Reasonable CPU/replica limits, cost optimization |
| βοΈ **Operations** | 3 rules | Proper labeling, valid runner images, observability |
| π **Networking** | 1 rule | Dual-stack networking support |
#### **Policy Configuration & Environments**
Generate environment-specific policy configurations with **24 pre-configured profiles**:
```text
π§ "Generate a HIPAA policy config"
π€ β
Generated HIPAA-compliant policy configuration
π Security rules: Critical severity (PHI protection)
π Compliance rules: Critical severity (HIPAA/HITECH)
π Performance rules: High severity (reliability)
π Saved: configs/policies/arc-policy-config.json
π§ "List all available security rules"
π€ π Security Policy Rules (6 total)
β
arc-sec-001: Require Runner Security Context (High)
β
arc-sec-002: Prohibit Privileged Runners (Critical)
β
arc-sec-003: Require GitHub Token Secret (Critical)
β
arc-013-003: JIT Token Security (High)
β
arc-013-005: Azure Key Vault Integration (Medium)
β
arc-013-006: OpenShift Compatibility (Medium)
```
**Supported Environments:**
- Core: `development`, `staging`, `production`
- Compliance: `hipaa`, `fedramp`, `pci-dss`, `sox`, `gdpr`
- Industry: `financial`, `healthcare`, `government`, `education`
- Infrastructure: `edge`, `iot`, `embedded`, `multi-tenant`
- Organization: `startup`, `enterprise`
- Workload: `aiml`, `research`
- Security: `high-security`, `zero-trust`, `air-gapped`
> **π Complete Policy Guide**: See **[Policy Validation Usage Guide](docs/POLICY_VALIDATION_GUIDE.md)** for step-by-step instructions, real-world workflows, and troubleshooting
>
> **π― Policy Rule Integration**: See **[Policy Rule Integration Guide](docs/POLICY_RULE_INTEGRATION.md)** for comprehensive documentation on how policy configs integrate with the 18 built-in rules
>
> **π Policy Reference**: See [POLICY_VALIDATION.md](docs/POLICY_VALIDATION.md) for detailed rule descriptions and technical specifications
### π Auto-Fix Capabilities
The policy engine can **automatically remediate violations** by generating fixed configuration files that follow best practices.
#### **How Auto-Fix Works**
```text
π§ "Check my runners for policy violations"
π€ π Running policy validation...
β
Compliance Score: 55.6%
β 8 violations found (6 can be auto-fixed)
Critical Issues:
π΄ None found
High Priority:
π Missing security context
π Repository scope too broad
π‘ Auto-fix available for 6 violations
π§ "Auto-fix the violations"
π€ π Generating fixed configuration files...
β
Fixed security context issues
β
Added dual-stack networking support
β
Configured OpenShift compatibility
β
Added enhanced metrics labels
π Generated Files:
- configs/runner-sets/my-runners.yaml
π Next Steps:
1. Review: configs/runner-sets/my-runners.yaml
2. Commit: git add configs/ && git commit -m "fix: policy violations"
3. Apply: Say "apply the runner configuration"
4. Validate: Say "check compliance again"
π‘ Config files saved for audit trail!
```
#### **Two Auto-Fix Modes**
##### **1. Generate Only (Default - Recommended)**
Perfect for GitOps workflows - **generates fixed config files in `configs/` folder only**.
```bash
# Ask AI:
"Auto-fix my policy violations"
# What happens:
β
Fetches current runner configuration from cluster
β
Applies policy fixes to the configuration
β
Generates fixed YAML in configs/runner-sets/
β
Adds audit annotations (timestamp, violations fixed)
βΈοΈ STOPS - does NOT apply to cluster
π Shows you the changes and next steps
```
**Benefits:**
- β
**Review before apply** - See exactly what will change
- β
**Git version control** - Config files ready to commit
- β
**Audit trail** - Track all policy fixes over time
- β
**Rollback capable** - Easy to revert changes
- β
**Team collaboration** - Create PRs for review
##### **2. Generate + Apply Mode**
For development environments - **generates configs in `configs/` folder AND applies fixes to cluster**.
```bash
# Ask AI:
"Auto-fix my violations and apply them"
# or
"Auto-fix with apply=true"
# What happens:
β
Everything from mode 1 (generates configs in configs/), PLUS:
π Applies fixes directly to cluster
π Shows apply results (success/failure per resource)
β
Config files still saved in configs/ for audit trail
```
**When to use:**
- π§ͺ Development/testing environments
- π Quick fixes needed urgently
- π€ Single-person projects
- β‘ Speed over review process
#### **Fixable Violations**
The auto-fix feature can remediate these policy violations automatically:
| Violation | Fix Applied | Impact |
|-----------|-------------|--------|
| Missing security context | Adds pod security context with non-root user | Security β |
| Container mode not optimized | Sets `kubernetes-novolume` mode | Performance β, Storage costs β |
| OpenShift incompatibility | Configures `runAsUser: 999` and SCC compatibility | OpenShift support β |
| Missing enhanced metrics labels | Adds `workflow_name` and `target` labels | Observability β |
| Dual-stack networking | Configures `dnsPolicy: ClusterFirst` | IPv4/IPv6 support β |
| Missing lifecycle hooks | Adds container lifecycle hooks for novolume mode | Reliability β |
#### **Manual Remediation Required**
Some violations require human decision-making and cannot be auto-fixed:
| Violation | Why Manual? | What to Do |
|-----------|-------------|------------|
| Missing GitHub token secret | Requires actual GitHub PAT/App credentials | Configure in cluster secrets |
| Privileged runner detected | Security decision needed | Remove privileged flag or justify |
| Repository scope too broad | Business logic decision | Scope to specific repos |
| Invalid runner image | Image selection requires approval | Use official images from ghcr.io |
| Missing required labels | Naming conventions vary by org | Add org-specific labels |
| Azure Key Vault not configured | Requires Azure setup | Configure AKV CSI driver |
### π Compliance Reporting
Generate comprehensive compliance reports for your ARC deployments:
```text
π§ "Generate a compliance report for all my runners"
π€ π ARC Compliance Report
Cluster: production-aks
Namespace: arc-systems
Compliance Score: 78.5%
β
Passed: 14 rules
β Failed: 4 rules
β οΈ Warnings: 3 rules
By Severity:
π΄ Critical: 0
π High: 2
π‘ Medium: 3
π’ Low: 2
By Category:
π Security: 3 violations
π Compliance: 1 violation
βοΈ Operations: 3 violations
Top Issues:
1. [HIGH] Security context not configured (3 runners)
2. [HIGH] Runners scoped to entire org (security risk)
3. [MED] Container mode not optimized (performance impact)
π‘ 6 violations can be auto-fixed
π° Estimated cost savings from fixes: $45/month
```
### π― Policy Validation Commands
Common AI commands for policy management:
```text
# Validation
"Check my runners for policy violations"
"Validate ARC compliance"
"Run a security audit on my runners"
# Auto-Fix
"Auto-fix the policy violations"
"Fix the violations and save configs"
"Auto-fix and apply immediately" (with apply=true)
# Reporting
"Generate a compliance report"
"Show me all critical violations"
"List security policy violations"
# Specific Checks
"Check if my runners meet SOC2 requirements"
"Validate runners against security policies"
"Show me cost optimization opportunities"
```
### π Policy Customization
While the server comes with 20+ built-in policies, you can customize enforcement levels:
```bash
# Configure policy behavior via environment variables
export ARC_POLICY_ENFORCEMENT="strict" # strict, advisory, or disabled
export ARC_POLICY_AUTO_FIX_ENABLED="true" # Enable/disable auto-fix
export ARC_POLICY_CATEGORIES="security,compliance" # Focus on specific categories
```
> **π Advanced Policy Configuration**: See [EXTERNAL_POLICY_CONFIG.md](docs/EXTERNAL_POLICY_CONFIG.md) for custom policy definitions
### π Learn More
**New to policy validation?** Check out the **[Complete Policy Validation Usage Guide](docs/POLICY_VALIDATION_GUIDE.md)** for:
- π Step-by-step tutorials for each operation
- π¬ Real-world workflow examples
- π§ Troubleshooting common issues
- π Advanced usage patterns
- β
Best practices and tips
**Quick Links:**
- [Understanding Policy Categories](docs/POLICY_VALIDATION_GUIDE.md#-understanding-policy-categories)
- [Auto-Fix Features](docs/POLICY_VALIDATION_GUIDE.md#-auto-fix-features)
- [Real-World Workflows](docs/POLICY_VALIDATION_GUIDE.md#-real-world-workflows)
- [Compliance Scoring Explained](docs/POLICY_VALIDATION_GUIDE.md#-understanding-compliance-scoring)
---
## π Monitoring & Observability
### π Built-in Metrics
The server exposes comprehensive metrics for monitoring:
```javascript
// Prometheus metrics available at /metrics
arc_operations_total{operation="install",status="success"} 42
arc_operations_duration_seconds{operation="scale"} 1.23
arc_runners_active{namespace="production"} 8
arc_policy_violations_total{severity="critical"} 0
arc_github_api_requests_total{endpoint="runners"} 1337
```
### π Health Checks
Multiple health check endpoints:
- `/health` - Basic server health
- `/health/kubernetes` - Cluster connectivity
- `/health/github` - GitHub API status
- `/health/runners` - Runner status summary
### π Grafana Dashboard
Pre-built dashboard for comprehensive monitoring:
```json
{
"dashboard": {
"title": "ARC MCP Server Monitoring",
"panels": [
{
"title": "Runner Utilization",
"type": "stat",
"targets": ["arc_runners_active / arc_runners_total"]
},
{
"title": "Operation Success Rate",
"type": "gauge",
"targets": ["rate(arc_operations_total{status='success'}[5m])"]
}
]
}
}
```
## π Advanced Features
### π― Cost Optimization Engine
Intelligent cost management for runner infrastructure:
```text
π° Cost Analysis Report
βββββββββββββββββββββββββββββββββββββββββββ
β Monthly Runner Costs: $1,247 β
β Optimization Potential: -$312 (25%) β
β β
β π Recommendations: β
β β’ Scale down during weekends (-$89) β
β β’ Use spot instances (-$156) β
β β’ Optimize resource allocations (-$67) β
β β
β π― Auto-optimization Available β
βββββββββββββββββββββββββββββββββββββββββββ
```
### π€ Predictive Scaling
AI-powered scaling based on workload patterns:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: predictive-scaling-config
data:
enabled: "true"
prediction_window: "2h"
confidence_threshold: "0.8"
scale_up_factor: "1.5"
scale_down_factor: "0.7"
# ML model configuration
model_type: "time_series_forecast"
training_data_days: "30"
retrain_interval: "24h"
```
### π οΈ Self-Healing Capabilities
Automated problem detection and resolution:
```text
π§ Self-Healing Engine Status
βββ π Issue Detection: Active
β βββ Resource exhaustion monitoring
β βββ Network connectivity checks
β βββ GitHub API rate limit tracking
β βββ Runner health verification
β
βββ π οΈ Auto-Remediation: Enabled
β βββ Restart unhealthy runners
β βββ Scale up on resource pressure
β βββ Rotate expired credentials
β βββ Clean up orphaned resources
β
βββ π Success Rate: 94.2%
βββ Issues detected: 127
βββ Auto-resolved: 119
βββ Manual intervention: 8
```
## π§ͺ Testing & Validation
### π¬ Comprehensive Test Suite
Run the full test suite to ensure reliability:
```bash
# Unit tests
npm run test:unit
# Integration tests (requires cluster)
npm run test:integration
# End-to-end tests
npm run test:e2e
# Performance tests
npm run test:performance
# Security tests
npm run test:security
```
### π― Test Coverage
Current test coverage metrics:
- **Unit Tests**: 94% line coverage
- **Integration Tests**: 87% API coverage
- **E2E Tests**: 78% workflow coverage
- **Security Tests**: 100% vulnerability checks
### ποΈ Local Testing Environment
Set up a complete local testing environment:
```bash
# Start local Kubernetes cluster
npm run dev:cluster:start
# Deploy test ARC environment
npm run dev:arc:setup
# Run MCP server in development mode
npm run dev:server
# Execute test scenarios
npm run dev:test:scenarios
```
## π CI/CD Integration
### GitHub Actions Workflow
Example workflow for automated ARC management:
```yaml
name: ARC Management
on:
schedule:
- cron: '0 */6 * * *' # Every 6 hours
workflow_dispatch:
jobs:
arc-health-check:
runs-on: ubuntu-latest
steps:
- name: Check ARC Status
uses: ./
with:
mcp-server: 'ghcr.io/tsviz/arc-config-mcp:latest'
operation: 'health-check'
github-token: ${{ secrets.GITHUB_TOKEN }}
- name: Scale for Peak Hours
if: github.event.schedule == '0 9 * * 1-5' # Weekday mornings
uses: ./
with:
operation: 'scale-runners'
target-replicas: 10
- name: Cost Optimization
if: github.event.schedule == '0 18 * * 5' # Friday evenings
uses: ./
with:
operation: 'optimize-costs'
apply-recommendations: true
```
## π API Reference
### MCP Protocol Integration
The server implements the full MCP specification:
```typescript
// Tool invocation example
interface MCPToolCall {
method: "tools/call";
params: {
name: "arc_install_controller";
arguments: {
namespace: "arc-systems";
security_profile: "standard";
auto_scaling: true;
};
};
}
// Response format
interface MCPToolResponse {
content: [
{
type: "text";
text: "β
ARC controller installed successfully";
}
];
isError: false;
}
```
### REST API Endpoints
When running in HTTP mode, these endpoints are available:
```
GET /health - Server health check
GET /metrics - Prometheus metrics
POST /api/v1/arc/install - Install ARC controller
GET /api/v1/arc/status - Get ARC status
POST /api/v1/arc/scale - Scale runners
GET /api/v1/tools - List available tools
POST /api/v1/execute - Execute natural language command
```
## π Documentation
### Core Guides
| Guide | Description | When to Use |
|-------|-------------|-------------|
| **[Policy Validation Usage Guide](docs/POLICY_VALIDATION_GUIDE.md)** | Complete guide to using the policy validation tool with real-world workflows | Essential for security/compliance teams |
| **[Policy Reference](docs/POLICY_VALIDATION.md)** | Technical reference for all 20+ built-in policies | When you need detailed policy specifications |
| **[Workflow Guide](docs/WORKFLOW_GUIDE.md)** | Understanding deployment workflows (Recommended, Direct, GitOps) | Setting up your deployment process |
| **[Hybrid Workflow Visual Guide](docs/HYBRID_WORKFLOW_VISUAL_GUIDE.md)** | Visual diagrams of the GitOps workflow | Visual learners or architecture planning |
| **[Advanced Security](docs/ADVANCED_SECURITY_POLICIES.md)** | Deep dive into security configurations | Hardening production deployments |
| **[Cleanup Functionality](docs/CLEANUP_FUNCTIONALITY.md)** | Safe ARC uninstallation and cleanup | Decommissioning or troubleshooting |
| **[Enhanced Troubleshooting](docs/ENHANCED_TROUBLESHOOTING.md)** | Debugging guide and common issues | When things go wrong |
### Quick References
- **[TOOLS.md](TOOLS.md)** - Complete tool catalog with all available operations
- **[QUICK_START.md](QUICK_START.md)** - Get up and running in 5 minutes
- **[ROADMAP.md](ROADMAP.md)** - Future features and development plans
- **[Release Notes](RELEASE-NOTES-v2.4.4.md)** - Latest updates and changes
### External Resources
- [GitHub ARC Official Documentation](https://docs.github.com/en/actions/tutorials/use-actions-runner-controller)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Kubernetes Operator Pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
## π€ Contributing
We welcome contributions to improve ARC Config MCP Server!
### π Getting Started
1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Set up development environment**:
```bash
npm install
npm run dev:setup
```
4. **Make your changes**
5. **Run tests**: `npm test`
6. **Submit a pull request**
### π Development Guidelines
- Follow TypeScript best practices
- Maintain 90%+ test coverage
- Update documentation for new features
- Follow conventional commit messages
- Ensure all security checks pass
### π Code Review Process
All contributions go through our review process:
1. **Automated Checks**: CI/CD pipeline validation
2. **Security Review**: Vulnerability scanning
3. **Performance Review**: Load testing for critical paths
4. **Documentation Review**: Ensure docs are updated
5. **Maintainer Review**: Final approval by core team
## π Troubleshooting
### Common Issues
#### Installation Problems
```text
β Error: KUBECONFIG not found
π§ Solution: Set KUBECONFIG environment variable
export KUBECONFIG=/path/to/kubeconfig
β Error: GitHub token invalid
π§ Solution: Check token scopes and expiration
- Required scopes: repo, admin:org, workflow
- Generate new token: https://github.com/settings/tokens
```
#### Runtime Issues
```text
β Error: Runners not starting
π§ Diagnosis: Check resource constraints
kubectl describe pod -n arc-runners
β Error: High API rate limits
π§ Solution: Configure rate limiting
Set GITHUB_API_RATE_LIMIT=5000 in environment
```
#### Configuration Drift Issues
```text
β Issue: Config file shows minRunners: 20 but only 1 runner is running
π§ Diagnosis: Manual Helm commands can override YAML configs
# Check actual deployed values
kubectl get autoscalingrunnersets -n arc-systems <name> -o yaml
π§ Solution: Re-apply using MCP tools to sync with config files
#arc_apply_config --configType runnerSet --name <runner-set-name>
# Or use drift detection to find all mismatches
#arc_detect_drift
π‘ Best Practice: Always use MCP tools (#arc_apply_config) instead of
manual Helm commands. MCP tools read your YAML files and apply all
values correctly. Manual Helm --set commands bypass the config files.
```
#### Policy Validation Issues
```text
β Issue: False positive violations reported
π§ Diagnosis: Check actual deployed resource structure
kubectl get autoscalingrunnersets -n arc-runners <name> -o yaml | grep -A5 <field>
π§ Solution: Policy engine validates against deployed resources, not config templates
- Ensure field paths match actual Kubernetes resource structure
- Array indices like containers[0] are supported
β Issue: Auto-fix not applying to cluster
π§ Solution: Use apply=true parameter to apply fixes
#arc_validate_policies operation=auto_fix apply=true
Default behavior (apply=false): Generates config files only for review
With apply=true: Generates config files AND applies to cluster
β Issue: Compliance score lower than expected
π§ Diagnosis: Check for manual remediation required
#arc_validate_policies operation=validate
- Auto-fixable: Resources, labels, annotations, security contexts
- Manual required: GitHub secrets, container images, privileged mode
π‘ Best Practice: Always review generated config files in configs/runner-sets/
before applying to production clusters. Config files are created for
audit trail regardless of apply parameter.
```
#### Performance Issues
```text
β Issue: Slow response times
π§ Optimization: Enable caching
Set ENABLE_CACHE=true
Set CACHE_TTL=300
β Issue: High memory usage
π§ Solution: Tune garbage collection
NODE_OPTIONS="--max-old-space-size=512"
```
### π Debug Mode
Enable detailed logging for troubleshooting:
```bash
# Environment variable
export LOG_LEVEL=debug
# Runtime flag
npm start -- --log-level debug
# Specific component debugging
export DEBUG=arc:*,mcp:*,k8s:*
```
### π Getting Help
- **Documentation**: [docs/](./docs/)
- **[Workflow Guide](docs/WORKFLOW_GUIDE.md)** - Complete guide to DevOps, GitOps, and Direct workflows with GitHub Copilot Chat
- **[Hybrid Workflow Visual Guide](docs/HYBRID_WORKFLOW_VISUAL_GUIDE.md)** - Visual diagrams and step-by-step workflow illustrations
- [Hybrid Workflow Clarity](docs/HYBRID_WORKFLOW_CLARITY.md) - Detailed explanation of config files and how they're used
- [Cleanup Functionality](docs/CLEANUP_FUNCTIONALITY.md) - Safe ARC cleanup procedures
- [Enhanced Troubleshooting](docs/ENHANCED_TROUBLESHOOTING.md) - Advanced debugging guide
- [Policy as Code](docs/POLICY_AS_CODE.md) - Policy configuration and enforcement
- **Examples**: [examples/](./examples/)
- [Controller with Custom Values](examples/controller-with-values.yaml.md) - How to customize ARC controller configuration
- **Official GitHub ARC Docs**:
- [ARC Tutorial](https://docs.github.com/en/actions/tutorials/use-actions-runner-controller) - Getting started guide
- [ARC Concepts](https://docs.github.com/en/actions/concepts/runners/actions-runner-controller) - Core concepts
- [Runner Scale Sets](https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/runners/runner-scale-sets) - Autoscaling
- [ARC Support](https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/runners/support-for-arc) - Enterprise support
- **GitHub Issues**: [Create an issue](https://github.com/tsviz/arc-config-mcp/issues/new)
- **Discussions**: [GitHub Discussions](https://github.com/tsviz/arc-config-mcp/discussions)
- **Security Issues**: security@tsviz.com
## π Learning Resources
### π Official GitHub Documentation
**Essential ARC Resources:**
- **[ARC Tutorial](https://docs.github.com/en/actions/tutorials/use-actions-runner-controller)** - Step-by-step guide to getting started with ARC
- **[ARC Concepts](https://docs.github.com/en/actions/concepts/runners/actions-runner-controller)** - Understanding how ARC works
- **[Runner Scale Sets](https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/runners/runner-scale-sets)** - Learn about autoscaling runners
- **[ARC Support & SLA](https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/runners/support-for-arc)** - Formal support information for enterprise
### π Additional Reading
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Actions Runner Controller Repository](https://github.com/actions/actions-runner-controller)
- [Kubernetes Operator Pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
### π₯ Video Tutorials
- [ARC MCP Server Quick Start](https://youtube.com/example) (5 min)
- [Advanced Configuration Guide](https://youtube.com/example) (15 min)
- [Troubleshooting Common Issues](https://youtube.com/example) (10 min)
### π‘ Best Practices Guide
- [Enterprise Deployment Patterns](./docs/ENTERPRISE_DEPLOYMENT.md)
- [Security Hardening Checklist](./docs/SECURITY_CHECKLIST.md)
- [Performance Optimization Guide](./docs/PERFORMANCE_TUNING.md)
## π Roadmap
### π― Upcoming Features
#### Version 1.6.0 (Next Release)
- [ ] **Multi-cluster Support**: Manage ARC across multiple Kubernetes clusters
- [ ] **Advanced Cost Analytics**: ML-powered cost prediction and optimization
- [ ] **Webhook Integration**: Real-time event processing from GitHub
- [ ] **Custom Policy DSL**: Domain-specific language for policy configuration
#### Version 1.7.0 (Q2 2024)
- [ ] **GitOps Integration**: ArgoCD and Flux compatibility
- [ ] **Advanced Scheduling**: Complex workload-aware runner scheduling
- [ ] **Integration Hub**: Pre-built integrations with popular DevOps tools
- [ ] **Mobile Dashboard**: React Native app for on-the-go monitoring
#### Version 2.0.0 (Q3 2024)
- [ ] **Multi-Cloud Support**: AWS, GCP, Azure runner orchestration
- [ ] **AI-Powered Optimization**: GPT-4 powered operational intelligence
- [ ] **Enterprise SSO**: SAML, OIDC, and LDAP integration
- [ ] **Compliance Framework**: SOC2, ISO27001, PCI-DSS automation
### πΊοΈ Long-term Vision
Transform ARC management from manual operations to fully autonomous, AI-driven infrastructure that:
- Predicts and prevents issues before they occur
- Optimizes costs automatically across cloud providers
- Ensures compliance with evolving security standards
- Scales intelligently based on development team patterns
## π License & Legal
### License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
### Third-Party Dependencies
- **Node.js Ecosystem**: Various MIT and Apache 2.0 licensed packages
- **Kubernetes Client**: Apache 2.0 License
- **GitHub API**: Used under GitHub Terms of Service
### Security Disclosure
For security vulnerabilities, please email security@tsviz.com instead of using public issues.
### Contributing License Agreement
By contributing to this project, you agree that your contributions will be licensed under the same MIT License.
## π Related Projects & Ecosystem
### Official Projects
- **[ARC Config Repo](https://github.com/tsviz/arc-config-repo)**: Original ARC configuration and policies
- **[K8s MCP Server](https://github.com/tsviz/k8s_mcp)**: General Kubernetes management MCP server
### Community Projects
- **[Actions Runner Controller](https://github.com/actions/actions-runner-controller)**: The core ARC project
- **[GitHub Official ARC Docs](https://docs.github.com/en/actions/concepts/runners/actions-runner-controller)**: Complete documentation
- [Tutorial: Use ARC](https://docs.github.com/en/actions/tutorials/use-actions-runner-controller)
- [Runner Scale Sets](https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/runners/runner-scale-sets)
- [ARC Support](https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/runners/support-for-arc)
- **[Model Context Protocol](https://modelcontextprotocol.io/)**: Protocol specification and tools
- **[GitHub Copilot](https://github.com/features/copilot)**: AI pair programmer integration
### Complementary Tools
- **Monitoring**: Prometheus, Grafana, DataDog integration examples
- **Security**: Falco, OPA Gatekeeper policy examples
- **GitOps**: ArgoCD, Flux configuration templates
- **Cost Management**: Kubecost, OpenCost integration guides
---
<div align="center">
**π Ready to transform your ARC operations?**
[Get Started](./docs/QUICKSTART.md) β’ [View Examples](./examples/) β’ [Join Community](https://github.com/tsviz/arc-config-mcp/discussions)
*Transforming GitHub Actions runner management from manual kubectl commands to conversational AI-powered automation* β¨
</div>