Variables #

One of the more important feature of lxd-compose is the management of the variables.

A variable could be identified by a simple key and a value that could be a simple string/integer or a complex struct.

Every key will be available inside the execution of the hooks as an environemnt variable, in the case of simple type will be available As-is, instead for complex struct lxd-compose will convert it in JSON string to parse for example with jq tool.

Before to describe how the variables are used inside the hooks i will describe the different way to set a specific variable inside lxd-compose.

Filter #

As described in the issue #16 using variables too big or complex could generates some issues in LXD.

So, it’s possible define at project level the list of the variables to exclude from automatic injection in the execute shell of the commands.

shell_envs_filter:
  - filteredEnv

The filtered variables will be available only for the template engine.

Inline variable #

Under a project it’s possible define an inline variable in different envs object:

# Inline variable
vars:
  - envs:
      mypublic_domain: example1.com
      letencrypt_server: https://acme-v02.api.letsencrypt.org/directory
      letencrypt_email: myemail@example.com

Variable’s file #

From a variables’s file inject by the include_env_files attribute.

envs:
  nginx_user: www-data
  nginx_logrotate_days: 30

  nginx_upstreams:
    - name: upstream1
      server: 192.168.0.90:8065
      keepalive: 32

  nginx_reset_htpasswd: "1"
  nginx_auth_basic_files:
    - path: /etc/nginx/myauth
      users:
        - user: "user1"
          pwd: "xxxxxx"
        - user: "user2"
          pwd: "yyyyy"

Node’s variables from labels #

From the node labels:

labels:
  label1: "1"

The node labels help to setup single node variables and when defined these options are also configured as container user.* configuration params. Normally, this variables could be used over LXD template engine integrated inside the LXD image and so a label with name myvar will be added inside the container configuration option as user.myvar.

Runtime variables #

It’s possible set variable on deploy a project from CLI:

$> lxd-compose apply myproject --env 'key1=value' --env 'key2=value'

Runtime inject variable file #

It’s possible inject a variable’s file on deploy a project from CLI:

$> lxd-compose apply myproject --vars-file vars.yml

Set a variable at runtime on the execution of the hooks #

An hooks could be used to set a variable from the stdout or stderr generated by the last command of the hook.

- event: pre-group
  node: "host"
  commands:
    - echo '[{ "user": "user1" }]'
  out2var: "json_var"

It’s used out2var for stdout and err2var for stderr.

These modes to configure variables inside a project are used to inizialize a map in memory that is then used from the template engine to render configuration files and as environment variables of the shell commands executed.

For example inside an hook the variable:

envs:
  nginx_user: www-data

could be used in this way:

- event: post-node-creation
  commands:
    - chown ${nginx_user}:${nginx_user} /mywww -R

Instead a complex variable like this:

envs:
  obj:
    key: "xxx"
    foo: "baa"

will be available inside the command in this way:

>>> [node1] - echo "${obj}" - ☕
{"foo":"baa","key":"xxx"}

Special variables #

There are special variables injected by lxd-compose automatically:

Diagnose variables #

To help people on parsing JSON object and check generated variable there is a debug tool to print variables inside a project:

$> # Generate the yaml of all project variables
$> lxd-compose diagnose vars  lxd-compose-example1

$> # Generate the JSON of all project variables
$> lxd-compose diagnose vars  lxd-compose-example1 --json