Reference
Rack Parameters

Setting Parameters

Parameters can be set using the following command:

$ convox rack params set Foo=bar

You can also set multiple parameters at once:

$ convox rack params set Foo=bar Baz=qux

Available Parameters

Which Amazon Machine Image should be used.

How many Rack API containers to run. Setting this higher than 2 will guarantee better Rack API availability for mission critical clusters.

| Default value | 2 |

How much CPU should be reserved by the API web process.

| Default value | 128 |

How much memory should be reserved by the API web process.

| Default value | 128 |

Autoscale rack instances. See our Scaling doc for more information.

| Default value | Yes | | Allowed values | Yes, No |

The number of instances of extra capacity that autoscale should keep running.

| Default value | 1 |

Override the default availability zones used in a Rack. Please note that updating this parameter once a Rack is installed will require setting MaxAvailabilityZones to the new AZs quantity you are choosing.

| Default value | |

How much CPU should be allocated to builds.

| Default value | 0 |

EC2 instance type to create and use as the Rack’s dedicated build instance.

Note: the build instance will also use the InstanceBootCommand and InstanceRunCommand Rack params, if defined.

| Default value | | | Allowed values | EC2 Instance Types |

See also the InstanceType Rack parameter.

Defines the amount of memory (in MB) that the instance should allocate to build containers for each build.

| Default value | 1024 |

Getting build errors like Starting build... ERROR: not enough memory available to start process? You should either reduce this parameter, or change the InstanceType parameter to an instance type with more memory.
Note: If you set BuildMemory to an amount that's more than half of the total memory available to the build instance, you'll only be able to run one build at a time. If this value is too high, builds may fail.
Getting errors like No space left on device on your builds (not your running applications)? You can extend the space on the device by increasing this parameter.

Default container disk size in GB.

| Default value | 100 |

Anonymous identifier.

| Default value | dev@convox.com |

The credit option for CPU usage of a T instance.

| Allowed values | standard, unlimited |

Defines the default Amazon Machine Image (AMI) used for x86_64-based rack instances. This allows racks to automatically use the latest recommended ECS-optimized AMI without manual intervention.

| Default value | /aws/service/ecs/optimized-ami/amazon-linux-2/recommended/image_id | | Allowed values | AWS SSM AMI path (e.g., /aws/service/ecs/optimized-ami/amazon-linux-2023/recommended/image_id) |

By default, Convox racks use the Amazon Linux 2 (AL2) ECS-optimized AMI. However, with AL2 nearing deprecation, you can switch to Amazon Linux 2023 (AL2023) by setting:

$ convox rack params set DefaultAmi="/aws/service/ecs/optimized-ami/amazon-linux-2023/recommended/image_id"

If the Ami rack parameter is set, DefaultAmi will be ignored, and the explicitly set Ami value will be used instead.

Defines the default Amazon Machine Image (AMI) used for ARM64-based rack instances. This ensures ARM-based racks always use the latest ECS-optimized AMI unless manually overridden.

| Default value | /aws/service/ecs/optimized-ami/amazon-linux-2/arm64/recommended/image_id | | Allowed values | AWS SSM AMI path (e.g., /aws/service/ecs/optimized-ami/amazon-linux-2023/arm64/recommended/image_id) |

If your rack runs on ARM64 architecture, it will use the Amazon Linux 2 (AL2) ARM64 ECS-optimized AMI by default. You can switch to Amazon Linux 2023 for ARM by setting:

$ convox rack params set DefaultAmiArm="/aws/service/ecs/optimized-ami/amazon-linux-2023/arm64/recommended/image_id"

If the Ami rack parameter is set, DefaultAmiArm will be ignored, and the explicitly set Ami value will be used instead.

Disable exposing 80 port on ALB

| Default value | No | | Allowed values | Yes, No |

Determines if a dynamodb table is protected from deletion. When enabled, the table cannot be deleted by any user or process. This setting is disabled by default.

| Default value | false | | Allowed values | true, false |

Indicates whether point in time recovery is enabled or disabled on the dynamodb table.

| Default value | false | | Allowed values | true, false |

Sets a custom timeout duration for stopping ECS containers. This parameter defines the time (in seconds) ECS waits after sending a SIGTERM before issuing a SIGKILL, allowing for graceful shutdowns.

By default, this value is unset, meaning ECS will use its default 30-second stop timeout or any custom configuration already set at the ECS level.

| Default value | | | Allowed values | Numerical values in seconds (e.g., 10, 60, 120) |

This parameter is useful for applications requiring additional time to shut down properly, such as those with active user sessions or complex cleanup processes.

How often (in seconds) to poll ECS for service updates(to inject into the app logs.

| Default value | 1 |

Enable encryption at rest for EBS volumes.

| Default value | No | | Allowed values | Yes, No |

Encrypt secrets with KMS.

| Default value | Yes | | Permitted values | Yes, No |

Existing VPC-ID from AWS, if blank a VPC will be created. Additional paramater InternetGateway must be set to use ExistingVPC.

| Default value || | Permitted values |VPC ID|

Enable s3 bucket versioning. This affects all the buckets created for this rack.

| Default value | Suspended | | Allowed values | Enabled, Suspended |

Enable container readonly root filesystem. Enabling this will remove write access to the root filesystem.

| Default value | No | | Allowed values | Yes, No |

This will enable AWS KMS encryption on the default shared EFS volume used for application volumes.

| Default value | false | | Allowed values | true, false |

Important: Enabling EnableSharedEFSVolumeEncryption will recreate the EFS volume and all application's shared volume data will be lost. To preserve data, it is crucial to follow these steps:
  • Backup: Use AWS Backup or a similar tool to create a snapshot of the existing Amazon EFS volume, ensuring all current data is securely copied.
  • Restore: After enabling encryption, restore your data from the backup snapshot to the new encrypted EFS volume.
This parameter cannot be changed after the rack is created.

Whether or not enable High Availability mode, choose between failure resiliency and cost efficiency. This ensure proper resources redundancy to mitigate system failures.

If HighAvailability is set to true, the InstanceCount is used as initial cluster size. If false, the NoHaInstanceCount is used as initial cluster size. Both can be scaled to 1000 instances.

| Default value | true | | Allowed values | true, false |

HTTP proxy for outbound HTTP connections (for network-restricted Racks).

Set this value to the hostname (or IP address) and port number of an HTTP proxy to use for the ECS agent to connect to the internet.

| Default value | |

For more information, see HTTP Proxy Configuration in the AWS docs.

The HttpProxyparam will not change how the apps access the internet, the traffic won’t go through the proxy. Only the instances requests will use the proxy for outbound connections, if you want your apps to use the proxy, you have to configure it on the convox.yml:

services:
  web:
    build: .
    port: 3000
    environment:
      - http_proxy=10.0.1.124:8888
      - https_proxy=10.0.1.124:8888
      - HTTP_PROXY=10.0.1.124:8888
      - HTTPS_PROXY=10.0.1.124:8888
      - NO_PROXY=169.254.170.2

Specifies the maximum number of network hops that PUT response packets are allowed to travel from the EC2 instance metadata service (IMDS) to the requesting instance. This parameter is particularly relevant when IMDSHttpTokens is set to required, ensuring enhanced security by enforcing IMDSv2.

| Default value | 1 | | Allowed values | Numerical values (e.g., 1, 2) |

When IMDSHttpTokens is set to required, some configurations may require increasing the IMDSHttpPutResponseHopLimit to ensure proper functionality. If encountering connectivity issues with applications requiring IMDSv2, consider setting IMDSHttpPutResponseHopLimit to 2. This adjustment helps facilitate necessary communications with the instance metadata service.
Note: Adjusting the IMDSHttpPutResponseHopLimit above the default value should be done with understanding of your network topology and the security implications. Always verify that changes do not compromise your instance's security posture.

Set how your instances will access the instance metadata. You can set EC2 instances to use only v2 by setting IMDSHttpTokens as ‘required’, see Configure the instance metadata options.

| Default value | optional | | Allowed values | optional, required |

To auto include build and instances ips to whitelist when rack is public and whitelist is enabled.

| Default value | Both | | Allowed values | Both , Build, Workload, None` |

A single line of shell script to run (as root) as a cloud-init command early during instance boot.

For more information about using cloud-init with EC2, see the AWS doc Running Commands on Your Linux Instance at Launch. For cloud-init specifics, see “bootcmd” in the doc Run commands on first boot.

The InstanceBootCommand will also apply to any build instance associated with the Rack.

| Default value | |

Example: increase virtual memory

Tell the host EC2 instance to set operating system limits on mmap to 262144 (useful for ElasticSearch):

$ convox rack params set 'InstanceBootCommand="sysctl -w vm.max_map_count=262144"'
Updating parameters... OK

(Note the surrounding single quotes in the above command.)

The number of EC2 instances in your Rack cluster. This parameter is only used for clusters with HighAvailablity = true.

| Default value | 3 | | Minimum value | 3 |

ARN of an additional IAM policy to add to the instance-level role.

| Default value | |

A single line of shell script to run as a cloud-init command late during instance boot.

For more information about using cloud-init with EC2, see the AWS doc Running Commands on Your Linux Instance at Launch. For cloud-init specifics, see “runcmd” in the doc Run commands on first boot.

The InstanceRunCommand will also apply to any build instance associated with the Rack.

| Default value | |

The type of EC2 instance to run in your Rack cluster.

| Default value | t2.small | | Allowed values | EC2 Instance Types |

See also the BuildInstance Rack parameter.

The number of instances to update in a batch.

| Default value | 1 | | Minimum value | 1 |

Enable the internal load balancer for this Rack. See Internal Services

| Default value | No | | Allowed values | Yes, No |

If installing rack on existing VPC, you need to pass existing InternetGateway ID attached to the VPC. See ExistingVPC.

| Default value | |

SSH key name for access to cluster instances.

| Default value | |

The idle timeout value for the ALB, in seconds. The valid range is 1-4000 seconds.

| Default value | 3600 |

Log driver used by the rack and services to send logs. Default to CloudWatch. You must provide the SyslogDestination when setting as Syslog. It disable logs if blank.

Attention!! Disabling CloudWatch will impact convox logs and convox rack logs. Use Syslog resource if you still want to use convox logs, see Resource Syslog

| Default value | CloudWatch | | Allowed values | CloudWatch, Syslog, |

Number of days to keep logs (blank for unlimited). Possible values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 2192, 2557, 2922, 3288, and 3653. See Logs retention.

| Default value | 7 |

To maintain the state of timer if it’s disabled/enabled in AWS console event rule. After deploying the timer, if you disable the timer in the AWS console event rule, this will keep it disabled unless it is recreated. By default it is not maintained explicitly and the behaviour of the timer state change(if you disable event rule in the AWS console) will be depened on the cloudformation.

| Default value | No | | Allowed values | Yes, No |

The maximum number of Availability Zones that the cluster should use.

| Default value | 3 | | Allowed values | 2, 3 |

Specifies the number of extra instances to maintain when autoscaling is enabled, but only applies when HighAvailability is set to false.

| Default value | 1 |

This functions similarly to the AutoscaleExtra parameter but is used exclusively in non-HA configurations.

The number of EC2 instances in your non High Availability Rack cluster. It’s only used for non high available clusters.

| Default value | 1 | | Minimum value | 1 |

If using spot instances through the SpotInstanceBid parameter, this configures the minimum number of on demand instances. This should be set to a value that will guarantee the minimum acceptable service availability. You must set it even if you using the HighAvailability as false, as this will be used to create the minimum on demand instances.

| Default value | 3 |

(REQUIRED) API HTTP password.

| Minimum length | 1 | | Maximum length | 50 |

Place convox related lambdas in vpc if rack is private.

| Default value | No | | Allowed values | Yes, No |

Suffix for internal router domain

| Default value | -rti |

Have the Rack create non-publicly routable resources, i.e. in a private subnet. See our Private Networking doc for more information.

| Default value | No | | Allowed values | Yes, No |

Put Rack API Load Balancer in a private network, i.e. have the Rack API use an Internal ELB, making it unreachable from the internet.

| Default value | No | | Allowed values | Yes, No |

Specify a custom security group that can connect to the Rack API when PrivateApi=Yes.

| Default value | |

Place only the build instances into a private network (unused if Private is Yes)

| Default value | No | | Allowed values | Yes, No |

To prune docker images older than this specified hours.

| Default value | 96 |

Cron frequecy to prune docker older images.

| Default value | daily | | Allowed values | hourly, daily, weekly |

Determines how the load balancer handles requests that might pose a security risk to your application. See here for more information.

| Default value | defensive | | Allowed values | defensive, monitor, strictest |

Specify a custom security group to use for the Rack’s router.

| Default value | |

Use ScheduleRackScaleDown & ScheduleRackScaleUp if you want to turn the rack on/off based on a schedule. Keep in mind that both parameters need to be set. To turn your rack off on weekends and back on during weekdays you can use:

convox rack params set ScheduleRackScaleDown="0 18 * * 5" ScheduleRackScaleUp="0 9 * * 1"

The supported cron expression format consists of five fields separated by white spaces: [Minute] [Hour] [Day_of_Month] [Month_of_Year] [Day_of_Week]. In the example above it’s configured to shutdown every Friday (5th day) at 6pm (UTC). More details on the CRON format can be found in Crontab and examples.

You can see details about the Scheduling Actions on AWS doc.

| Default value | |

A value, in dollars, that you want to pay for spot instances. If spot instances are available for the bid price, the Rack instances will use spot instances instead of on demand instances, resulting in significant cost savings. If the parameter is empty, spot instances will not be utilized. This must be used with the OnDemandMinCount parameter to guarantee some on demand instances are running if spot instances are not available (even if the HighAvailability is false, if not set will use the default).

| Default value | |

Comma-separated list of allowed instance types in the Spot Fleet. It can not be used with SpotFleetExcludedInstanceTypes, it takes precedent over it. The following are examples: m5.8xlarge, c5., m5a., r, 3. This parameter can be used only when SpotFleet is enabled.

| Default value | |

Comma-separated list of excluded instance types in the Spot Fleet. . It can not be used with SpotFleetAllowedInstanceTypes. The following are examples: m5.8xlarge, c5., m5a., r, 3. This parameter can be used only when SpotFleet is enabled.

| Default value | |

The Spot Fleet allocation strategy. This parameter can be used only when SpotFleet is enabled.

| Allowed values | lowestPrice, diversified, capacityOptimized |

| Default value | lowestPrice |

The maximum price for instances in the Spot Fleet per hour. It will try to launch instances untill it crosses the price even if target InstanceCount or NoHaInstanceCount is not fullfilled. Setting this parameter will enable spotfleet which will use the AWS Spot request to fullfill the instance demand and will be manage by the spot request(not autoscaling group). Currently this has only single zone support even if you set HighAvailability to true. SpotFleetMinOnDemandCount will be used to lauch ondemand instances along with these spot instances.

Spot fleet’s min memory in MiB. This parameter can be used only when SpotFleet is enabled.

| Default value | 1000 |

Spot fleet’s min vcpu count. This parameter can be used only when SpotFleet is enabled.

| Default value | 0 |

Spot fleet’s minimum on demand instance count. Instance type will taken from InstanceType param. This parameter can be used only when SpotFleet is enabled.

| Default value (if HighAvailability disabled) | 1 |

| Default value (if HighAvailability enabled) | 2 |

The unit type used for the Spot Fleet target capacity. This parameter can be used only when SpotFleet is enabled.

| Allowed values | memory-mib, units, vcpu |

| Default value | units |

Specify an SSL policy for the primary Rack load balancer.

| Default value | |

| Allowed values | ELB SSL Policies |

Public Subnet 0 CIDR Block.

| Default value | 10.0.1.0/24 |

Public Subnet 1 CIDR Block.

| Default value | 10.0.2.0/24 |

Public Subnet 2 CIDR Block.

| Default value | 10.0.3.0/24 |

Private Subnet 0 CIDR Block.

| Default value | 10.0.4.0/24 |

Private Subnet 1 CIDR Block.

| Default value | 10.0.5.0/24 |

Private Subnet 2 CIDR Block.

| Default value | 10.0.6.0/24 |

Default swap volume size in GB. Set this value to 0 to disable swap.

| Default value | 5 |

Syslog address destination, you need to pass the protocol to be used, e.g. tcp+tls://logsX.syslog.com:1234.

| Default value | |

Syslog format (low case) to sent to SyslogDestination. See Docker Syslog and RFC5424.

| Default value | rfc5424 |

Custom tags to add with AWS resource

| Default value | | | Format | <key>=<val>,<key>=<val>. example: key1=val1,key2=val2 |

Dedicated hardware.

| Default value | default | | Allowed values | default, dedicated |

(REQUIRED) Convox release version.

| Minimum length | 1 |

Default disk size (in gibibytes) of the EBS volume attached to each EC2 instance in the cluster.

| Default value | 50 |

VPC CIDR Block. Note that changing this has no effect since VPC CIDR ranges cannot be changed after they’re created.

| Default value | 10.0.0.0/16 |

Comma delimited list of CIDRs, e.g. 10.0.0.0/24,172.10.0.1/32, to allow access to the rack api.

Attention!! Please be careful to consider all required connections to the rack API before enabling Whitelist. You can block your access and ability to edit this parameter from CLI again if misconfigured.

| Default value | |