Changing the CLI Output to JSON

📘

Orka 2.4.x content

This page has not been updated to reflect the changes introduced in Orka 3.0. Some of the information might be outdated or incorrect. Use 2.4.x to 3.0.0: API Mapping and 2.4.x to 3.0.0: CLI Mapping to figure out the correct endpoints and commands.

As of Orka version 1.6, the CLI is now automation friendly, meaning it can now be used with any CI pipeline. All commands now return appropriate exit codes. 0 for successful completion of a command and 1 for any errors.

The CLI also utilizes JSON output using the --json flag or by permanently setting it via orka config. It can be used in conjunction with applications like .jq to parse JSON data. All of these features can be used in unison in a shell script to create seamless automation.

What is jq?

jq is a separate application that can be used to parse JSON data. Common usage is piping JSON data into jq to return only the desired. To download jq, please visit here

Basic jq Example:

Of course other options like sed and awk exist as well but jq is the most optimized for JSON output.

Orka CLI Configuration

To permanently configure the CLI to use JSON output, all you have to do is pass in "JSON" to the output style of orka config.

For shorthand notation, you can use:

orka config -a <ORKA_API_URL> -l <ORKA_LICENSE_KEY> --output-style JSON

🚧

NOTE:

Once JSON output is set permanently, you will no longer be able to use the TABLE output style. In order to switch it back to the TABLE output style, you have to use the orka config shorthand notation.

EX:
orka config --output-style TABLE

If you do not want to use JSON for all commands and much rather configure the CLI on a case by case basis, then you can use the --json flag on any command that you desire.

EX:

orka vm configs --json

Usage

There are various use cases where you might want to use JSON output over the interactive menu. You may have a set of different tasks that are used on a regular basis. You can compile these tasks into one shell script

EX using orka vm create

The above is an example of the output that is returned when the command
orka vm create -v foo -b 90GCatalinaSSH.img --json is run. Some of you may be asking, what is the benefit of having all this data spit out at me? The power of comes when you use it with a parser like jq.

So in the above use case, the message and vm_id fields are the only fields needed. To accomplish filtering these fields , use jq to parse this data. The final result returns only the message and vm_id.

EX using orka vm create with jq

So by utilizing jq, you can clean up the output returned when using the --json flag.

You can then begin to used advanced configurations that combine various CLI commands to automate your desired workflow. Below is one such bash script that runs various tasks back to back.

#!/bin/bash

set -e

echo Creating and deploying VM...
read vm_id ip ssh_port < <(echo $(orka vm create -v foo -b 90GCatalinaSSH.img --json | jq -r '.vm_id, .ip, .ssh_port'))
if [ $vm_id = "null" ]; then
       echo "error occured"
       exit 1
fi

echo Wait for VM to boot
sleep 60
echo Checking status
vm_status=$(orka vm status -v $vm_id --json | jq -r ".virtual_machine_resources[] | .status[] | select(.virtual_machine_id==\"$vm_id\") | .vm_status")
if [ $vm_status == 'running' ]
then
    echo issuing ssh commands
    sshpass -p admin ssh Admin@$ip -p $ssh_port 'echo testfile > test.txt'
    sshpass -p admin ssh Admin@$ip -p $ssh_port 'ls'
    sshpass -p admin ssh Admin@$ip -p $ssh_port 'cat test.txt'

    echo saving image
    orka image save -v $vm_id -b newbase --json
    orka images --json | jq -r '.image_attributes[] | select(.image=="newbase")'
else
    echo error occured
fi

orka vm purge -v foo --json | jq -r .message

What this script does is:

• Creates and deploys a VM.
• Checks that deployment was successful.
• Waits for the VM to boot.
• Checks that it's running.
• Runs commands in the VM using sshpass.
• Then saves and image based off of this virtual machine.
• Finally the VM is purged.

And this only sample of what can be done using JSON output. You are only limited by your imagination. So happy hacking!