GLOBAL

kind

What kind of deployment is this file.

Valid choices are directorProject, metadata and vmJail.

datacenters

Servers to perform HTTP requests.

datacenters.datacenter.entrypoint

 

datacenters.datacenter.access_token

 

datacenters.datacenter.timeout

 

datacenters.datacenter.read_timeout

 

datacenters.datacenter.write_timeout

 

datacenters.datacenter.connect_timeout

 

datacenters.datacenter.pool_timeout

 

datacenters.datacenter.max_keepalive_connections

 

datacenters.datacenter.max_connections

 

datacenters.datacenter.keepalive_expiry

See chains.chain.* in CONFIGURATION for details.

deployIn

Specify where to deploy.

deployIn.entrypoints

List of entry points to connect to that may have the chain with a syntax such as datacenter.{chainA}.{chainB}.

By default, when no entry point is specified, data centers will be used as the entry points.

deployIn.labels

Deploy to servers with these labels. When no labels are specified, the all label is used.

deployIn.exclude

Exclude servers matching the specified labels.

maximumDeployments

The maximum number of times to deploy a project.

metadata

Metadata allows simple text files to be created in the corresponding Overlord instances. Metadata is integrated with other Overlord parameters or subsystems, so it can be reused for multiple things.

metadata

A dictionary specifiying the metadata to be stored.

directorProject

Director is used for the creation of a project, a simple text file in YAML format that deploys one or more services (aka jails) on a single system.

projectName

Project name.

projectFile

Content of the project.

projectFromMetadata

Like projectFile but it obtains the content of the project from a metadata.

environment

A dictionary with each key-value environment. Both the key and the value must be a string.

environFromMetadata

Like environment but obtains a dictionary from a metadata in YAML format.

datacentersEnvironment

Each key must be a datacenter and its value a dictionary such as environment specifying the environment to use depending on the datacenter.

This parameter overrides any other environment-like option.

chainsEnvironment

Each key must be a chain and its value a dictionary such as environment specifying the environment to use depending on the chain.

This parameter overrides any other environment-like option except datacentersEnvironment.

A special key <root> can be used when a request is to be made to a datacenter but without specifiying a chain.

labelsEnvironment

Each key must be a label and its value a dictionary such as environment specifying the environment to use depending on whether the datacenter and its chain have a label that matches a key.

This parameter overrides any other environment-like option except datacentersEnvironment and chainsEnvironment.

autoScale

When at least one option of this parameter is set, a metadata named overlord.autoscale.project is created instead of simply deploying the project to the matching nodes. It is assumed that the remote Overlord instance will read the metadata to deploy and autoscale the project depending on how many chains it has.

The counterpart to destroying a project is to create another metadata named overlord.autoscale-cleanup.project. This is an indication to the Overlord instance not to deploy any more projects and to destroy the ones that are currently deployed.

If the overlord.autoscale.project metadata have at least one change, the project is redeployed to the nodes that have the project.

autoScale.replicas

Configuration parameters used to replicate the project.

autoScale.replicas.min

The minimum number of replicas this project will have. It depends on the number of matching and working chains.

autoScale.replicas.max

When scaling the project due to rctl(8) rules, this limits the number of deployments. By default, the number of matched and working chains calculated at runtime is used.

autoScale.type

When at least one rctl(8) rule is specified to scale the project based on the jail metrics, this indicates how the metric should be evaluated.

any-jail

Fails if any of the jails have a metric greater than or equal to the specified limit.

any-project

Fails if the metric total for all jails in the same project is greater than or equal to the specified limit.

average

Calculates the average of the metric for all jails in the same project and fails if it is greater than or equal to the specified limit.

percent-jail

Calculates the percentage of the specified limit and fails if it is greater than or equal to the current metric. For example, if you define a rule as “vmemoryuse=512m” and a percentage of 60, the value will be 307 (rounded), so this test fails if the current metric is greater than or equal to 307.

percent-project

Like percent-jail, but first get the metric total for all jails in the same project

autoScale.value

If the type requires a value such as percent-jail or percent-project, this parameter must be used.

autoScale.rules

A dictionary specifying the rctl(8) rules. Each key-value must specify the rule and the limit, and if that limit is reached, more instances of the project will be created.

autoScale.economy

Like autoScale.rules but the comparison is as simple as comparing the current server stats with the rules provided by this parameter.

This by itself does not solve the noisy neighbor problem (limiting resource usage could solve this problem), but it can be useful for when you want to improve the latency response, so Overlord will throw away the project on an available chain.

autoScale.labels

See deployIn.labels for details.

readOnly

This deployment is only useful for use with the get-info command and can't be used with apply or destroy.

appConfig

Gets a Mako template from a metadata and substitutes variables, generating a new deployment file that can only be a directorProject or vmJail deployment. The resulting deployment file is temporary and is created each time the appConfig deployment is applied. Once the deployment file is created from the Mako template, it is applied.

Even if you have deployed the metadata in many chains, only the first match in an appConfig deployment is used.

See also Mako syntax

appName

Application name.

The variable ${appName} is automatically set and must be used in the Mako template, however this is not enforced in any way.

appFrom

Metadata to obtain the Mako template.

In addition to the parameters required for the specified deployment type, you must include at least the kind parameter. datacenters, deployIn and maximumDeployments parameters are set by Overlord when processing the appConfig deployment.

appConfig

A dictionary where each key represents the variable to be substituted when processing the Mako template.

vmJail

Deploy a new project that will create a new jail to then create a virtual machine. This kind of deployment integrates well with Overlord because the information it gets comes from the project and the jail.

A virtual disk is created and partitioned. This deployment file specifies the files to be installed on the root partition that must correspond to the FreeBSD installation. Once this process is complete, a new virtual machine will be up and running.

vmName

The name of the project, the jail and the virtual machine.

makejail

The Makejail to create the environment. This Makejail must install at least vm-bhyve(8) (stable or devel) for this kind of deployment to work properly. Apart from installing vm-bhyve(8) you must specify the network options of the jail, such as using Virtual Networks, configure the bridge, create the switch, and unhide the devices for bhyve(4) to work correctly.

makejailFromMetadata

Like makejail but it obtains the content of the Makejail from a metadata.

template

A dictionary where each key-value will be written as a vm-bhyve(8) template. The parameters disk0_type, disk0_name, disk0_dev and disk0_size will be written by Overlord when creating the template.

disk0_type is whatever is specified in diskLayout.driver, disk0_name is disk0.img, disk0_dev is file and disk0_size is whatever is specified in diskLayout.size.

diskLayout

Configuration parameters for the virtual disk.

diskLayout.driver

The emulation type for the virtual disk.

Only nvme and virtio-blk are supported.

diskLayout.size

Size of the virtual disk.

diskLayout.from

Configuration parameters to determine how FreeBSD will be installed.

diskLayout.from.type

How to install FreeBSD. Depending on this parameter, some parameters may or may not be valid.

Only appjailImage, components and iso are supported.

diskLayout.from.isoFile

The name of the ISO file containing the operating system to install. Due to the nature of Overlord, which deploys jails and VMs not necessarily on your local machine, you must use configure the VM template for use with VNC.

See also UEFI Graphics (VNC)

This parameter is only valid for the iso type.

diskLayout.from.installed

A boolean to indicate whether the VM can be enabled and started for persistent use. Or in other words, after installing the operating system, you must modify your deployment file and include this parameter set to true.

This parameter is only valid for the iso type.

diskLayout.from.components

A list of components to download and extract into the VM root partition.

This parameter is only valid for the components type.

diskLayout.from.osVersion

FreeBSD version.

This parameter is only valid for the components type.

diskLayout.from.osArch

FreeBSD architecture.

This parameter is only valid for the components type.

diskLayout.from.downloadURL

URL of the web site where the components will be downloaded. The special strings {ARCH} and {VERSION} will be replaced by the values specified in the osArch and osVersion parameters.

This parameter is only valid for the components type.

diskLayout.from.entrypoint

Where and how to obtain the appjail-ajspec(5) file to then obtain the image to be extracted to the VM root partition.

This parameter is only valid for the appjailImage type.

diskLayout.from.imageName

Image name that does not necessarily correspond to the one specified in the appjail-ajspec(5) file, although it is recommended to use the same value as the one specified in the name parameter of that file.

This parameter is only valid for the appjailImage type.

diskLayout.from.imageArch

Obtain and use the image that matches this architecture.

This parameter is only valid for the appjailImage type.

diskLayout.from.imageTag

Obtain and use the image that matches this tag.

This parameter is only valid for the appjailImage type.

diskLayout.disk

Configuration parameters of virtual disk partitions, scheme and boot code.

diskLayout.disk.scheme

Specify the partitioning scheme to use.

diskLayout.disk.partitions

A list of dictionaries specifying the configuration parameters of the virtual disk partition.

diskLayout.disk.partitions.partition.type

Create a partition of type type.

diskLayout.disk.partitions.partition.alignment

If specified, then Overlord tries to align start offset and partition size to be multiple of alignment value.

diskLayout.disk.partitions.partition.start

The logical block address where the partition will begin.

diskLayout.disk.partitions.partition.size

Create a partition of size size.

diskLayout.disk.partitions.partition.label

The label attached to the partition. This option is only valid when used on partitioning schemes that support partition labels.

diskLayout.disk.partitions.partition.format

Configuration parameters for formatting the root partition.

If this parameter is set, the root partition is not only formatted, but also mounted and FreeBSD files are installed on it. You can specify this parameter multiple times, but only the first one will be mounted, although all partitions with this parameter will be formatted.

diskLayout.disk.partitions.partition.format.flags

newfs(8) flags.

diskLayout.disk.bootcode

Embed bootstrap code into the partitioning scheme's metadata on the root partition or write bootstrap code into a partition.

diskLayout.disk.bootcode.bootcode

Embed bootstrap code from the file bootcode into the partitioning scheme's metadata.

diskLayout.disk.bootcode.partcode

Write the bootstrap code from the file partcode into the root partition specified by diskLayout.disk.bootcode.index.

diskLayout.disk.bootcode.index

Specify the target partition for diskLayout.disk.bootcode.partcode.

diskLayout.fstab

Specifies the entries to create an fstab(5) file on the root partition.

diskLayout.fstab.entry.device

Special device or remote file system to be mounted.

diskLayout.fstab.entry.mountpoint

Mount point for the file system.

diskLayout.fstab.entry.type

Type of file system.

diskLayout.fstab.entry.options

Mount options associated with the file system.

diskLayout.fstab.entry.dump

Used for these file systems by the dump(8) command to determine which file systems need to be dumped.

diskLayout.fstab.entry.pass

Used by the fsck(8) and quotacheck(8) programs to determine the order in which file system and quota checks are done at reboot time.

script

A sh(1) script intended to further customize the virtual machine. The VM root partition is mounted on /mnt but inside the jail, however, the script runs in the jail directory not /mnt.

metadata

A list of metadata to be copied to the /metadata directory inside the jail. The metadata must be previously deployed or it is simply ignored.

options

Array of dictionaries where each dictionary (key and value) represents the option used by appjail-quick(1).

Keys are mandatory, but values are optional.

script-environment

Array of dictionaries where each dictionary (key and value) represents the environment used by the script.

Environment variables are not loaded automatically, they must be loaded from the /metadata/environment file which is always created even if this parameter is not specified.

start-environment

Array of dictionaries where each dictionary (key and value) represents the environment used by the start stage.

start-arguments

Array of dictionaries where each dictionary (key and value) represents the arguments used by the start stage.

build-environment

Array of dictionaries where each dictionary (key and value) represents the environment used by the build stage.

build-arguments

Array of dictionaries where each dictionary (key and value) represents the arguments used by the build stage.