rvn-ec2-service / Latest version: 2.2.0
See EC2 Service module reference for the full module page.
$ref:rvn-aws-network
required
VPC network. Existing Ravion network that supplies the AWS account, region, VPC, and public and private subnets for the instances.
- Immutable after creation
network to null.
Mapped inputs for network: set these keys alongside network, not inside it, when supplying existing infrastructure instead of a module reference.
section
AWS account & region.
string
AWS account.
- Default:
<< ref.input.aws_account_id >> - Immutable after creation
string
Region. AWS region for this module. If unset in Terraform, the provider region is used.
- Default:
<< ref.input.aws_region >> - Immutable after creation
string
Terraform execution environment. Override the VPC, subnet, and security group for Terraform runners. Must use the same AWS account as selected above.
- Default:
<< ref.input.execution_environment_id >>
section
VPC.
string
required
VPC ID.
- Default:
<<ref.stack.output.vpc_id>> - Immutable after creation
string_array
required
Private subnet IDs. Required by Terraform. Used for private workloads and private load balancers.
- Default:
<<ref.stack.output.private_subnet_ids>> - Immutable after creation
string_array
Public subnet IDs. Used for public load balancers. Terraform defaults to [] when no public load balancer is enabled.
- Default:
<<ref.stack.output.public_subnet_ids>> - Immutable after creation
boolean
Run in private subnets. Recommended. Requires a NAT gateway or equivalent for internet access and a static IP.
- Default:
true
EC2 service config
string
required
Service name. Stable service name used to prefix the instance group and name related resources.
- Default:
<<project.given_id>>-<<environment.given_id>>-<<module.given_id>> - Immutable after creation
- Pattern:
^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$— 1-28 lowercase letters, numbers, and hyphens. Start and end with a letter or number.
string
required
Instance type. Pick the family that matches the workload (
t burstable, m general purpose, c CPU-bound, r memory-bound), then the highest generation number this list offers for it, such as m8g rather than m7g or m6i. Graviton (g) types give the best price and performance and need an arm64 image. Never copy an instance type from an example or from memory; see the README for the full selection guide.string
Custom AMI ID. Custom AMI for new instances. Leave blank for the latest architecture-matched Amazon Linux 2023 AMI.
string
SSH key pair name. Optional EC2 key pair for SSH access.
text
Additional user data. Shell script run as root after Ravion’s bootstrap on every newly launched instance.
boolean
Serve HTTP traffic. Off for a worker. On to serve HTTP traffic through a load balancer.
- Default:
true
string
required
Deploy type. Choose in-place container image deploys or host-level shell commands.
- Default:
container - Allowed values:
container(Container),manual(Manual)
Build config
string
required
Build source. Build a container image from source with Dockerfile or Railpack, use a Ravion-managed ECR repository populated by a pipeline, or deploy an existing image from a configured registry repository.
- Default:
dockerfile - Allowed values:
dockerfile(Dockerfile),railpack(Railpack),image_registry(Pull from image registry),ecr(Managed ECR repository) - Shown when:
{"deploy_type":"container"}
gitrepo
required
Git repository. Repository containing the application source for Dockerfile or Railpack builds.
- Shown when:
{"build_source":["dockerfile","railpack"],"deploy_type":"container"}
string
Source base path. Repository-relative source and build root.
- Default:
. - Shown when:
{"build_source":["dockerfile","railpack"],"deploy_type":"container"}
string
required
Image repository. Repository without a tag or digest, such as
nginx or 123456789012.dkr.ecr.us-east-1.amazonaws.com/app. Registries requiring Docker credentials are unsupported. Same-region private ECR also needs a repository policy that lets the service instance role pull images.- Shown when:
{"build_source":"image_registry","deploy_type":"container"}
string
Start command override. Optional command string that overrides the image CMD. The image ENTRYPOINT is preserved.
- Shown when:
{"deploy_type":"container"}
boolean
Docker socket mount. Mount the host Docker socket into the container and add the host docker group’s GID. This grants the container root-equivalent control of the instance: it can start privileged containers, read the host filesystem, and use the instance role. The container image must include a docker CLI for this to be useful.
- Default:
false - Shown when:
{"deploy_type":"container"}
Docker
string
Dockerfile path. Path to the Dockerfile to use for the build, relative to the repository root or configured source base path.
- Shown when:
{"build_source":"dockerfile","deploy_type":"container"}
string
Docker build context path. Directory to use as the Docker build context, relative to the repository root or configured source base path.
- Shown when:
{"build_source":"dockerfile","deploy_type":"container"}
Railpack
string
Railpack version. Optional Railpack version to use for the build. Leave blank to use the Ravion default.
- Pattern:
^(|latest|v?[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?)$— Leave blank, use latest, a semantic version like 0.29.0, or a v-prefixed version like v0.29.0. - Shown when:
{"build_source":"railpack","deploy_type":"container"}
string
Install command. Optional dependency installation command. Leave blank to use Railpack detection.
- Shown when:
{"build_source":"railpack","deploy_type":"container"}
string
Build command. Optional application build command. Leave blank to use Railpack detection.
- Shown when:
{"build_source":"railpack","deploy_type":"container"}
string
Start command. Optional start command embedded in the Railpack-built image. Leave blank to use Railpack detection.
- Shown when:
{"build_source":"railpack","deploy_type":"container"}
Deployment
gitrepo
Git repository. Optional repository to check out before manual deploy commands run. Leave blank to run the commands without a managed source checkout.
- Shown when:
{"deploy_type":"manual"}
string
Source base path. Repository-relative working directory for manual deploy and start commands when a Git repository is selected.
- Default:
. - Shown when:
{"deploy_source_repo":{"not":""},"deploy_type":"manual"}
string_array
required
Deploy commands. Release preparation commands run as root, in order, on every instance during each manual deploy. Keep them idempotent; any command that exits non-zero fails that instance’s deploy.
- Shown when:
{"deploy_type":"manual"}
string
required
Start command. Long-running foreground app command that supervisord runs as root after preparation and restarts if it exits. Use a wrapper to drop privileges when needed; the command must not daemonize.
- Shown when:
{"deploy_type":"manual"}
string
required
Maximum concurrent instances. Maximum instances updated at once. Use an instance count such as 1 or a percentage such as 25%.
- Default:
1 - Pattern:
^([1-9][0-9]*|[1-9][0-9]?%|100%)$— Positive instance count or percentage from 1% to 100%.
string
required
Maximum deployment errors. Number or percentage of failed instances tolerated before the deployment stops on remaining instances.
- Default:
0 - Pattern:
^(0|[1-9][0-9]*|[1-9][0-9]?%|100%)$— Zero, a positive error count, or percentage from 1% to 100%.
number
Per-instance deploy timeout (secs). Maximum time allowed for the SSM deploy script on each instance, for both container and manual deploys.
- Default:
1200 - Min:
60 - Max:
14400
HTTP routing
string
required
Load balancer source. Must use the same AWS account, region, and VPC as the VPC network.
- Default:
standalone_alb - Allowed values:
standalone_alb(Standalone ALB module),ecs_cluster(ALB from ECS Cluster module) - Immutable after creation
- Shown when:
{"http_traffic_enabled":true}
$ref:rvn-aws-alb
required
Standalone ALB module. Attach listener rules to this.
- Immutable after creation
- Shown when:
{"http_traffic_enabled":true,"load_balancer_source":"standalone_alb"}
alb to null.
Mapped inputs for alb: set these keys alongside alb, not inside it, when supplying existing infrastructure instead of a module reference.
string
ALB HTTP listener ARN.
- Default:
<<ref.stack.output.http_listener_arn>> - Immutable after creation
string
ALB HTTPS listener ARN.
- Default:
<<ref.stack.output.https_listener_arn>> - Immutable after creation
string
required
ALB security group ID.
- Default:
<<ref.stack.output.security_group_id>> - Immutable after creation
string
required
ALB ARN suffix.
- Default:
<<ref.stack.output.alb_arn_suffix>> - Immutable after creation
string
ALB DNS name.
- Default:
<<ref.stack.output.alb_dns_name>> - Immutable after creation
number
ALB HTTP listener port.
- Default:
<<ref.input.http_listener_port>> - Immutable after creation
number
ALB HTTPS listener port.
- Default:
<<ref.input.https_listener_port>> - Immutable after creation
$ref:rvn-ecs-cluster
required
ECS Cluster. Attach listener rules to the ALB in this cluster.
- Immutable after creation
- Shown when:
{"http_traffic_enabled":true,"load_balancer_source":"ecs_cluster"}
ecs_cluster to null.
Mapped inputs for ecs_cluster: set these keys alongside ecs_cluster, not inside it, when supplying existing infrastructure instead of a module reference.
section
Cluster load balancers.
string
Public ALB HTTP listener ARN.
- Default:
<<ref.stack.output.public_alb_http_listener_arn>> - Immutable after creation
string
Public ALB HTTPS listener ARN. HTTPS listener ARN from the selected public ALB. Ravion uses it when present, otherwise falls back to HTTP.
- Default:
<<ref.stack.output.public_alb_https_listener_arn>> - Immutable after creation
string
Public ALB security group ID.
- Default:
<<ref.stack.output.public_alb_security_group_id>> - Immutable after creation
string
Private ALB HTTP listener ARN.
- Default:
<<ref.stack.output.private_alb_http_listener_arn>> - Immutable after creation
string
Private ALB HTTPS listener ARN. HTTPS listener ARN from the selected private ALB. Ravion uses it when present, otherwise falls back to HTTP.
- Default:
<<ref.stack.output.private_alb_https_listener_arn>> - Immutable after creation
string
Private ALB security group ID.
- Default:
<<ref.stack.output.private_alb_security_group_id>> - Immutable after creation
string
Public ALB ARN suffix.
- Default:
<<ref.stack.output.public_alb_arn_suffix>> - Immutable after creation
string
Private ALB ARN suffix.
- Default:
<<ref.stack.output.private_alb_arn_suffix>> - Immutable after creation
string
Public ALB DNS name.
- Default:
<<ref.stack.output.public_alb_dns_name>> - Immutable after creation
string
Private ALB DNS name.
- Default:
<<ref.stack.output.private_alb_dns_name>> - Immutable after creation
string
required
ALB to use from ECS Cluster module. The selected load balancer must be enabled on the cluster.
- Default:
public - Allowed values:
public(Public),private(Private) - Shown when:
{"http_traffic_enabled":true,"load_balancer_source":"ecs_cluster"}
number
required
App port. Port the host application listens on. Container mode publishes the same container port, and PORT is set automatically.
- Default:
80 - Min:
1 - Max:
65535 - Immutable after creation
- Shown when:
{"http_traffic_enabled":true}
HTTP listener rules
string_array
Domain host rules. Hostnames that should route to this service, such as app.example.com or *.example.com. Leave empty to use path-based routing.
- Shown when:
{"http_traffic_enabled":true}
string_array
Path rules. Path patterns that should route to this service, such as /, /api/, or /app/. If both domain host rules and path rules are empty, the service routes all paths with /.
- Shown when:
{"http_traffic_enabled":true}
number
Listener rule priority. Optional ALB listener rule priority. Leave blank to let AWS assign the next available priority.
- Min:
1 - Max:
50000 - Shown when:
{"http_traffic_enabled":true}
Health check
string
required
Health check path. HTTP path used by the load balancer health check and by the Container-mode deploy gate on each instance.
- Default:
/ - Shown when:
{"http_traffic_enabled":true}
string
required
Success codes. HTTP status codes the ALB treats as healthy, such as 200-399.
- Default:
200-399 - Shown when:
{"http_traffic_enabled":true}
number
Interval (secs). Seconds between Application Load Balancer health checks.
- Default:
10 - Min:
5 - Max:
300 - Shown when:
{"http_traffic_enabled":true}
number
Timeout (secs). Seconds the Application Load Balancer waits for a health-check response. Must be lower than the interval.
- Default:
5 - Min:
2 - Max:
120 - Shown when:
{"http_traffic_enabled":true}
number
Healthy threshold. Consecutive successful ALB checks required before an instance is healthy.
- Default:
2 - Min:
2 - Max:
10 - Shown when:
{"http_traffic_enabled":true}
number
Unhealthy threshold. Consecutive failed ALB checks required before an instance is unhealthy.
- Default:
2 - Min:
2 - Max:
10 - Shown when:
{"http_traffic_enabled":true}
number
Instance health check grace period (secs). Seconds after launch before Auto Scaling health checks apply.
- Default:
300 - Min:
0
number
Slow start duration (secs). Seconds the load balancer gradually increases traffic to a newly healthy instance. Use 0 to disable.
- Default:
0 - Min:
0 - Max:
900 - Shown when:
{"http_traffic_enabled":true}
number
Deregistration delay (secs). Seconds allowed for in-flight requests to drain before a Container-mode in-place swap.
- Default:
30 - Min:
0 - Max:
3600 - Shown when:
{"http_traffic_enabled":true}
boolean
Sticky sessions. Keep repeat requests on the same instance using a load balancer or application cookie.
- Default:
false - Shown when:
{"http_traffic_enabled":true}
string
required
Stickiness type. Use a load-balancer-generated cookie or an application cookie.
- Default:
lb_cookie - Allowed values:
lb_cookie(Load balancer cookie),app_cookie(Application cookie) - Shown when:
{"http_traffic_enabled":true,"target_group_stickiness_enabled":true}
string
required
Application cookie name. Application cookie name used for target stickiness.
- Shown when:
{"http_traffic_enabled":true,"target_group_stickiness_enabled":true,"target_group_stickiness_type":"app_cookie"}
number
Stickiness cookie duration (secs). How long the cookie keeps a client routed to the same instance.
- Default:
86400 - Min:
1 - Max:
604800 - Shown when:
{"http_traffic_enabled":true,"target_group_stickiness_enabled":true}
Storage
number
Root volume size (GB). Required encrypted boot disk for the operating system, Docker, and local files. Its contents persist across deploys, restarts, and in-place stack updates, but not instance or group replacement.
- Default:
30 - Min:
8 - Max:
16384
boolean
Data volume. Attach a second encrypted EBS disk to keep application data separate from the boot disk, for example a local database, uploads, or a cache. Each instance gets its own disk, which persists for the life of that instance.
- Default:
false
number
Data volume size (GB). Size of the dedicated EBS data volume attached to each instance. Take EBS snapshots or back up elsewhere if it holds critical data.
- Default:
20 - Min:
1 - Max:
16384 - Shown when:
{"data_volume_creation_enabled":true}
string
required
Data volume mount path. Absolute host path for the data volume.
- Default:
/data - Pattern:
^/— Use an absolute path. - Shown when:
{"data_volume_creation_enabled":true}
boolean
EFS file system. Mount a shared network filesystem that every instance can access. Use it when multiple instances need the same files, or when files must survive instance replacement without a restore step.
- Default:
false
$ref:rvn-efs
required
EFS file system.
- Shown when:
{"efs_enabled":true}
efs to null.
Mapped inputs for efs: set these keys alongside efs, not inside it, when supplying existing infrastructure instead of a module reference.
string
EFS file system ID.
- Default:
<<ref.stack.output.file_system_id>>
string
EFS access point ID.
- Default:
<<ref.stack.output.access_point_id>>
string
EFS client security group ID.
- Default:
<<ref.stack.output.client_security_group_id>>
string
required
EFS mount path. Host path where the file system is mounted.
- Default:
/mnt/efs - Pattern:
^/— Use an absolute path. - Shown when:
{"efs_enabled":true}
Scaling
number
required
Minimum instances.
- Default:
1 - Min:
0
number
required
Maximum instances.
- Default:
1 - Min:
1
boolean
CPU autoscaling.
- Default:
false
number
CPU target (%). Average EC2 CPU utilization that target-tracking autoscaling tries to maintain.
- Default:
70 - Min:
1 - Max:
100 - Shown when:
{"cpu_autoscaling_enabled":true}
number
Desired instances. Initial group size when CPU autoscaling is off. Leave blank to start at the minimum.
- Min:
0 - Shown when:
{"cpu_autoscaling_enabled":false}
Environment variables
object
Build environment variables. Only available during the build, not at runtime. Use environment variables or secrets for runtime values.
- Shown when:
{"build_source":["dockerfile","railpack"],"deploy_type":"container"}
boolean
Inject environment variables in Dockerfile. Pass build environment variables into Dockerfile builds as build arguments.
- Default:
false - Shown when:
{"build_source":"dockerfile","deploy_type":"container"}
array
Runtime environment variables. Plain, single-line environment variables written to each instance at boot and refreshed on every deploy.
array
Runtime secrets. Secret environment variables fetched on each instance, as an array of objects with
name and value_from keys (snake_case, not valueFrom). value_from is a Secrets Manager secret ARN, an SSM parameter ARN, or a bare SSM parameter name.Networking
string_array
Additional security groups. Additional security groups attached to the instances.
string_array
Allowed CIDR blocks. IPv4 CIDR blocks allowed to reach the app port directly, bypassing the load balancer.
- Shown when:
{"http_traffic_enabled":true}
Builder config
string
required
Builder capacity type. Sandbox starts fastest. EC2 spot costs less but may wait for capacity or be interrupted.
- Default:
sandbox - Allowed values:
sandbox(Sandbox),ec2(EC2),ec2-spot(EC2 spot) - Shown when:
{"build_source":["dockerfile","railpack"],"deploy_type":"container"}
string
required
Builder instance type. EC2 instance type for builds. Start with the default value, then increase or decrease it based on the resource usage report at the end of builds.
- Default:
c7a.4xlarge - Shown when:
{"build_capacity_type":["ec2","ec2-spot"],"build_source":["dockerfile","railpack"],"deploy_type":"container"}
number
required
Builder vCPUs.
- Default:
14 - Shown when:
{"build_capacity_type":"sandbox","build_source":["dockerfile","railpack"],"deploy_type":"container"}
number
required
Builder memory (GiB).
- Default:
28 - Shown when:
{"build_capacity_type":"sandbox","build_source":["dockerfile","railpack"],"deploy_type":"container"}
number
Builder disk (GiB). Space the build reserves on the pool host for what it writes. Larger values let fewer builds share a host.
- Default:
30 - Shown when:
{"build_capacity_type":"sandbox","build_source":["dockerfile","railpack"],"deploy_type":"container"}
boolean
Interruptible build. Lets the build run on spot hosts and start over if AWS reclaims the host. Turn off if your build commands change anything outside the build, such as running database migrations.
- Default:
true - Shown when:
{"build_capacity_type":"sandbox","build_source":["dockerfile","railpack"],"deploy_type":"container"}
string
Builder execution environment. Optional execution environment ID or given ID for builds. Defaults to the module Terraform execution environment.
- Shown when:
{"build_source":["dockerfile","railpack"],"deploy_type":"container"}
string
Builder AMI. Optional AMI ID for build runners. Leave empty to use the default runner image.
- Shown when:
{"build_capacity_type":["ec2","ec2-spot"],"build_source":["dockerfile","railpack"],"deploy_type":"container"}
boolean
Include default build policies. The step’s built-in policies (ECR/S3 access, CloudWatch agent) stay attached alongside your Builder IAM policies. Turn off to run the build with only the policies listed below.
- Default:
true - Shown when:
{"build_source":["dockerfile","railpack"],"deploy_type":"container"}
string_array
Builder IAM policies. IAM managed policy ARNs for the EC2 build runner role, applied for the duration of each build.
- Default:
[] - Shown when:
{"build_source":["dockerfile","railpack"],"deploy_type":"container"}
Container registry
boolean
Scan images on push. Scan images for vulnerabilities after they are pushed to the Ravion-created ECR repository. Enabled by default to satisfy SOC 2 vulnerability-scanning requirements.
- Default:
true - Shown when:
{"build_source":["dockerfile","railpack","ecr"],"deploy_type":"container"}
boolean
Force delete image repository. Allow the Ravion-created ECR repository to be deleted while it still contains images.
- Default:
false - Shown when:
{"build_source":["dockerfile","railpack","ecr"],"deploy_type":"container"}
Logging
number
Log retention (days). CloudWatch retention for app logs.
- Default:
30 - Min:
1
number
Log rotation size (MB). Size at which supervisord rotates the app log file on the instance. Bounds disk usage when the process restarts repeatedly.
- Default:
20 - Min:
1 - Max:
1024
number
Rotated log files kept. Number of rotated app log files kept on the instance. On-instance usage is bounded by (this + 1) times the rotation size.
- Default:
5 - Min:
1 - Max:
100
keyvalue
Tags. A map of tags to assign to all resources. Default tags are
Owner, ProjectGivenId, EnvironmentGivenId, ModuleGivenId, ModuleIdTerraform settings
string
OpenTofu version override. Override the environment’s default version for this module
string
Ravion Terraform workspace name. Override Terraform state backend workspace name. Defaults to project + environment + module given ids.
- Immutable after creation
boolean
Include default plan policies. Turn off to plan with only the policies below instead of the default read-only policies. Requires at least one policy below.
- Default:
true
string_array
Terraform plan IAM policies. IAM managed policy ARNs for the Terraform plan runner role. Without default policies, allow s3:CreateBucket, s3:PutObject, s3:GetObject, and s3:ListBucket on the ravion-terraform-plans-<AWS account number> bucket in this account.
- Default:
[]
boolean
Include default apply policies. Turn off to apply and destroy with only the policies below instead of AdministratorAccess. Requires at least one policy below.
- Default:
true
string_array
Terraform apply IAM policies. IAM managed policy ARNs for the Terraform apply runner role. Without default policies, allow s3:CreateBucket, s3:PutObject, s3:GetObject, and s3:ListBucket on the ravion-terraform-plans-<AWS account number> bucket in this account.
- Default:
[]
object
Advanced Terraform variables. Optional raw Terraform variable overrides for advanced module inputs or one-off overrides. Values here override the generated variables above.
- Default:
{}