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

The development version of the package is available on Test PyPI and the installation goes as follows.

(.venv) $ pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ 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

metadata:
  template_name: "hello-world"
  template_author: "XLAB"
  template_version: "1.0"

node_types:
  hello_type:
    derived_from: tosca.nodes.SoftwareComponent
    interfaces:
      Standard:
        inputs:
          marker:
            value: { get_input: marker }
            type: string
        operations:
          create: playbooks/create.yaml
          delete: playbooks/delete.yaml

topology_template:
  inputs:
    marker:
      type: string
      default: default-marker

  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 Ansible playbook that implements the create TOSCA operation looks like this:

---
- hosts: all
  gather_facts: false

  tasks:
    - name: Make the location
      file:
        path: /tmp/playing-opera/hello
        recurse: true
        state: directory

    - name: Ansible was here
      copy:
        dest: /tmp/playing-opera/hello/hello.txt
        content: "{{ marker }}"

And the playbook for destroying the service is below.

---
- hosts: all
  gather_facts: false

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

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

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

Tip

You can retrieve currently installed version with opera --version/-v.

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 CLI 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	package templates and accompanying files into CSAR
opera unpackage	unpackage CSAR into directory
opera diff	compare service templates and instances
opera update	update/redeploy template and instances
opera notify	notify the orchestrator about changes after the deployment and run triggers defined in TOSCA policies

The commands can be executed in a random order and the orchestrator will warn you in case of 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 TOSCA application described in YAML or CSAR.

UsageDescriptionExample

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

options

--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.

UsageDescriptionExample

The opera undeploy command does not take any positional arguments.

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

options

--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.

UsageDescriptionExample

usage: opera validate [-h] [--instance-path INSTANCE_PATH] [--inputs INPUTS]
                      [--executors] [--verbose]
                      [csar_or_service_template]

Positional Arguments

csar_or_service_template

TOSCA YAML service template file or CSAR

options

--instance-path, -p

Storage folder location (instead of default .opera)

--inputs, -i

YAML or JSON file with inputs

--executors, -e

Validate TOSCA templates and also the executors (e.g., Ansible playbooks) behind them

Default: False

--verbose, -v

Turns on verbose mode

Default: False

---

outputs

opera outputs - print the outputs from service template (after deployment/undeployment).

UsageDescriptionExample

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

options

--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.

UsageDescriptionExample

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)

options

--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 (zipped) TOSCA CSAR.

UsageDescriptionExample

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

options

--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 (to a specified directory).

UsageDescriptionExample

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

Positional Arguments

csar

Path to the compressed TOSCA CSAR

options

--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.

UsageDescriptionExample

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

options

--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.

UsageDescriptionExample

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

Positional Arguments

template

TOSCA YAML service template file

options

--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.

UsageDescriptionExample

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

options

--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

---

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 and 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_subparsers=('deploy' 'diff' 'info' 'notify' 'outputs' 'package' 'undeploy' 'unpackage' 'update' 'validate')

_shtab_opera_option_strings=('-h' '--help' '-s' '--shell-completion' '--version' '-v')
_shtab_opera_deploy_option_strings=('-h' '--help' '--instance-path' '-p' '--inputs' '-i' '--workers' '-w' '--resume' '-r' '--clean-state' '-c' '--force' '-f' '--verbose' '-v')
...

# 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)"
  {--version,-v}"[Get current opera package version]:version:"
)

_shtab_opera_commands_() {
  local _commands=(
    "deploy:"
    "diff:"
    "info:"
    "notify:"
    "outputs:"
    "package:"
    "undeploy:"
    "unpackage:"
    "update:"
    "validate:"
  )
...

# 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.