NAME

overlord — Deploy FreeBSD jails as fast as you code

SYNOPSIS

DESCRIPTION

Overlord is a fast, distributed orchestrator for FreeBSD jails oriented to GitOps. You define a file with the service intended to run on your cluster and deployment takes seconds to minutes.

apply [--restart] --file file

Applies a file containing a deployment, or in other words, this command is to deploy something depending on the deployment type specified in overlord-spec(5).

--restart

If this option is set and is a directorProject deployment, all jails in the project will be restarted. Overlord does not control the execution flow, it uses down and up of Director for this. If you have configured autoscaling, this option is ignored.

In the case of a vmJail deployment, the above process takes place, however in a vmJail deployment the VM is forcibly shutdown, which may lead to data loss or something else. Be careful.

-f file, --file file

Deployment file.

cancel [--filter-chain filter] --file file

Cancels a project or VM in execution.

--filter-chain filter

Destroy the project that matches with this chain.

This parameter can be specified multiple times.

-f file, --file file

Deployment file.

print-config

Prints the configuration in JSON format. This includes the default values.

print-spec

Prints the specification of a deployment file in JSON format. This includes the default values.

destroy [--force] [--filter-chain filter] --file file

Destroy a project or metadata.

--force

Force the destruction of a project.

Overlord will refuse to destroy a project that has an unexpected status, however labels are still executed and if they any of them fail, the project will not be destroyed.

--filter-chain filter

Destroy the project that matches with this chain.

This parameter can be specified multiple times.

-f file, --file file

Deployment file.

gen-token [--metadata key[=value]] [--expire expire] [--expire-type type]

Generate a new token.

--metadata key[=value]

Additional metadata. They can be used for additional functions or third-party tools.

--expire expire

If this parameter is set, an expiration date is set on the token, which by default never expires.

--expire-type type

Set the expiration date in seconds, minutes, hours, days or weeks.

get-info [--jail-item item] [--all-labels] [[--filter filter|--filter-per-project]] [--use-autoscale-labels] --file file --type type

Gets information about an entity specified with --type.

--jail-item item

When the --type parameter is set to jails, this parameter can be used to control how much information to display from the jails. Valid values are stats, info, cpuset, devfs, expose, healthcheck, limits, fstab, labels, nat and volumes. If this parameter is not specified, all elements are used.

This parameter can be specified multiple times.

--all-labels

By default, the information is displayed according to the labels specified in the deployment file. This parameter displays all information ignoring the labels.

--filter filter

Depending on the value specified with --type, it can be used to filter the information to be displayed. The value of this parameter is a literal string when the --type parameter is set to autoscale or a valid regular expression for other types. The value to compare can be the jail name, the project name, the VM name, a chain or a log file name.

This parameter can be specified multiple times.

--filter-per-project

Like --filter but matching only the project or VM specified in the deployment file.

--use-autoscale-labels

Use the labels defined in the autoScale section.

-t type, --type type

What kind of information to get. The elements are jails, to get information about jails, projects to get information about projects, vm to get information about VM deployments, chains to simply display chains recursively, autoscale to get the scaling status, chains:tree to display an ASCII-tree of chains, chains:stats to get server metrics, metadata to get the metadata specified in the deployment file or in the parameter --filter, projects:logs for logs created by Director and jails:logs for logs created by AppJail.

-f file, --file file

Deployment file.

get-project-log --file file --date date --service service --log log entrypoint

Gets the content of a log created by Director.

-f file, --file file

Deployment file.

-d date, --date date

Log date.

-s service, --service service

Service name.

-l log, --log log

Log file name.

entrypoint

An entry point that must exist in the deployment file. After the entry point, a chain can be specified (e.g.: main.delta.echo).

get-jail-log --file file --type type --entity entity --subtype subtype --log log entrypoint

Gets the content of a log created by AppJail.

-f file, --file file

Deployment file.

-t type, --type type

Group of entities.

-e entity, --entity entity

Individual in a group.

-s subtype, --subtype subtype

Group of logs.

-l log, --log log

Log file name.

entrypoint

An entry point that must exist in the deployment file. After the entry point, a chain can be specified (e.g.: main.delta.echo).

poll-jails

Collects the list of jails from the system and stores them in the cache server. Indispensable for other polling operations.

poll-jail-info

Using the list of jails stored in the cache server, this command will collect the information of each jail to be stored in the cache server.

poll-jail-extras [--item item]

Like poll-jail-info but for more information depending on the --item parameter.

--item item

The reason for having this parameter is to allow more processes to be separated to collect information in parallel and decide exactly what information to obtain.

Valid values are cpuset, devfs, expose, healthcheck, limits, fstab, label, nat and volume.

poll-jail-stats

Collects the statistics provided by the rctl(4) framework on the jails and stores them in the cache server.

poll-projects

Collects the list of projects from the system and stores them in the cache server. Indispensable for other polling operations.

poll-project-info

Using the list of projects stored in the cache server, this command will collect the information of each project to be stored in the cache server.

poll-autoscale

Scale projects based on metrics and replicas.

poll-heartbeat

Checks the status of each chain.

This adds more intelligence to the server because Smart Timeouts can completely disable a chain if it is slow to respond after a few attempts but does not necessarily mean it is faulty. So instead of simply disabling a chain for a while, this command influences this operation because it allows a user to make requests based on the health of the chain.

watch-projects

Wait for jobs to create or destroy a project.

See SPECIAL LABELS for more information on the labels that this command can use to perform some operations.

SPECIAL LABELS

Jails can have labels and some of them cause the watch-project command to perform certain operations.

In order for special labels to perform their operations, the project must have the status DONE and each jail must have the status 0 reported by appjail-status(1). Jails that do not meet this requirement will be completely ignored.

Also note that in the case of destroying a project requested by the destroy command, the project will not be destroyed if an integration fails in its operation. This is to inform you first if an error has occurred and it is necessary to intervene.

overlord.load-balancer

If this label has a value, a new server is added, replaced or removed (depending on whether the project will be added or destroyed) to the backend specified in the overlord.load-balancer.backend label.

overlord.load-balancer.backend

The backend to add, replace or remove the server.

overlord.load-balancer.interface

The interface to obtain the IP address.

overlord.load-balancer.interface.port

The port to which the load-balancer will be connected.

overlord.load-balancer.interface.address

The network address where the corresponding IP should be.

If this label is not specified, the first IP returned will be used.

overlord.load-balancer.set.name

Additional configuration to add to the server. The value must be in JSON format.

See also Add a new server and Replace a server

overlord.skydns

If this label has a value, new DNS records are added to an etcd instance assuming that a SkyDNS instance is consuming it. In the modern era, you should use coredns-etcd(7) instead of the older implementation that is not related to CoreDNS.

overlord.skydns.group

This is the part that specifies the DNS label that is concatenated between the server ID and the zone. In other words, the domain will be serverid.group.zone, but you should use group.zone to consume, also remember that how SkyDNS is designed, the IPs are accumulated, so you can use it in a round-robin fashion, although it is preferable to use a load-balancer for this function, however.

overlord.skydns.interface

The interface to obtain the IP address.

overlord.skydns.interface.address

The network address where the corresponding IP should be.

If this label is not specified, the first IP returned will be used.

Note that if the IP address is an IPv4 address, an A record will be added, and if the IP is an IPv6 address, an AAAA record will be added instead.

overlord.skydns.ttl

The time-to-live field for A and AAAA records.

overlord.skydns.ptr

If this label has a value, a PTR record using the IP address of the interface specified in the overlord.skydns.interface label is added.

Note that you should use this record only if you are absolutely sure that the IP addresses are different between each system on which the project will be deployed.

overlord.skydns.srv

If this label has a value, an SRV record is added.

overlord.skydns.srv.port

The port that clients must use to connect to the application.

overlord.skydns.srv.proto

The protocol that clients must use to communicate with the application. Normally tcp or udp.

overlord.skydns.srv.service

The symbolic name of the desired service.

overlord.skydns.srv.priority

The priority of the target host.

overlord.skydns.srv.weight

A relative weight for records with the same priority, higher value means higher chance of getting picked.

See also Service Announcements for how this value is calculated.

overlord.skydns.srv.ttl

The time-to-live field for the SRV record.

ENVIRONMENT

OVERLORD_CONFIG

The configuration file to load if it exists. The default is .overlord.yml.

OVERLORD_METADATA

An environment variable set by the watch-projects command to indicate where the metadata is located. Useful for using metadata as simple text files.

SEE ALSO

appjail(1) overlord-spec(5)

AUTHORS

Jesús Daniel Colmenares Oviedo <DtxdF@disroot.org>