Skip to content

Commit 47ffe45

Browse files
hllvchllvc
committed
SG-3410: Add standalone registration for runner with existing group.
1 parent 56780c4 commit 47ffe45

File tree

13 files changed

+1213
-0
lines changed

13 files changed

+1213
-0
lines changed

‎stackguardian_private_runner/aws_runner/DOCUMENTATION.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# StackGuardian Private Runner - AWS Template
2+
3+
Deploy a StackGuardian Private Runner on AWS with auto-scaling capabilities and complete platform integration.
4+
5+
## Overview
6+
7+
This template creates a StackGuardian Private Runner infrastructure on AWS with auto-scaling capabilities, enabling secure execution of workflows in your private environment.
8+
9+
### What This Template Creates
10+
11+
- **Auto Scaling Group** with EC2 instances running the StackGuardian runner
12+
- **Lambda-based autoscaler** that scales runners based on job queue metrics
13+
- **S3 storage backend** for Terraform state and artifacts with encryption
14+
- **Security groups** and networking configuration
15+
- **StackGuardian Runner Group and Connector** for platform integration
16+
17+
## Prerequisites
18+
19+
1. **StackGuardian API Key** - Generate from your organization settings
20+
2. **AWS Permissions** - Your AWS account needs sufficient permissions (see `aws_permissions.json`)
21+
3. **Custom AMI** - AMI with required dependencies: docker, cron, jq, sg-runner
22+
4. **VPC Infrastructure** - Existing VPC with at least one public subnet
23+
24+
## Template Parameters
25+
26+
### Required Parameters
27+
28+
| Parameter | Description | Type |
29+
| -------------------------- | ---------------------------------------------- | -------- |
30+
| `stackguardian.api_key` | StackGuardian API key (must start with `sgu_`) | `string` |
31+
| `aws_region` | Target AWS region for deployment | `string` |
32+
| `ami_id` | AMI ID with runner dependencies | `string` |
33+
| `network.vpc_id` | Existing VPC ID | `string` |
34+
| `network.public_subnet_id` | Public subnet for runner instances | `string` |
35+
36+
### Optional Parameters
37+
38+
| Parameter | Description | Default |
39+
| ----------------------------------------------- | ---------------------------------------------- | ------------ |
40+
| `stackguardian.org_name` | Organization name (auto-derived from API key) | `""` |
41+
| `instance_type` | EC2 instance type | `t3.xlarge` |
42+
| `volume.type` | EBS volume type (gp2/gp3/io1/io2) | `gp3` |
43+
| `volume.size` | Volume size in GB | `100` |
44+
| `volume.delete_on_termination` | Delete volume when instance terminates | `false` |
45+
| `override_names.global_prefix` | Prefix for all resource names | `SG_RUNNER` |
46+
| `override_names.runner_group_name` | Custom runner group name | `""` |
47+
| `override_names.connector_name` | Custom connector name | `""` |
48+
| `firewall.ssh_key_name` | EC2 Key Pair name for SSH access | `""` |
49+
| `firewall.ssh_public_key` | SSH public key content | `""` |
50+
| `firewall.ssh_access_rules` | IP ranges allowed SSH access | `{}` |
51+
| `firewall.additional_ingress_rules` | Custom firewall rules | `{}` |
52+
| `scaling.min_runners` | Minimum number of runner instances | `1` |
53+
| `scaling.scale_out_threshold` | Scale out threshold (jobs) | `3` |
54+
| `scaling.scale_in_threshold` | Scale in threshold (jobs) | `1` |
55+
| `scaling.scale_out_cooldown_duration` | Scale out cooldown (minutes) | `4` |
56+
| `scaling.scale_in_cooldown_duration` | Scale in cooldown (minutes) | `5` |
57+
| `scaling.scale_out_step` | Instances to add per scale-out | `1` |
58+
| `scaling.scale_in_step` | Instances to remove per scale-in | `1` |
59+
| `force_destroy_storage_backend` | Allow destroying S3 bucket with data | `false` |
60+
61+
## Important Notes
62+
63+
**AMI Requirements**: Your AMI must include docker, cron, jq, and the sg-runner binary. Use the StackGuardian Packer template for best results.
64+
65+
**Network Security**: Runners need outbound HTTPS (port 443) access to communicate with StackGuardian. Private subnet deployment requires NAT Gateway or similar for internet access.
66+
67+
**Auto-scaling**: The Lambda function monitors your StackGuardian job queue and automatically adjusts the number of running instances based on demand. Default thresholds are 3 jobs to scale out and 1 job to scale in.
68+
69+
## Outputs
70+
71+
| Output | Description |
72+
| ------------------------ | ----------------------------------- |
73+
| `runner_group_name` | Use this name in workflow configurations |
74+
| `runner_group_url` | Direct link to manage runners in StackGuardian |
75+
| `storage_backend_name` | S3 bucket for state storage |
76+
| `autoscaling_group_name` | Auto Scaling Group name |
77+
| `lambda_function_name` | Lambda autoscaler function name |
78+
79+
## Security Features
80+
81+
- S3 bucket with encryption at rest and versioning enabled
82+
- Security groups restrict access to necessary ports only
83+
- IAM roles follow least-privilege principles
84+
- Optional private subnet deployment for network isolation
85+
86+
## Usage
87+
88+
After deployment, the template creates a Runner Group that will appear in your StackGuardian organization. Use the Runner Group name (from outputs) when configuring workflows to execute on your private infrastructure.
89+
90+
This template integrates seamlessly with StackGuardian workflows - simply select the created Runner Group when configuring your infrastructure deployments.
91+

0 commit comments

Comments
 (0)