ALM v3.0
WebsiteRepoTech blog (JP)Tech blog (EN)

Reference (2017-03-03)

Template structure

Below is a tree view of all possible components within an ALM Template. The following structure is not a working demo template, but rather to explain all possible key names that may contain in the template body.

version: string
label: string
description: string
vendor: object
  aws: object
  azure: object
  gcp: object
  alicloud: object
  k5: object
configurations: array of objects
  role: string
  flag: string
  provision: object
    vpc_id: string
    availability_zone: string
    instance_type: string
    image: string
    instance_count: number
    volume_type: string
    volume_size: number
    keypair: boolean
    subnet: object
    security_group: object
    network_acl: object
    load_balancer: object
    auto_scaling: object
  container: object
    container_image: string
    container_registry_username: string
    container_registry_password: string
    container_code_dir: string
    container_code_repo: string
    container_git_reference: string
    container_git_private_key: string
    container_ports: array of numbers
    container_users: object
    container_env_vars: object

version

The version of ALM Template release. This value is always 2017-03-03.

label

The label of the ALM Template. You can use this section to mark the labels for each of your ALM Template versions. This is useful when you update your template. This value can be empty, and you can write up to 64 characters in length.

description

The description of the ALM Template. You can use this section to describe the purpose of the ALM Template. For example: production app stack. This value can be empty, and you can write up to 255 characters in length.

vendor

The cloud platform vendor of which the template will be deployed to. You need to specify the vendor in every ALM Template you write, and can only specify one vendor at a time.

Valid values:

cred: ALM credential name created under AWS vendor region: vendor region for your deployment

"vendor": {
    "aws": {
      "cred": "change this to your AWS Security Key ID",
      "region": "ap-northeast-1"
    }
}

configurations

The configurations of the stack which ALM Template is about to deploy. In the configurations section, you specify one or multiple configuration layers of your application's provision and container runtime settings. Inside each layer, there are four sections you need to specify:

role

The "role" of which the stack layer defines to.

You deploy multiple layers within one ALM Template, for example two web layers, one bastion layer and one database layer. The current available role names:

  • web

  • bastion

flag

The unique identifier of each layer.

You must specify the flag name for each configuration layer. The value must between 4 to 18 characters in length and contains only alphanumeric characters.

provision

The infrastructure provisioning configurations.

vpc_id

Reserved key name, not supported yet.

Currently, a new VPC will be created with every ALM Template execution and the default VPC has a fixed CIDR range of 10.0.0.0/16 and you cannot customize it at the moment, so when you specifying your subnets please make sure the CIDR setting for your subnets are sitting within the VPC CIDR range.

For GCP, all deployments use the region's default public network. For GCP's predefined network ranges, you can refer to this page.

availability_zone

Type

Required

Description

string

Yes

The availability zone of which the stack deploys to. You must specify this value in your ALM Template.

Valid values:

"availability_zone": "ap-northeast-1c"

Below are the valid availability zones for each regions on AWS.

    (North Virginia)
    us-east-1a
    us-east-1b
    us-east-1c
    us-east-1d
    us-east-1e

    (Ohio)
    us-east-2a
    us-east-2b
    us-east-2c

    (North Carolina)
    us-west-1b
    us-west-1c

    (Oregon)
    us-west-2a
    us-west-2b
    us-west-2c

    (Canada)
    ca-central-1a
    ca-central-1b

    (Ireland)
    eu-west-1a
    eu-west-1b
    eu-west-1c

    (Frankfurt)
    eu-central-1a
    eu-central-1b

    (London)
    eu-west-2a
    eu-west-2b

    (Singapore)
    ap-southeast-1a
    ap-southeast-1b

    (Sydney)
    ap-southeast-2a
    ap-southeast-2b
    ap-southeast-2c

    (Seoul)
    ap-northeast-2a
    ap-northeast-2c

    (Tokyo)
    ap-northeast-1a
    ap-northeast-1c

    (Mumbai)
    ap-south-1a
    ap-south-1b

    (Sao Paulo)
    sa-east-1a
    sa-east-1b
    sa-east-1c

instance_type

The type of instances (VMs). If value is not provided in the template, the default values will be used for each cloud platform.

Valid values:

Default: t2.micro

"instance_type": "t2.micro"

Below are the valid instance types for AWS.

    t2.nano
    t2.micro [default]
    t2.small
    t2.medium
    t2.large
    t2.xlarge
    t2.2xlarge
    m4.large
    m4.xlarge
    m4.2xlarge
    m4.4xlarge
    m4.10xlarge
    m4.16xlarge
    m3.medium
    m3.large
    m3.xlarge
    m3.2xlarge
    c5.large
    c5.xlarge
    c5.2xlarge
    c5.4xlarge
    c5.9xlarge
    c5.18xlarge
    c4.large
    c4.xlarge
    c4.2xlarge
    c4.4xlarge
    c4.8xlarge
    c3.large
    c3.xlarge
    c3.2xlarge
    c3.4xlarge
    c3.8xlarge
    x1.16large
    x1.32xlarge
    x1e.xlarge
    x1e.2xlarge
    x1e.4xlarge
    x1e.8xlarge
    x1e.16xlarge
    x1e.32xlarge
    r4.large
    r4.xlarge
    r4.2xlarge
    r4.4xlarge
    r4.8xlarge
    r4.16xlarge
    r3.large
    r3.xlarge
    r3.2xlarge
    r3.4xlarge
    r3.8xlarge
    p3.2xlarge
    p3.8xlarge
    p3.16xlarge
    p2.xlarge
    p2.8xlarge
    p2.16xlarge
    g3.4xlarge
    g3.8xlarge
    g3.16xlarge
    f1.2xlarge
    f1.16xlarge
    i3.large
    i3.xlarge
    i3.2xlarge
    i3.4xlarge
    i3.8xlarge
    i3.16large
    d2.xlarge
    d2.2xlarge
    d2.4xlarge
    d2.8xlarge

image

Type

Required

Description

string

no

The machine image (id) used to launch the instance.

Default values will be applied for each cloud platform (see below for default values). However, you can also specify this value for launching with a customized machine image.

Note: If you specify this value and also specify the container section in the ALM Template to take the advantage of application lifecycle management, you need to make sure the base machine image operating system supports ALM-agent installation. For supported operating systems by ALM-agent, please refer to this guide.

Valid values:

Below is also the default value for AWS.

    "image": "ami-2a69be4c"

instance_count

Type

Required

Description

int

no

Number of instances (VMs) to provision. This is only applicable to non-autoscaled stacks.For autoscaled stacks, see auto_scaling section.

If you don't specify this declarative, the default value of 1 will be applied.

Valid values:

    "instance_count": 1

volume_type

Type

Required

Description

string

no

The volume type of instance.

Valid values:

If you don't specify this declarative, the default value of gp2 will be applied.

    gp2 - General Purpose SSD
    io1 - Provisioned IOPS SSD
    st1 - Throughput Optimized HDD
    sc1 - Cold HDD
    standard - Magnetic volumes

volume_size

Type

Required

Description

string

no

The size of the volume, in gibibytes (GiBs).

Valid values:

    Constraints: 1-16384 for gp2, 4-16384 for io1, 500-16384 for st1, 500-16384 for sc1, and 1-1024 for standard (magnetic disk).

    Default volume size in GB for each volume types:

    - gp2: 50
    - io1: 50
    - st1: 500
    - sc1: 500
    - standard: 50

keypair

The ssh key pair used to access instances.

Type

Required

Description

boolean

no

Enable SSH key pair to be used to access instances. Default value is true.

subnet

Type

Required

Description

object

no

The subnet settings.

A subnet section contains 3 key names.

  • cidr (string)

    The IPv4 CIDR block that you want the subnet to cover (for example, "10.0.0.0/24").

    Required: No

    If you don't specify this declarative, the default CIDR block settings will be applied. See below for default values on each cloud platform.

  • public (boolean)

    Defines whether this subnet is public or private. This value is either true or false.

    If you don't specify this declarative, the default value of true will be applied.

    Required: No

  • auto_assign_public_ip (boolean)

    Defines whether automatically assigns a public IP when instance launched into the subnet. This value is either true or false.

    Required: No

    If you don't specify this declarative, the default value of true will be applied.

    If you set public as false, then this declarative will be ignored.

Valid values:

Example below is also the default settings when deploying to AWS.

"subnet": {
  "cidr": "10.0.0.0/24",
  "public": true,
  "auto_assign_public_ip": true
}

network_acl

The network action control list for a virtual private cloud. This section supports AWS only.

Type

Required

Description

array

no

The network action control list for a virtual private cloud. This section supports AWS only.

A network_acl section contains a list of network_acl entry items. Each item contains the following declaratives:

  • rule_number (int)

    Rule number to assign to the entry, such as 100. ACL entries are processed in ascending order by rule number. Entries can't use the same rule number unless one is an egress rule and the other is an ingress rule.

    Required: Yes

    For more on valid values, please refer to this guide on aws documentation site.

  • protocol (string)

    The IP protocol that the rule applies to. You must specify -1 or a protocol number. You can specify -1 for all protocols.

    Required: Yes

    For more on protocol numbers, please refer to this guide.

  • rule_action (string)

    Whether to allow or deny traffic that matches the rule; valid values are "allow" or "deny".

    Required: Yes

  • acl_egress (boolean)

    Whether this rule applies to egress traffic from the subnet (true) or ingress traffic to the subnet (false).

    Required: No

    If you don't specify this declarative, the default value of false will be applied.

  • cidr_block (string)

    The IPv4 CIDR range to allow or deny, in CIDR notation (e.g., 172.16.0.0/24).

    Required: Yes

For more information about network acl please refer to AWS Documentation

Valid values:

Example below is also the default settings when deploying to AWS.

"network_acl": [
  {
    "rule_number": 100,
    "protocol": "-1",
    "rule_action": "allow",
    "cidr_block": "0.0.0.0/0"
  },
  {
    "rule_number": 100,
    "protocol": "-1",
    "rule_action": "allow",
    "acl_egress": false,
    "cidr_block": "0.0.0.0/0"
  }
]

security_group

Type

Required

Description

object

no

The security groups for your virtual private cloud. Security groups are associated with network interfaces and acts as a virtual firewall that controls the traffic for one or more instances.

A security group section contains two entry items, ingress and egress.

  • ingress (array)

  • egress (array)

Each ingress or egress contains the following 4 declarative:

  • cidr_ip (string)

    An IPv4 CIDR range.

    Required: Yes

    (For more information on cidr calculations, there are tools like this to helping you get started.)

  • from_port (int)

    Start of port range for the TCP and UDP protocols, or an ICMP type number. If you specify icmp for the IpProtocol property, you can specify -1 as a wildcard (i.e., any ICMP type number).

    Required: Yes

  • ip_protocol (string)

    IP protocol name or number.

    Required: Yes

  • to_port (int)

    End of port range for the TCP and UDP protocols, or an ICMP code. If you specify icmp for the IpProtocol property, you can specify -1 as a wildcard (i.e., any ICMP code).

    Required: Yes

Valid values:

Example below is also the default settings when deploying to AWS.

"security_group": {
        "ingress": [
            {
                "cidr_ip": "0.0.0.0/0",
                "from_port": 80,
                "ip_protocol": "tcp",
                "to_port": 80
            },
            {
                "cidr_ip": "0.0.0.0/0",
                "from_port": 443,
                "ip_protocol": "tcp",
                "to_port": 443
            },
            {
                "cidr_ip": "0.0.0.0/0",
                "from_port": 22,
                "ip_protocol": "tcp",
                "to_port": 22
            }
        ],
        "egress": [
            {
                "cidr_ip": "0.0.0.0/0",
                "from_port": 0,
                "ip_protocol": "-1",
                "to_port": 65535
            }
        ]
    }

auto_scaling

Type

Required

Description

object, or string

no

The auto_scaling group defines the configuration to automatically scale up or down the number of compute resources that are being allocated to your application based on its needs at any given time.

If you are deploying an application type of load balancer (you define in load_balancer declarative), you can omit the required parameters below and use the ATL function #share to share the same auto scaling group which you defined in another layer. Click here for more on ATL functions.

ATL is only supported by AWS at the moment.

The auto_scaling section contains the following declarative:

  • min (int)

    The minimum size of the whole (total) autoscaling group.

    Required: No

    If you don't specify this declarative, the default value of 1 will be applied.

  • max (int)

    The maximum size of the whole (total) autoscaling group.

    Required: No

    If you don't specify this declarative, the default value of 1 will be applied.

  • spot_to_ondemand_ratio (int) The percentage of min/max values to deploy as spot/preemptible/low-priority instances. For example, if you have 10 as min and 100 as max, a spot_to_ondemand_ratio value of 60 (or 60 percent) will have the following results: Spot min: 6 (60% of 10) Spot max: 60 (60% of 100) On-demand min: 4 On-demand max: 40 For calculations that results to fractions, like 50% of 3, the results will be rounded off to the nearest integer such as 1.5 = 2, 3.9 = 4, 2.3 = 2, etc. For example, if you have a min value of 3 and 50 as spot_to_ondemand_ratio, you will have a minimum of 2 spot instances (50% of 3 is 1.5, rounded off to 2) and a single on-demand instance.

  • spot_min (int) [DEPRECATED]

    The minimum size of the spot instances in the autoscaling group. This key will still work with AWS- and GCP-based stacks. For other cloud vendors, please use spot_to_ondemand_ratio key.

    Required: No

  • spot_max (int) [DEPRECATED]

    The maximum size of the spot instances in the autoscaling group. This key will still work with AWS- and GCP-based stacks. For other cloud vendors, please use spot_to_ondemand_ratio key.

    Required: No

  • availability_zones (string)

    The list of availability zones for the Auto Scaling group.

    Required: Yes

  • cooldown (string)

    The number of seconds after a scaling activity is completed before any further scaling activities can start.

    Required: No

    If you don't specify this declarative, the default value of 360 will be applied.

  • healthcheck_grace_period (string)

    The length of time in seconds after a new instance comes into service that Auto Scaling starts checking its health.

    Required: No

    If you don't specify this declarative, the default value of 360 will be applied.

Valid values:

"auto_scaling": {
  "min": 1,
  "max": 1,
  "availability_zones": "${use(FlagName1.provision.availability_zone, FlagName2.provision.availability_zone)}",
  "cooldown": "360",
  "healthcheck_grace_period": "360"
}

load_balancer

Type

Required

Description

object

no

The load_balancer for the auto_scaling group.

The load balancer section contains the following declarative:

  • lb_type (string)

    Either classic, application or networking.

    In usual case, ALM creates the classic (standard) load balancer.

    On AWS specifically, you can also create the application load balancer and a networking load balancer. For more on these two AWS load balancer types, please refer to this guide.

    Required: No

    If you don't specify this declarative, the default value of classic will be applied.

  • scheme (string)

    Either internet-facing or internal.

    Specify internal to create an internal load balancer with a DNS name that resolves to private IP addresses or internet-facing to create a load balancer with a publicly resolvable DNS name, which resolves to public IP addresses.

    Required: No

    If you don't specify this declarative, the default value of internet-facing will be applied.

  • security_groups (string)

    Specifies a list of security groups assigned to this load balancer.

    Required: No

    Note: This value is in string type and can only be the reference to security_group section you defined in same or other layers. For example if you have two layers of configurations named "Layer1" and "Layer2", you can reference the security group defined in Layer2 to Layer1 by writing:

      { "security_groups": "#ref(Layer2.provision.security_group)"}

  • subnets (string)

    Specifies a list of subnets assigned to this load balancer defined in lb_type parameter above.

    Required: No

    Note: Only specify this value if you are deploying an ALB type of load-balancer.

    Note: This value is in string type and can only be the reference to subnet section you defined in same or other layers. For example if you have two layers of configurations named "Layer1" and "Layer2", you can reference the subnets to use both of them by:

      { "subnets": "#ref(Layer2.provision.subnet,Layer1.provision.subnet)"}

  • listeners (array)

    One or more listeners for this load balancer. Each listener must be registered for a specific port, and you cannot have more than one listener for a given port.

    Required: Yes. You must specify at least one entry item for this section.

    A listeners section contains a list of entry items with each item contains the following declarative:

    • load_balancer_port (string)

      Specifies the external load balancer port number.

      Required: Yes

    • protocol (string)

      Specifies the load balancer transport protocol to use for routing: HTTP, HTTPS, TCP or SSL.

      Required: Yes

    • instance_port (string)

      Specifies the TCP port on which the instance server listens.

      Required: Yes

    • instance_protocol (string)

      Specifies the protocol to use for routing traffic to back-end instances: HTTP, HTTPS, TCP or SSL. You can't modify this property during the life of the load balancer.

      Required: No

      Note:

      • If the front-end protocol is HTTP or HTTPS, instance protocol must be on the same protocol layer (HTTP or HTTPS). Likewise, if the front-end protocol is TCP or SSL, instance protocol must be TCP or SSL.

      • If there is another Listener with the same instance port whose instance protocol is secure, (using HTTPS or SSL), the instance protocol of the Listener must be secure (using HTTPS or SSL). If there is another Listener with the same instance port whose instance protocol is HTTP or TCP, the instance protocol of the Listener must be either HTTP or TCP.

    • cert_domain (string)

      (AWS Only)

      Specifies the domain name to be used for issuing SSL certificate via AWS ACM service.

      Required: No

      When you provide the domain name here, a verification email will be sent to the domain owner (sent by AWS), and you have to click link found in email to approve the issuance of the SSL certificate before the stack provision can be finished.

      Once the provision deployment is successfully done, the SSL certificate will be attached to your load-balancer automatically.

  • health_check (object)

    (AWS Only)

    Application health check for the instances.

    Required: No

    A health check section contains the following declarative:

    • healthy_threshold (string)

      Specifies the number of consecutive health probe successes required before moving the instance to the Healthy state.

      Required: Yes

    • interval (string)

      Specifies the approximate interval, in seconds, between health checks of an individual instance. Valid values are 5 to 300.

      Required: Yes

    • target (string)

      Specifies the instance's protocol and port to check. The protocol can be TCP, HTTP, HTTPS, or SSL. The range of valid ports is 1 through 65535.

      Required: Yes

    • timeout (string)

      Specifies the amount of time, in seconds, during which no response means a failed health probe. This value must be less than the value for interval.

      Required: No

    • unhealthy_threshold (string)

      Specifies the number of consecutive health probe failures required before moving the instance to the Unhealthy state.

      Required: No

Valid values:

"load_balancer": {
        "lb_type": "classic",
        "scheme": "internet-facing",
        "listeners": [
            {
                "load_balancer_port": "443",
                "instance_port": "80",
                "protocol": "HTTPS",
                "cert_domain": "www.example.com"
            }
        ],
        "health_check": {
            "healthy_threshold": "2",
            "interval": "10",
            "target": "TCP:80",
            "timeout": "5",
            "unhealthy_threshold": "10"
        }
    }

rds

Type

Required

Description

object

no

The rds is a managed relational database service.

The rds section contains the following declarative:

  • db_instance_type (string)

    If you don't specify this declarative, the default values will be applied for each cloud platform.

    Required: Yes

  • engine (string)

    If you don't specify this declarative, the default values will be applied for each cloud platform.

    Required: Yes

  • version (string)

    If you don't specify this declarative, the default values will be applied for each cloud platform.

    Required: Yes

  • storage (int)

    Constraints: 5-3072 (managemet disk).

    Required: Yes

  • multi_az (boolean)

    Create replica in an availability zone different from the DB instance. Defines whether this nulti_az is AZ or No AZ. This value is either true or false.

    Required: Yes

  • replica (int)

    Constraints: 1-5 (replica counts).

    Required: No

Valid values:

Default: db.t2.micro

 "rds": {
        "db_instance_type": "db.t2.micro",
        "engine": "mysql",
        "version": "5.6"
        "storage": 10,
        "multi_az": true,
        "replica": 1
    }

Below are the valid db instance types for AWS.

    db.t2.micro [default]
    db.t2.small
    db.t2.medium
    db.t2.large
    db.t2.xlarge
    db.t2.2xlarge
    db.m4.large
    db.m4.xlarge
    db.m4.2xlarge
    db.m4.4xlarge
    db.m4.10xlarge
    db.m4.16xlarge
    db.m3.medium
    db.m3.large
    db.m3.xlarge
    db.m3.2xlarge
    db.r3.large
    db.r3.xlarge
    db.r3.2xlarge
    db.r3.4xlarge
    db.r3.8xlarge
    db.r4.large
    db.r4.xlarge
    db.r4.2xlarge
    db.r4.4xlarge
    db.r4.8xlarge
    db.r4.16xlarge
    db.m2.xlarge
    db.m2.2xlarge
    db.m2.4xlarge
    db.m1.small
    db.m1.medium
    db.m1.large
    db.m1.xlarge

Below are the valid engine and version for AWS.

    mysql
        - 5.6
        - 5.7
    postgres
        - 9.6
        - 10

container

The software runtime configurations (defined as docker images) and code deployment requirement for each instance node.

container_image

Type

Required

Description

string

no

The docker image to be used to launch base container.

Example:

registry.mobingi.com/tompson/ubuntu-nginx-php:latest

container_registry_username

The docker image registry's username if this is a private image repository.

Type

Example Value

Required

Supported Platforms

string

N/A

No

Platform Stateless

container_registry_password

Type

Required

Description

string

no

The docker image registry's password if this is a private image repository.

container_code_dir

Type

Required

Supported Platforms

string

no

The directory of the instance where application code will be deployed to.

Example:

/var/www/html

container_git_repo

Type

Required

Description

string

no

The git repository url of where application code is hosted.

Example:

https://github.com/mobingilabs/default-site-php.git

container_git_reference

Type

Required

Description

string

no

The git repository branch of where application code is hosted.

Example:

master

container_git_private_key

Type

Required

Description

string

no

The private key of the git repository if it is a private repository.

container_ports

Type

Required

Description

array

no

The ports for connection to be used by containers.

Example:

[ 80 ]

container_users

This parameter is not yet supported.

container_env_vars

Type

Required

Description

object

no

The environment variables to be defined for the container operating system.

An example container configuration:

"container": {
  "container_image": "mobingi/ubuntu-apache2-php7",
  "container_code_dir": "/var/www/html",
  "container_git_repo": "https://github.com/mobingilabs/default-site-php.git",
  "container_git_reference": "master",
  "container_ports": [80],
  "container_env_vars": {
    "display_errors": "Off",
    "my_variable": "Some value"
  }
}
PreviousWhat is ALM Template?NextALM Template Language

Last updated