Preparing the runtime environment

Prerequisites

Follow the global prerequisite.

Finite value of variables in runtime environment

The managed node will use the environment prepared by the control node. Values must be determined exactly. It makes no sense to send a variable referencing another one on an administered node, you’ll indicate the name of this referencing directly in the script: Executing MYVAR=“$HOME” echo “$MYVAR” only makes the process more complex, so write echo “$HOME” directly.

This presentation takes place in stages, with the aim of displaying the contents of a file located on a managed node.

The “prepareenvironment” operation consists of a manifest and a single script.

Using the “-e” switch

The operation script is :

#!/usr/bin/env bash

echo "File to read: ${MYFILE}"
cat "${MYFILE}"

The managed node does not know the value of “${MYFILE}”, this value will be defined in the environment provided by the control node and defined in the manifest:

[...]
parameters:
  required:
    MYFILE:
      type: string
      comment: "file name"

From a control node, I run the command :

automation-cli run -op "prepareenvironment" -h "localhost" -e MYFILE="/etc/cron.d/e2scrub_all"

The control node, after preparation, sends the execution order to the managed node in this form:

MYFILE="/etc/cron.d/e2scrub_all" bash [script name]

The file read will be “/etc/cron.d/e2scrub_all”.

You’ll notice that starting an operation always involves a presentation of what’s going to be executed and a list of the hosts affected. If you wish to bypass this confirmation, add the “-y” switch to your command.

WARNING: Performing an operation on a server may lead to serious malfunctions.

Default value - “operation” manifest

Manifests can stipulate default values for both types of parameter: “required” and “optional”.

Repeating the previous step, make a copy of the operation, naming it “prepareenvironmentdefault”, in the manifest, add the “default” attribute with a fixed value:

[...]
parameters:
  required:
    MYFILE:
      type: string
      comment: "file name"
      default: "/etc/cron.d/e2scrub_all"

From a control node, without specifying the ‘-e’ switch, I run the command :

automation-cli run -op "prepareenvironmentdefault" -h "localhost"

The file read will be “/etc/cron.d/e2scrub_all”.

Default value overridden by ‘-e’ switch

The “-e” switch overrides the default values defined in the operation manifests. Therefore, its value overrides the default value.

Going back to the previous step, the manifest contains a default value for the “MYFILE” variable:

[...]
parameters:
  required:
    MYFILE:
      type: string
      comment: "file name"
      default: "/etc/cron.d/e2scrub_all"

automation-cli run -op "prepareenvironmentdefault" -h "localhost" -e MYFILE="/etc/debian_version"

The file read will be “/etc/debian_version” and not the default value set in the operation.

Default value overridden by operationBook

When you have several steps in an operation to perform, using “operationBook”, the “operationBook” environment for an operation overrides the default values defined in the operation manifests.

Taking the previous step, add the “operationBook” manifest:

operations:
  - operation: "prepareenvironmentdefault"
    environment:
      MYFILE: "/etc/debian_version"

automation-cli run -ob "prepareenvironmentdefault" -h "localhost"

The file read will be “/etc/debian_version” and not the default value set in the operation.

Overriding the value defined in operationBook with the ‘-e’ switch

Returning to the previous step, we have two explicit values for the “MYFILE” variable in :

• The “operation” manifest (default): “/etc/cron.d/e2scrub_all”.
• The “operationBook” manifest: “/etc/debian_version”.

Based on this information, run the command :

automation-cli run -ob "prepareenvironmentdefault" -h "localhost" -e MYFILE="/etc/hosts"

The file read will be “/etc/hosts” the “-e” switch has priority in all operation executions.

Using inventory values

The runtime environment can also be prepared using values read from an inventory file.

In this case, variables used in operations must begin with ‘#inv.’, followed by the path to the desired value. The path is constructed by browsing the attributes of an inventory. An inventory is represented by an object built from a “YAML” structure.

From an inventory file created with the : automation-cli cinv "$OPS/inventory.yaml, add the “myfile” attribute with the value “/etc/hosts”:

sshpk: ""
sshpass: ""
serverGroups:
  all:
    - localhost
  controlnode:
    - localhost
  localhost: 127.0.0.1
myfile: /etc/group

Run :

automation-cli run -op "prepareenvironmentdefault" -i "$OPS/inventory.yaml" -h "localhost" -e MYFILE="#inv.myfile"

The file read will be “/etc/group”.

Note: The “MYFILE” variable in the “operation” manifest is required, so its final value cannot be empty. If the inventory file does not contain the “myfile” attribute, the operation will fail.

More complex use: Mixing control node environment and inventory values

“automation-cli” can read inventory values, depending on the value of a variable in its environment (control node).

From an inventory file created with the : automation-cli cinv "$OPS/inventoryEnv.yaml, add the attributes as follows:

sshpk: ""
sshpass: ""
serverGroups:
  all:
    - localhost
  controlnode:
    - localhost
  localhost: 127.0.0.1
myfile:
  group: /etc/group
  hosts: /etc/hosts

FILETOREAD="group" automation-cli run -op "prepareenvironmentdefault" -i "$OPS/inventoryEnv.yaml" -h "localhost" -e MYFILE="#inv.myfile.\$FILETOREAD"

The file read will be “/etc/group”.

FILETOREAD="hosts" automation-cli run -op "prepareenvironmentdefault" -i "$OPS/inventoryEnv.yaml" -h "localhost" -e MYFILE="#inv.myfile.\$FILETOREAD"

The file read will be “/etc/hosts.

How does it work?

The “FILETOREAD” variable is injected into the control node’s environment, prior to execution of “automation-cli”, so the process has this value. During preparation, the process tries to convert anything resembling an environment variable before determining its final value.

“#inv.myfile.$FILETOREAD” is transformed into ”#inv.myfile.[value of $FILETOREAD] (#inv.myfile.group or #inv.myfile.hosts depending on the value of FILETOREAD), and attempts to read this path in the inventory file.

**Explanation of the ”\” in front of “$FILETOREAD” :

The “$” character is protected by “\” so that bash does not perform any substitution at runtime.

“Bash” is a process in its own right, and is responsible for executing the command that follows its prompt. FILETOREAD=“hosts” will only be available in the “automation-cli” process started by “bash”. If “bash” doesn’t know the value of FILETOREAD, it will substitute it with “”, and “automation-cli” will then have the environment variable: ‘-e FILETOREAD=“#inv.myfile.”’ (FILETOREAD having been substituted by bash with the value “”). For bash to know this value before executing the command, you would first have to run: export FILETOREAD=“hosts”.

To avoid manipulating the bash variable protection, you can enclose the value of the “-e” switch variable with apostrophes instead of using quotation marks (-e MYFILE=‘#inv.myfile.$FILETOREAD’).

Another option for enriching the control node environment

Instead of injecting the FILETOREAD variable into the “automation-cli” execution environment, specify the variable in the operation environment. Although this variable can be used by the control node, and is not specified in the “prepareenvironmentdefault” operation manifest, it will not be part of the execution environment on the managed node.

Based on the previous step, run :

automation-cli run -op "prepareenvironmentdefault" -i "$OPS/inventoryEnv.yaml" -h "localhost" -e MYFILE="#inv.myfile.\$FILETOREAD" -e FILETOREAD="group"

The file read will be “/etc/group”.

Override priority order

• Value of ‘-e’ switch (highest level).
• Environment value in an “operationBook” manifest.
• Default value in an “operation” manifest.

It’s important to remember this order.

WARNING: The “register” method, depending on the variable names used, may override the prepared environment and cause major side effects.

Overridding a variable

Example, an operation started by “operationBook”, must communicate the KEY variable to the shell that will be executed on the administered node.

• Provided by user ‘-e’ :

• Provided by operationBook, calling operation :

• Provided by operationBook, calling operationBook, then operation :

• Provided by operation (“default” attribute) :

Side effects with register

This is a bad practice: you’re inserting an operation that includes the “register” mode, which you’ve named ‘KEY’. To avoid this, I advise you to prefix this variable type with ‘REG’. This type of programming can lead to serious errors.

• Reusing an existing variable with “register”:

The value of MYFILE has changed.

• With the variable used for register mode prefixed with ‘REG

MYFILE value has not been modified.

It is planned to include a stricter control on the name of this type of variable.