Yaml Based Configuration

Within an empty directory the following command can be used to generate an initial edi configuration:

edi config init my-project debian-stretch-amd64

This command generates a configuration with four placeholder use cases:

  • my-project-run.yml: This configuration file covers the run use case. It is the configuration that the customer will get.
  • my-project-test.yml: The test use case shall be as close as possible to the run use case. A few modifications that enable efficient testing will differentiate this use case from the run use case.
  • my-project-build.yml: The build use case covers the requirements of a build server deployment.
  • my-project-develop.yml: The develop use case satisfies the requirements of the developers.

Please note that the above use cases are just an initial guess. edi does not at all force you to build your project upon a predefined set of use cases. It just helps you to modularize your different use cases so that they do not diverge over time.

The configuration is split into several sections. The following command will dump the merged and rendered configuration of the use case develop for the given command:

edi lxc configure --config my-container my-project-develop.yml

general Section

The general section contains the information that might affect all other sections.

edi supports the following settings:

key description
edi_compression The compression that will be used for edi (intermediate) artifacts.
Possible values are gz (fast but not very small),
bz2 or xz (slower but minimal required space).
If not specified, edi uses xz compression.
edi_lxc_stop_timeout The maximum time in seconds that edi will wait until
it forces the shutdown of the lxc container.
The default timeout is 120 seconds.
edi_required_minimal_edi_version Defines the minimal edi version that is required for the given configuration.
If the edi executable does not meet the required minimal version, it will exit with an error.
If not specified, edi will not enforce a certain minimal version.
A valid version string value looks like 0.5.2.
edi_lxc_network_interface_name The default network interface that will be used for the lxc container.
If unspecified edi will name the container interface lxcif0.
edi_config_management_user_name The target system user that will be used for configuration management tasks.
Please note that direct lxc container management uses the root user.
If unspecified edi will name the configuration management user edicfgmgmt.

bootstrap Section

This section tells edi how the initial system shall be bootstrapped. The following settings are supported:

key description
architecture The architecture of the target system.
For Debian possible values are any supported architecture such as amd64, armel or armhf.
repository The repository specification where the initial image will get bootstrapped from.
A valid value looks like this: deb http://deb.debian.org/debian/ stretch main.
repository_key The signature key for the repository.
Attention: If you do not specify a key the downloaded packages will not be verified during the bootstrap process.
Hint: It is a good practice to download such a key from a https server.
A valid repository key value is: https://ftp-master.debian.org/keys/archive-key-8.asc.
tool The tool that will be used for the bootstrap process.
Currently only debootstrap is supported.
If unspecified, edi will choose debootstrap.

Please note that edi will automatically do cross bootstrapping if required. This means that you can for instance bootstrap an armhf system on an amd64 host.

If you would like to bootstrap an image right now, you can run the following command:

sudo edi image bootstrap my-project-develop.yml

qemu Section

If the target architecture does not match the host architecture edi uses QEMU to emulate the foreign architecture. edi automatically detects the necessity of an architecture emulation and takes the necessary steps to set up QEMU. As QEMU evolves quickly it is often desirable to point edi to a very recent version of QEMU. The QEMU section allows you to do this. The following settings are available:

key description
package The name of the qemu package that should get downloaded.
If not specified edi assumes that the package is named qemu-user-static.
repository The repository specification where QEMU will get downloaded from.
A valid value looks like this: deb http://deb.debian.org/debian/ stretch main.
If unspecified, edi will try to download QEMU from the repository indicated in the bootstrap section.
repository_key The signature key for the QEMU repository.
Attention: If you do not specify a key the downloaded QEMU package will not be verified.
Hint: It is a good practice to download such a key from a https server.
A valid repository key value is: https://ftp-master.debian.org/keys/archive-key-8.asc.

Ordered Node Section

In order to understand the following sections we have to introduce the concept of an ordered node section. In Unix based systems it is quite common to split configurations into a set of small configuration files (see e.g. /etc/sysctl.d). Those small configuration files are loaded and applied according to their alphanumerical order. edi does a very similar thing in its ordered node sections. Here is an example:

Example 1
dog_tasks:
  10_first_task:
    job: bark
  20_second_task:
    job: sleep
Example 2
dog_tasks:
  20_second_task:
    job: sleep
  10_first_task:
    job: bark

In both examples above the dog will first bark and then sleep because of the alphanumerical order of the nodes 10_first_task and 20_second_task. The explicit order of the nodes makes it easy to add or modify a certain node using Overlays.

Plugin Node

Most of the ordered node sections contain nodes that specify and parametrize plugins.

A typical node looks like this:

lxc_profiles:
  10_first_profile:
     path: path/to/profile.yml
     parameters:
       custom_param_1: foo
       custom_param_2: bar

Such nodes accept the following settings:

key description
path A relative or absolute path.
Relative paths are first searched within edi_project_plugin_directory and
if nothing is found the search falls back to edi_edi_plugin_directory.
The values of the plugin and project directory can be retrieved as follows:
edi lxc configure --dictionary SOME-CONTAINER SOME_CONFIG.yml.
parameters An optional list of parameters that will be used to parametrize the given plugin.
skip True or False. If True the plugin will not get applied.
If unspecified, the plugin will get applied.

To learn more about plugins please read the chapter Plugins.

lxc_templates Section

The lxc_templates section is an ordered node section consisting of plugin nodes. Please consult the LXD documentation if you want to write custom templates.

lxc_profiles Section

The lxc_profiles section is an ordered node section consisting of plugin nodes. Please consult the LXD documentation if you want to write custom profiles.

playbooks Section

The playbooks section is an ordered node section consisting of plugin nodes. Please consult the Ansible documentation if you want to write custom playbooks.

postprocessing_commands Section

The postprocessing_commands section is an ordered node section consisting of plugin nodes. The post processing commands can be written in any language of choice. In contrast to the other plugin nodes the post processing command nodes require an explicit declaration of the generated artifacts. Please read the chapter Plugins for more details.

shared_folders Section

The shared_folders section is an ordered node section that can be used to specify shared folders between LXC containers and their host.

Shared folders are very convenient for development use cases. Please note that edi will automatically turn any container that uses shared folders into a privileged container. This will facilitate the data exchange between the host and the target system. It is advisable to use shared folders together with the development_user_facilities playbook plugin.

A shared folder section can look like this:

shared_folders:
  edi_workspace:
    folder: edi-workspace
    mountpoint: edi-workspace

Let us assume that the name of the current development user is johndoe and that his home directory is /home/johndoe. The development_user_facilities playbook plugin will automatically make sure that the user johndoe will also exist within the container. The shared_folders section will then make sure that the host folder /home/johndoe/edi-workspace (folder) will be shared with the container using the container directory /home/johndoe/edi-workspace (mountpoint).

The shared folder nodes accept the the following settings:

key description
folder The name of the host folder within the home directory of the current user.
If the folder does not exist, edi will create it.
mountpoint The name of the mount point within the container home directory of the current user.
If the mount point does not exist edi will display an error.
Hint: It is assumed that the mount points within the container will get created using an appropriate playbook.
The development_user_facilities playbook plugin will for instance take care of mount point creation.
skip True or False. If True the folder will not be shared.
If unspecified, the folder will get shared.