xOpera CLI (opera)

Installation

This section explains the installation of xOpera orchestrator.

Prerequisites

opera requires python 3 and a virtual environment. In a typical modern Linux environment, we should already be set. In Ubuntu, however, we might need to run the following commands:

$ sudo apt update
$ sudo apt install -y python3-venv python3-wheel python-wheel-common

Installation

xOpera is distributed as Python package that is regularly published on PyPI. So the simplest way to test opera is to install it into virtual environment:

$ mkdir ~/opera && cd ~/opera
$ python3 -m venv .venv && . .venv/bin/activate
(.venv) $ pip install --upgrade pip
(.venv) $ pip install opera

Quickstart

After you installed xOpera CLI into virtual environment you can test if everything is working as expected. We can now explain how to deploy the hello-world example.

The hello world TOSCA service template is below.

---
tosca_definitions_version: tosca_simple_yaml_1_3

node_types:
  hello_type:
    derived_from: tosca.nodes.SoftwareComponent
    interfaces:
      Standard:
        inputs:
          content:
            default: { get_input: content }
            type: string
        operations:
          create: playbooks/create.yml
          delete: playbooks/delete.yml

topology_template:
  inputs:
    content:
      type: string
      default: "Hello from Ansible and xOpera!\n"

  node_templates:
    my-workstation:
      type: tosca.nodes.Compute
      attributes:
        private_address: localhost
        public_address: localhost

    hello:
      type: hello_type
      requirements:
        - host: my-workstation
...

As you can see it is has only one node type defined. This hello_type here has two linked implementations that are actually two TOSCA operations (create and delete) that are implemented in a form of Ansible playbooks. The Ansible playbook for creation is shown below and it is used to create a new folder and hello world file in /tmp directory.

The deployment operation returns the following output:

(.venv) $ git clone git@github.com:xlab-si/xopera-opera.git
(.venv) $ cd examples/hello
(.venv) examples/hello$ opera deploy service.yaml
[Worker_0]   Deploying my-workstation_0
[Worker_0]   Deployment of my-workstation_0 complete
[Worker_0]   Deploying hello_0
[Worker_0]     Executing create on hello_0
[Worker_0]   Deployment of hello_0 complete

If nothing went wrong, new empty file has been created at /tmp/playing-opera/hello/hello.txt.

(venv) examples/hello$ ls -lh /tmp/playing-opera/hello/
total 0
-rw-rw-rw- 1 user user 0 Feb 20 16:02 hello.txt

And the playbook for destroying the service is below.

---
- hosts: all
  gather_facts: false

  tasks:
    - name: Remove the location
      file:
        path: /tmp/opera-test
        state: absent
...

To delete the created directory, we can undeploy our stuff by running:

(venv) examples/hello$ opera undeploy
[Worker_0]   Undeploying hello_0
[Worker_0]     Executing delete on hello_0
[Worker_0]   Undeployment of hello_0 complete
[Worker_0]   Undeploying my-workstation_0
[Worker_0]   Undeployment of my-workstation_0 complete

After that the created directory and file are deleted:

(venv) examples/hello$ ls -lh /tmp/playing-opera/hello/
ls: cannot access '/tmp/playing-opera/hello/': No such file or directory

CLI commands reference

opera was originally meant to be used in a terminal as a client and it currently allows users to execute the following commands:

CLI command

Purpose and description

opera deploy

deploy TOSCA service template or CSAR

opera undeploy

undeploy TOSCA service template or CSAR

opera validate

validate TOSCA service template or CSAR

opera outputs

retrieve outputs from service template

opera info

show information about the current project

opera package

retrieve outputs from service template

opera unpackage

retrieve outputs from service template

opera diff

compare service templates and instances

opera update

update/redeploy template and instances

notify the orchestrator about changes after the
deployment and run triggers defined in TOSCA policies

opera init

initialize the service template or CSAR (deprecated)

The commands can be executed in a random order and the orchestrator will warn and the orchestrator will warn you in case if any problems. Each CLI command is described more in detail in the following sections.


deploy

opera deploy - used to deploy and control deployment of the application described in YAML or CSAR.

The --resume/-r and --clean-state/-c options are mutually exclusive.

usage: opera deploy [-h] [--instance-path INSTANCE_PATH] [--inputs INPUTS]
                    [--workers WORKERS] [--resume | --clean-state] [--force]
                    [--verbose]
                    [template]

Positional Arguments

template

TOSCA YAML service template file or CSAR

Named Arguments

--instance-path, -p

Storage folder location (instead of default .opera)

--inputs, -i

YAML or JSON file with inputs to override the inputs supplied in init

--workers, -w

Maximum number of concurrent deployment threads (positive number, default 1)

Default: 1

--resume, -r

Resume the deployment from where it was interrupted

Default: False

--clean-state, -c

Clean the previous deployment state and start over the deployment

Default: False

--force, -f

Force the action and skip any possible prompts

Default: False

--verbose, -v

Turns on verbose mode

Default: False


undeploy

opera undeploy - undeploys application; removes all application instances and components.

The opera undeploy command does not take any positional arguments.

usage: opera undeploy [-h] [--instance-path INSTANCE_PATH] [--workers WORKERS]
                      [--resume] [--force] [--verbose]

Named Arguments

--instance-path, -p

Storage folder location (instead of default .opera)

--workers, -w

Maximum number of concurrent undeployment threads (positive number, default 1)

Default: 1

--resume, -r

Resume the undeployment from where it was interrupted

Default: False

--force, -f

Force the action and skip any possible prompts

Default: False

--verbose, -v

Turns on verbose mode

Default: False


validate

opera validate - validates the structure of TOSCA template or CSAR.

usage: opera validate [-h] [--inputs INPUTS] [--verbose]
                      [csar_or_service_template]

Positional Arguments

csar_or_service_template

TOSCA YAML service template file or CSAR

Named Arguments

--inputs, -i

YAML or JSON file with inputs

--verbose, -v

Turns on verbose mode

Default: False


outputs

opera outputs - print the outputs of the deploy/undeploy.

usage: opera outputs [-h] [--instance-path INSTANCE_PATH]
                     [--format {yaml,json}] [--output OUTPUT] [--verbose]

Named Arguments

--instance-path, -p

Storage folder location (instead of default .opera)

--format, -f

Possible choices: yaml, json

Output format

Default: “yaml”

--output, -o

Output file location

--verbose, -v

Turns on verbose mode

Default: False


info

opera info - print the details of current deployment project.

usage: opera info [-h] [--instance-path INSTANCE_PATH] [--format {yaml,json}]
                  [--output OUTPUT] [--verbose]
                  [csar_or_rootdir]

Positional Arguments

csar_or_rootdir

Path to a packed or unpacked TOSCA CSAR (defaults to the current directory if not specified)

Named Arguments

--instance-path, -p

Storage folder location (instead of default .opera)

--format, -f

Possible choices: yaml, json

Output format

Default: “yaml”

--output, -o

Output file location

--verbose, -v

Turns on verbose mode

Default: False


package

opera package - package TOSCA YAML templates and their accompanying files to a compressed TOSCA CSAR.

usage: opera package [-h] [--service-template SERVICE_TEMPLATE]
                     [--output OUTPUT] [--format {zip,tar}] [--verbose]
                     service_template_folder

Positional Arguments

service_template_folder

Path to the root of the service template or folder you want to create the TOSCA CSAR from

Named Arguments

--service-template, -t

Name or path to the TOSCA service template file from the root of the input folder

--output, -o

Output CSAR file path

--format, -f

Possible choices: zip, tar

CSAR compressed file format

Default: “zip”

--verbose, -v

Turns on verbose mode

Default: False


unpackage

opera unpackage - uncompress TOSCA CSAR.

usage: opera unpackage [-h] [--destination DESTINATION] [--verbose] csar

Positional Arguments

csar

Path to the compressed TOSCA CSAR

Named Arguments

--destination, -d

Path to the location where the CSAR file will be extracted to, the path will be generated in the current working directory if it isn’t specified

--verbose, -v

Turns on verbose mode

Default: False


diff

opera diff - compare TOSCA service templates and instances.

usage: opera diff [-h] [--instance-path INSTANCE_PATH] [--inputs INPUTS]
                  [--verbose] [--template-only] [--format {yaml,json}]
                  [--output OUTPUT]
                  [template]

Positional Arguments

template

TOSCA YAML service template file

Named Arguments

--instance-path, -p

Storage folder location (instead of default .opera)

--inputs, -i

Optional: YAML or JSON file with inputs that will be used along with the comparison

--verbose, -v

Turns on verbose mode

Default: False

--template-only, -t

Compare only templates without instances

Default: False

--format, -f

Possible choices: yaml, json

Output format

Default: “yaml”

--output, -o

Output file location


update

opera update - update the deployed TOSCA service template and redeploy it according to the discovered template diff.

usage: opera update [-h] [--instance-path INSTANCE_PATH] [--inputs INPUTS]
                    [--workers WORKERS] [--verbose]
                    [template]

Positional Arguments

template

TOSCA YAML service template file

Named Arguments

--instance-path, -p

Storage folder location (instead of default .opera)

--inputs, -i

Optional: YAML or JSON file with inputs that will be used for deployment update

--workers, -w

Maximum number of concurrent update threads (positive number, default 1)

Default: 1

--verbose, -v

Turns on verbose mode

Default: False


notify

opera notify - notify the orchestrator about changes after deployment and run triggers defined in TOSCA policies.

usage: opera notify [-h] [--instance-path INSTANCE_PATH] --trigger
                    TRIGGER_OR_EVENT [--notification NOTIFICATION] [--force]
                    [--verbose]

Named Arguments

--instance-path, -p

Storage folder location (instead of default .opera)

--trigger, -t, --event, -e

TOSCA policy trigger name or event that will invoke all the actions (interface operations) on policy

--notification, -n

Notification file (usually JSON) with changes that will be exposed to TOSCA interfaces

--force, -f

Skip any prompts and force execution

Default: False

--verbose, -v

Enable verbose mode

Default: False


init (deprecated)

opera init - initialize TOSCA CSAR or service template.

usage: opera init [-h] [--instance-path INSTANCE_PATH] [--inputs INPUTS]
                  [--clean] [--verbose]
                  csar

Positional Arguments

csar

TOSCA YAML service template file or CSAR

Named Arguments

--instance-path, -p

Storage folder location (instead of default .opera)

--inputs, -i

YAML or JSON file with inputs

--clean, -c

Clean storage by removing previously initialized TOSCA service template or CSAR

Default: False

--verbose, -v

Turns on verbose mode

Default: False

Note

The opera init command is deprecated (since version 0.6.1) and will probably be removed within one of the next releases. Please use opera deploy to initialize and deploy service templates or compressed CSARs.


Secrets and Environment variables

You can use the following environment variables:

Environment variable

Description

Example value

OPERA_SSH_USER

Username for the Ansible ssh
connection to a remote VM
ubuntu
(default is centos)
OPERA_SSH_IDENTITY_FILE



Path to the file containing
your private ssh key that
will be used for a
connection to a remote VM
~/.ssh/id_ed25519



OPERA_SSH_HOST_KEY_CHECKING

Disable Ansible host key
checking (not recommended)
false or f
(not case sensitive)

Danger

Be very careful with your orchestration secrets (such as SSH private keys, cloud credentials, passwords ans so on) that are stored as opera inputs. To avoid exposing them don’t share the inputs file and the created opera storage folder with anyone.

Shell completion

For easier usage of the CLI tool opera enables tab completion for all CLI commands and arguments. We use shtab in our code to generate a shell completion script. We don’t have a separate command to do that since but rather a global optional argument that will print out the completion script for the main parser. This flag is called --shell-completion/-s and it receives a shell type to generate completion for. Shtab currently supports bash and zsh so those are the options. So, after running opera -s bash|zsh the generated tab completion script will be printed out. To activate it you must source the contents which can be done with eval "$(opera -s bash)" or you can save it to a file and then source it.

# print out completion script for bash shell
(venv) $ opera -s bash
#!/usr/bin/env bash
# AUTOMATCALLY GENERATED by `shtab`

_shtab_opera_options_='-h --help -s --shell-completion'
_shtab_opera_commands_='deploy diff info init outputs package undeploy unpackage update validate'

_shtab_opera_deploy='-h --help --instance-path -p --inputs -i --workers -w --resume -r --clean-state -c --force -f --verbose -v'
_shtab_opera_deploy_COMPGEN=_shtab_compgen_files
...

# print out completion script for zsh shell
(venv) $ opera -s zsh
#compdef opera

# AUTOMATCALLY GENERATED by `shtab`

_shtab_opera_options_=(
"(- :)"{-h,--help}"[show this help message and exit]"
{-s,--shell-completion}"[Generate tab completion script for your shell]:shell_completion:(bash zsh)"
)

_shtab_opera_commands_() {
local _commands=(
"deploy:"
"diff:"
"info:"
...

# activate completion for bash directly
(venv) $ eval "$(opera -s bash)"

# activate completion for zsh directly
(venv) $ eval "$(opera -s zsh)"

Troubleshooting

Every CLI command is equipped with --help/-h switch that displays the information about it and its arguments, and with --verbose/-v switch which turns on debug mode and prints out the orchestration parameters and the results from the executed Ansible playbooks. Consider using the two switches if you face any problems. If the issue persists please have a look at the existing opera issues or open a new one yourself.

Video

This video will help you to get started with xOpera. It also shows an example of deploying a simple image resize solution to AWS Lambda: