How to use Variables in KOSI Packages

This guide explains how to use Variables that are set by KOSI plugins inside your KOSI package.
Tags:

  3 minute read  

How to use Variables in KOSI Packages

KOSI plugins can produce internal variables during execution, which you can reference in subsequent steps of your package (for example in conditions or output messages). The following guide explains how to use variables set by various KOSI plugins and how to consume them using e.g. the if and fprint plugins (which allow conditional logic and formatted output, respectively).

Plugins that set Variables

Several plugins store their results in named variables. These include:

  • Firewall / Firewalld / IPTables – All three firewall plugins support a key like getFirewallStatus = "<var>". For example:

    firewall
(
    type = "firewalld";
    action = "enable";
    getFirewallStatus = "status";
);

    This stores the firewall status ("running" or "not running") into the variable status. You can then reference this status variable in later steps.

  • Hostname – The hostname plugin can get the current hostname into a variable or set a new hostname from a variable. Its keys are: get = "<var>" to save the current hostname and setVar = "<var>" to restore from a saved variable. For example:

    hostname(get = "oldHostname");

    This saves the machine’s current hostname into the variable oldHostname.

  • kubeadm – The kubeadm plugin runs kubeadm commands. Its outputVar = "<var>" option captures the command’s output into a variable. For example:

    kubeadm
(
    operation = "version";
    kubeadmVersion = "version";
    outputVar = "kubeadmVersionOutput";
);

    This saves the output of kubeadm version into the variable kubeadmVersionOutput.

  • kubectl – The kubectl plugin executes kubectl commands. Its outputVar = "<var>" captures the command output. For example:

    kubectl
(
    operation = "get";
    resource = "pods";
    flags = "-n kube-system -o wide";
    outputVar = "podsOutput";
    outputFile = "/root/output.txt";
);

    This saves the kubectl get pods output into podsOutput. You can then use podsOutput in subsequent steps.

  • osCheck – The osCheck plugin detects the OS name and version. It has two keys: getOSVar="<var>" for the OS name and getOSVersionVar="<var>" for the OS version. For example:

    osCheck(getOSVar="osName"; getOSVersionVar="osVersion");

    This stores the OS name in osName and the version in osVersion.

  • set – The set plugin lets you define arbitrary variables. Use variable="<name>"; value="<something>" to create a variable. For example:

    set(variable = "envType"; value = "production");

    This creates a variable named envType with value "production". Variables set by the set plugin are accessed via vars.<variableName>.

Referencing Plugin Variables

KOSI provides two main ways to use these variables:

  • Conditional checks with the if plugin: The if plugin evaluates an expression and branches accordingly. In the condition string, you can include plugin variables by name, enclosed in $...$. For example:

    if(condition = "$oldHostname$ = 'myHost'") then {
    # ... do something ...
}

    For variables set via the set plugin, access them as $vars.<name>$, e.g. $vars.envType$.

  • Formatted output with the fprint plugin: The fprint plugin prints a message and can include plugin-variable values. You provide a list of variable names in its variables key and placeholders {0}, {1}, etc. in the message. For example:

    fprint
(
    message = "Firewall status is {0}";
    variables = "['status']";
);

    For variables from the set plugin:

    set(variable="userName"; value="Alice");
set(variable="userIP"; value="10.0.0.1");
fprint
(
    message = "User {0} has IP {1}";
    variables = "['vars.userName','vars.userIP']";
);

Example Workflow

  1. Set or retrieve a variable:

    hostname(get = "myHostname");
osCheck(getOSVar = "osName"; getOSVersionVar = "osVersion");

  2. Conditionally act on it:

     if(condition = "$myHostname$ = 'expectedHost'") then {
     fprint
     (
         message = "Got expected hostname: {0}";
         variables = "['myHostname']";
     );
 }

  3. Output or log values:

    fprint
(
    message = "Running on {0} version {1}";
    variables = "['osName','osVersion']";
);

Plugins mentioned in this How to Guide that set or use variables