Configuring your application
Configure the deployment options for your applications

Passing config to run

The run command requires you to provide a toml based configuration file. This file controls the resources that the scheduler uses, how machines are dynamically scaled, and what features are enabled.
The available configuration options are shown in an example configuration file below, which is available in your install as ~/hadean/examples/configs/config.toml
1
args = "test"
2
3
# Machine settings - these are cloud specific and apply to all
4
# the members of your cluster.
5
# These are not available in the freemium version.
6
machine_class = "c6i.2xlarge"
7
# machine_class = "Standard_A8_v2"
8
disk_class = "gp2"
9
# disk_class = "Standard_LRS"
10
disk_size = "80"
11
12
# Environment variables passed to your application
13
[env]
14
key = "value"
15
16
[requirements]
17
# Number of cores each user process uses, affects scheduling and
18
# machine allocation
19
cores = "1/16"
20
# Amount of memory required by each user process, same as above
21
memory = "8 MiB"
22
23
[tools]
24
# These features are not available in the freemium version of the
25
# Hadean SDK
26
tracing_enabled = false
27
debugging_enabled = false
28
metrics_enabled = false
29
30
[cluster]
31
# The number of machines to allocate in preparation for scaling up.
32
# 0 = always allocate just in time
33
# 1 = keep a VM around between runs that makes rapid iteration easier
34
# 2+ = keep n VMs around between runs and always keep n-1 VMs on hand
35
# ready to use while your application is scaling
36
standby_machines = 1
37
# The time (in seconds) after which all standby machines will be
38
# deallocated after an application has stopped.
39
machines_timeout = 3600
40
41
[[inbound-rules]]
42
# Inbound firewall rules that specify ports and protocols you want to have open.
43
# This rule would open ports 80, 443, and 8080 through 8100 for TCP.
44
ports = "80,443,8080:8100"
45
protocol = "TCP"
46
# The source CIDR block specifies where the traffic is allowd to come from.
47
# 0.0.0.0/0 is all IPv4 traffic from anywhere on the internet.
48
source = "0.0.0.0/0"
49
50
[[inbound-rules]]
51
# You can add more rules by having multiple blocks.
52
# This rule would open ports 12000 through 12100 for UDP.
53
ports = "12000:12100"
54
# Currently only "TCP" and "UDP" are supported.
55
protocol = "UDP"
56
# CIRD blocks can also be IPv6!
57
source = "::/0"
58
59
[[outbound-rules]]
60
# Outbound firewall rules that specify ports and protocols you want to have open.
61
ports = "12000:12100"
62
protocol = "UDP"
63
# Outbound firewall rules are filtered by destination instead of source,
64
# specifying where traffic is allowed to go to outside the network.
65
destination = "::/0"
Copied!

Application arguments

The args setting controls what arguments are passed to the user binary. For environment variables, see: Hints, Tips, and Troubleshooting

Machine spec

The machine_class, disk_class, and disk_size options can be used (only in the licensed version) to specify what kind of machines to deploy when dynamically scaling.
The configuration you set here has no impact on the behaviour of the machine builder API, so that can still be used to create arbitrary machines at runtime.
Setting
Description
machine_class
Controls the type of machine that is deployed, impacting the number of vCPUs and the amount of memory available per machine.
disk_class
What type of storage is used by machines in the cluster.
disk_size
The total amount of disk space (as a number of gigabytes) available to a machine in the cluster (only available in AWS).

Supported Machine Classes

Azure
AWS
  • Standard_A1_V2
  • Standard_A2_V2
  • Standard_A4_V2
  • Standard_A8_V2
  • Standard_A2m_V2
  • Standard_A4m_V2
  • Standard_A8m_V2
  • m5.xlarge
  • m5.2xlarge
  • m5.4xlarge
  • m5.8xlarge
  • m5.12xlarge
  • m5.16xlarge
  • m5.24xlarge
  • m5.metal
  • m5d.large
  • m5d.xlarge
  • m5d.2xlarge
  • m5d.4xlarge
  • m5d.8xlarge
  • m5d.12xlarge
  • m5d.16xlarge
  • m5d.24xlarge
  • m5d.metal
  • m5a.large
  • m5a.xlarge
  • m5a.2xlarge
  • m5a.4xlarge
  • m5a.8xlarge
  • m5a.12xlarge
  • m5a.16xlarge
  • m5a.24xlarge
  • m5ad.large
  • m5ad.xlarge
  • m5ad.2xlarge
  • m5ad.4xlarge
  • m5ad.8xlarge
  • m5ad.12xlarge
  • m5ad.16xlarge
  • m5ad.24xlarge
  • m5n.large
  • m5n.xlarge
  • m5n.2xlarge
  • m5n.4xlarge
  • m5n.8xlarge
  • m5n.12xlarge
  • m5n.16xlarge
  • m5n.24xlarge
  • m5n.metal
  • m5dn.large
  • m5dn.xlarge
  • m5dn.2xlarge
  • m5dn.4xlarge
  • m5dn.8xlarge
  • m5dn.12xlarge
  • m5dn.16xlarge
  • m5dn.24xlarge
  • m5dn.metal
  • m5zn.large
  • m5zn.xlarge
  • m5zn.2xlarge
  • m5zn.3xlarge
  • m5zn.6xlarge
  • m5zn.12xlarge
  • m5zn.metal
  • m4.large
  • m4.xlarge
  • m4.2xlarge
  • m4.4xlarge
  • m4.10xlarge
  • m4.16xlarge
  • c5.large
  • c5.xlarge
  • c5.2xlarge
  • c5.4xlarge
  • c5.9xlarge
  • c5.12xlarge
  • c5.18xlarge
  • c5.24xlarge
  • c5.metal
  • c5d.large
  • c5d.xlarge
  • c5d.2xlarge
  • c5d.4xlarge
  • c5d.9xlarge
  • c5d.12xlarge
  • c5d.18xlarge
  • c5d.24xlarge
  • c5d.metal
  • c5a.large
  • c5a.xlarge
  • c5a.2xlarge
  • c5a.4xlarge
  • c5a.8xlarge
  • c5a.12xlarge
  • c5a.16xlarge
  • c5a.24xlarge
  • c5ad.large
  • c5ad.xlarge
  • c5ad.2xlarge
  • c5ad.4xlarge
  • c5ad.8xlarge
  • c5ad.12xlarge
  • c5ad.16xlarge
  • c5ad.24xlarge
  • c5n.large
  • c5n.xlarge
  • c5n.2xlarge
  • c5n.4xlarge
  • c5n.9xlarge
  • c5n.18xlarge
  • c5n.metal
  • c4.large
  • c4.xlarge
  • c4.2xlarge
  • c4.4xlarge
  • c4.8xlarge
  • r5.large
  • r5.xlarge
  • r5.2xlarge
  • r5.4xlarge
  • r5.8xlarge
  • r5.12xlarge
  • r5.16xlarge
  • r5.24xlarge
  • r5.metal
  • r5d.large
  • r5d.xlarge
  • r5d.2xlarge
  • r5d.4xlarge
  • r5d.8xlarge
  • r5d.12xlarge
  • r5d.16xlarge
  • r5d.24xlarge
  • r5d.metal
  • r5a.large
  • r5a.xlarge
  • r5a.2xlarge
  • r5a.4xlarge
  • r5a.8xlarge
  • r5a.12xlarge
  • r5a.16xlarge
  • r5a.24xlarge
  • r5ad.large
  • r5ad.xlarge
  • r5ad.2xlarge
  • r5ad.4xlarge
  • r5ad.8xlarge
  • r5ad.12xlarge
  • r5ad.16xlarge
  • r5ad.24xlarge
  • r5b.large
  • r5b.xlarge
  • r5b.2xlarge
  • r5b.4xlarge
  • r5b.8xlarge
  • r5b.12xlarge
  • r5b.16xlarge
  • r5b.24xlarge
  • r5b.metal
  • r5n.large
  • r5n.xlarge
  • r5n.2xlarge
  • r5n.4xlarge
  • r5n.8xlarge
  • r5n.12xlarge
  • r5n.16xlarge
  • r5n.24xlarge
  • r5n.metal
  • r5dn.large
  • r5dn.xlarge
  • r5dn.2xlarge
  • r5dn.4xlarge
  • r5dn.8xlarge
  • r5dn.12xlarge
  • r5dn.16xlarge
  • r5dn.24xlarge
  • r5dn.metal
  • r4.large
  • r4.xlarge
  • r4.2xlarge
  • r4.4xlarge
  • r4.8xlarge
  • r4.16xlarge
  • c6i.2xlarge
Don't see a machine class here that you want to use? Get in contact with us at: [email protected]

Supported Disk Classes

Azure
AWS
  • Standard_LRS
  • StandardSSD_LRS

Environment Variables

You can specify a key value map of environment variables using the [env] declaration. For example:
1
[env]
2
RUST_BACKTRACE = "full"
Copied!
Note that you cannot specify RUST_LOG here specifically, because this is currently controlled by the Hadean Global Logger.
If while running your application you pass the --debug flag, then RUST_LOG will be set to debug and RUST_BACKTRACE set to 1 in your applications environment variables automatically. Otherwise RUST_LOG will be set to info. The --debug argument will override these settings in this configuration file, but all other environment variables will be passed as normal.

The [requirements] section

The requirements section states what your application needs for it to be launched. In the freemium version, this also controls what resources are needed by each application that is created via the spawn API. However, the full API is capable of using spawn with arbitrary resource requirements.

The [tools] section

The tools section of the configuration controls what features are enabled on the platform. These features are not available in the freemium version of the platform.
AWS Configurations / Machine Data (Premium users only)
Supported machine config in AWS
Machine Types
m4
c4
r4
m5
c5
r5
Supported disk types:
Disk Classes
gp2
gp3
io1
io2
st1
sc1
Disk-size - Default 100 - unsigned integer 16
Azure Configurations / Machine Data (Premium users only)
Supported Machine Types
Machine Types
Standard_A1_v2
Standard_A2_v2
Standard_A4_v2
Standard_A8_v2
Standard_A2m_v2
Standard_A4m_v2
Standard_A8m
Azure Disk Classes
Disk Classes
Standard_LRS
StandardSSD_LRS

The [cluster] section

The cluster section of the configuration controls how the cluster scales:
  • standby_machines controls how many machines are provisioned ahead of time for scaling events.
  • machine_timeout controls how long the system should stay idle running no application before it starts removing standby machines.
For faster dev & test iteration, it's recommended to keep your standby_machines at 1 or above, which will ensure that you don't have to wait to scale up or down every time you use the run command. If your application needs to scale rapidly, you should set standby_machines to at least 2, so that the platform begins creating a new VM once all VMs are in use.

Firewall Rules

Inbound rules specify ports that you want to be open for incoming traffic into the cluster's dynamic network. For example, when creating a web server you might want to have ports 80 and 443 open.
Outbound rules specify ports that you want to be open for outgoing traffic from the cluster's dynamic network. For example, when creating a web server you might want to have ports 80 and 443 open.
An inbound rule is specified with the fields ports, protocol, and source. An outbound rule is specified with the fields ports, protocol, and destination.
Multiple [[inbound-rules]] and [[outbound-rules]] blocks can occur in the same configuration file, where each time it appears you are specifying one additional rule. In your cloud provider, each rule may be represented as multiple rules, when using comma separated lists for ports.
Any ports not specified in these configuration opens are by default closed. Traffic within the network (such as inter-process communication) is always open for all ports and protocols.
Field
Description
ports
The ports to open. This is a comma separated list of port ranges such as 80,443,8080:8100. A port range can be a single port such as 80, or a range of ports separated with a colon such as 8080:8100.
protocol
The protocol to open the ports from. May only be TCP or UDP.
source
The source to allow traffic from for inbound rules only. Specified as a CIDR block in either IPv4 or IPv6.
destination
The destination to allow traffic out to for outbound rules only. Specified as a CIDR block in either IPv4 or IPv6.

AWS

Region

When creating new clusters in AWS to deploy your application to, the Hadean Platform needs to know which geographic region to provision them in. The --location argument has the aliases -l and --region, but all of these can be used to specify which AWS region you want to deploy into:
1
hadean cluster --name <cluster-name> create --region eu-west-2
Copied!
You can also set a default for all new clusters by using the config command:
1
hadean config --default-location <region>
Copied!

Availability Zone

In AWS, VMs must be deployed into specific availability zones. Most regions have three availability zones; a, b, and c. While some have different configurations. Once you know which zone you want to deploy into, that also needs to be specified using the --availability-zone argument, along with region.
1
hadean cluster --name <cluster-name> create --zone eu-west-2a
Copied!
You can also set a default for all new clusters by using the config command:
1
hadean config --default-avilability-zone <zone>
Copied!

Domain Name

It is not possible to use Let's Encrypt to obtain a certificate for an EC2 AWS public domain name, as Let's Encrypt have added amazonaws.com to their high risk domain list. For now, this means that you must register your own domain name for AWS clusters.
To integrate with our platform deployment, the domain you specify in the --domain-name argument must be the exact name of a hosted zone in AWS Route53. The deployment will then automatically register a Route53 record set as a subdomain of the hosted zone with the cluster name and key. For example:
1
hadean cluster --name simulation create --domain hadean.com
Copied!
This will create a subdomain using part of the name, and part of the cluster key. It might look like simula-123456.mycompanyname.com, depending on the key that the cluster gets when it is created. Once created, we then use Let's Encrypt to obtain a certificate for the subdomain. Note that this means that clusters created within this domain are subject to Let's Encrypt's rate limits, the most important of which is no more than 50 registrations per registered domain per week.
In the future we plan to restore parity between all available platforms here, so this requirement will instead become an option.

Azure

Location

When creating new clusters in Azure to deploy your application to, the Hadean Platform needs to know which geographic region to provision them in. Use the --location argument to pass a location from the list below.:
1
hadean cluster --name <cluster-name> create --location uksouth
Copied!
You can also set a default for all new clusters by using the config command:
1
hadean config --default-location <location>
Copied!
The following Azure locations are available:
  • westeurope
  • uksouth
  • centralus
  • eastus
  • eastus2
  • northcentralus
  • southcentralus
  • westcentralus
  • westus
  • westus2
  • australiaeast
  • southeastasia
  • eastasia
AWS supported regions & availability zones:
RegionName
AvailabilityZones
ap-northeast-1
ap-northeast-1a ap-northeast-1c ap-northeast-1d
ap-northeast-2
ap-northeast-2a ap-northeast-2b ap-northeast-2c ap-northeast-2d
ap-northeast-3
ap-northeast-3a ap-northeast-3b ap-northeast-3c
ap-south-1
ap-south-1a ap-south-1b ap-south-1c
ap-southeast-1
ap-southeast-1a ap-southeast-1b ap-southeast-1c
ap-southeast-2
ap-southeast-2a ap-southeast-2b ap-southeast-2c
ca-central-1
ca-central-1a ca-central-1b ca-central-1d
eu-central-1
eu-central-1a eu-central-1b eu-central-1c
eu-north-1
eu-north-1a eu-north-1b eu-north-1c
eu-west-1
eu-west-1a eu-west-1b eu-west-1c
eu-west-2
eu-west-2a eu-west-2b eu-west-2c
eu-west-3
eu-west-3a eu-west-3b eu-west-3c
sa-east-1
sa-east-1a sa-east-1b sa-east-1c
us-east-1
us-east-1a us-east-1b us-east-1c us-east-1d us-east-1e us-east-1f
us-east-2
us-east-2a us-east-2b us-east-2c
us-west-1
us-west-1a us-west-1c
us-west-2
us-west-2a us-west-2b us-west-2c us-west-2d

Analytics

You can turn analytics tracking on or off using the hadean config command. Simply specify true or false as follows:
1
# Turn analytics off
2
hadean config --analytics false
3
4
# Turn analytics on
5
hadean config --analytics true
Copied!
The analytics data we collect is minimal. You can see tracing for when we send analytics requests via the --debug flag on any command. Analytics are on by default.