What's on this page

LMCTL Command Line Tool

Objectives

Pre-requisites

Python

Before you begin you will need to install:

As it’s possible to have both Python2 and Python3 installed on one machine, this guide will make use of python3 and pip3 commands instead of python and pip. If you only have Python3, then you may use the latter instead. Verify which command works for you by running both:

python --version

python3 --version

Use the version which responds with a 3.x number.

Python Virtual Environment

It is highly recommended that you install and make use of a virtual environment when installing LMCTL. This will keep all dependencies used by LMCTL isolated from other Python applications on your machine. It will also allow you to have alternate versions installed, in two separate environments, which is useful when there is a new major version of Stratoss™ Lifecycle Manager and LMCTL, with potential non-backward compatible changes.

We recommend installing Virtualenv:

python3 -m pip install virtualenv

Create a new virtual environment with virtualenv, specifying a suitable name for it:

python3 -m virtualenv lmctl-env

This will create an environment in a directory named lmctl-env (or any name you decide). Once created, the virtual environment can be activated anytime with:

source lmctl-env/bin/activate

On Windows, try:

lmctl-env\Scripts\activate.bat

Ensure the environment is active anytime you install or use LMCTL to maintain isolation from your global Python environment.

To deactivate the virtual environment at anytime just execute:

deactivate

Install LMCTL

Activate any virtual environment (if you plan to use one) and install LMCTL with pip:

python3 -m pip install lmctl

To install a specific version see available versions, add the number to the end of the command with ==:

python3 -m pip install lmctl==2.0.5

Verify the installation has worked by executing:

lmctl --version

Access the help section of LMCTL with:

lmctl --help

Configure LMCTL environments

To allow LMCTL to access your Stratoss™ Lifecycle Manager and Resource Managers, you must provide access credentials for them in a configuration YAML file.

  1. Create a new file named lmctl-config.yaml (or any name suffixed with .yaml of your choice)

    touch $HOME/lmctl-config.yaml
    
    # For Windows
    type nul > %HomeDrive%%HomePath%\lmctl-config.yaml
    
  2. Add the following content to the file:

    ## Each section provides configuration for a named environment.
    ## In this example a 'dev' environment is created
    dev:
       ## Useful description shown when running 'lmctl env list'
       description: My private dev environment
    
       ## Each environment must configure access to LM
       ## (Required)
       alm:
           ## The host of the API gateway of your LM environment
           ## (Required)
           ip_address: localhost
    
           ## The port of the API gateway of your LM environment
           ## (Required)
           port: 8081
    
           ## Set to True if the API gateway is accessed using
           ## the HTTPs protocol instead of HTTP
           secure_port: True
    
           ## The username to use when accessing the Stratoss LM APIs.
           ## Leave empty if security is disabled on your Stratoss LM
           username: jack
    
           ## The host of the API on the LM UI used to authenticate a user
           ## (Required when 'username' is set)
           auth_address: localhost
    
           ## The port of the API on the LM UI used to
           ## authenticate a user (leave blank to use same value as 'port')
           auth_port: 8080
    
           ## The password to use when authenticating the user
           ## given by 'username'.
           ## Can be left blank and provided as a command line option
           ## or at prompt to any command that requires it
           # password: jack
    
       ## If planning to manage projects which make use of VNFC resources
       ## intended for an Ansible RM then access must be configured
       arm:
           ## Multiple Ansible RMs are separated by name
           ## The name here must match the name given to the RM when onboarded to the LM environment
           defaultrm:
               ## The host of the Ansible RM API
               ## (Required)
               ip_address: localhost
    
               ## The port of the Ansible RM API
               ## (Required)
               port: 31081
    
               ## Set to True if the API gateway is accessed using the
               ## HTTPs protocol instead of HTTP
               secure_port: True
    
               ## Set if the url of the RM should be different to the
               ## host, port, secure_port settings used above for lmctl to access the RM
               ## Do not include API path and do not include a trailing slash
               onboarding_addr: https://osslm-ansible-rm:8443
    
  3. Update the values in this file to reflect the access address and credentials for your target environment(s)

  4. Create an environment variable called LMCONFIG and set it to the path of the created file:

    export LMCONFIG=$HOME/lmctl-config.yaml
    
    # For Windows
    set LMCONFIG=%HomeDrive%%HomePath%\lmctl-config.yaml
    
  5. Verify the configuration file is found by LMCTL using the env list command:

    lmctl env list
    

    Example output:

    lmctl: Available environments:
    lmctl:  - dev: My private dev environment
    

Secure environments

As seen in Configure LMCTL environments you may configure LMCTL with the username to use when authenticating with a secure LM environment. You may also include the password, although this is discouraged as it will be visible in plain-text.

Instead it is recommended to provide the password on each LMCTL command that requires access to the secure LM environment. If a command requires access and there is no value for password in the configuration file, a prompt will be displayed requesting the password:

lmctl project push dev
> Please enter a password for user jack []:

To provide the password upfront, avoiding prompts in non-interactive usage (such as a Jenkins pipeline), use the --pwd option included on the command:

lmctl project push dev --pwd mypassword

Understanding LMCTL Projects

A project represents a single NS/VNF to be developed, tested and published for usage in Stratoss™ Lifecycle Manager environments. LMCTL helps developers manage a project through a recommended lifecycle, making use of common stages in continuous integration and deployment pipelines:

The main benefit of LMCTL is it’s ability to organise the collection of artifacts required by a NS or VNF, then orchestrate the laborious task of applying changes across Stratoss LM environments for testing.

Once a project is ready for publishing, LMCTL is used to produce a distributable package that can be shared to other LMCTL users and deployed to their development environments or to pre-prod/production environments.

LMCTL also supports bundling VNFCs as part of a VNF project, providing further automation by pushing each to a specified Resource Manager when the VNF is deployed to a target Stratoss LM environment.

As projects managed by LMCTL are organised by a common directory tree, the artifacts of a project are maintained independent of a single Stratoss LM environment. Instead they are pushed into an environment for modification and testing, before the changes are pulled back into the local file system - this makes it simple to integrate with any existing version control or change management process, without sacrificing the ability to view and modify each artifact in the fit-for-purpose user interfaces provided by Stratoss LM.

Creating a Project

Project Structure

A project is organised by a directory tree which includes the following artifacts:

myproject/
    lmproject.yaml
    Descriptor/
    Behaviour/
        Tests/
        Templates/
        Runtime/
    VNFCs/

The following table details the relevance of each item in the project tree:

Item Requirement Description
lmproject.yaml mandatory This file details the meta-data required by LMCTL to manage the project
Descriptor mandatory This directory must contain a descriptor file called assembly.yml, representing the top level service
Behaviour optional This optional directory contains the Assembly Configurations and Scenarios for behavior testing
Behaviour/Tests optional This optional directory contains the Test Scenarios for behavior testing
Behaviour/Templates optional This optional directory contains the Assembly Templates for behavior testing
Behaviour/Runtime optional This optional directory contains the Runtime Scenarios, such as Diagnostic tests, for behavior testing
VNFCs optional This optional directory can contain one or more to be used by the service in this project, each VNFC is pushed to a target Ansible RM

Project File

A project directory must contain a lmproject.yaml file, which details the meta-data required by LMCTL. At minimum, this file must provide a name for the project, used in console output and the names for packages produced by LMCTL.

name: ippbx

If the project features nested VNFCs, then additional information must be specified to ensure they are included in the package produced for this project:

name: ippbx
vnfcs:
  definitions:
    ...
  packages:
    ...

Creating a new Project

A new project may be created by manually initialising the directory tree and all the required artifacts or, more efficiently, by using the project create command provided by LMCTL:

  1. Create a new directory using the name of your intended project and navigate to it:

    mkdir example && cd example
    
  2. Execute the project create, specifying the name, version and servicetype:

    lmctl project create --name example --version 1.0 --servicetype NS
    
  3. View the contents of the sub-directories and files created by LMCTL

Creating a Project with VNFCs

To include nested VNFCs in your project, specify the name of each with the --vnfc option:

  1. Create a new directory using the name of your intended project and navigate to it:

    mkdir example && cd example
    
  2. Execute the project create, specifying the name, version and servicetype. Also include the names of each VNFC to be included:

    lmctl project create --name example --version 1.0 --servicetype VNF --vnfc vnfcA --vnfc vnfcB
    
  3. View the contents of the sub-directories and files created by LMCTL. Note the new VNFC directory and the vnfcA and vnfcB sub-directories.

Creating a Project from existing sources in LM

If you have already designed a service in Stratoss LM you can base a project around it and pull the existing content using LMCTL. (Note: currently it is not possible to pull the contents of VNFCs from Ansible RM):

  1. Create a Project as explained in Creating a new Project. Ensure the name and version correspond with the service design in Stratoss LM you intend to base this project on
  2. Use project pull command to pull the contents from a target named environment:

    lmctl project pull dev
    
  3. Verify the Descriptor/assembly.yml file has been populated with the design of your service and the Behaviour directory has been populated with any Assembly Configurations and/or Scenarios you have in Stratoss LM

Including VNFCs

VNFCs can be included in any project by creating a directory for each in the VNFCs sub-directory.

myproject/
    lmproject.yaml
    Descriptor/
        ...
    Behaviour/
        ...
    VNFCs/
      vnfcA/
        ...
      vnfcB/
        ...

Each VNFC must then be added to the lmproject.yaml and linked to a VNFC package execution to indicate the target RM type. This is important as the RM type determines the format of the VNFC package, included in your project, making it compatible with the target RM.

As seen in Creating a Project with VNFCs you can add VNFCs when creating your project, using the --vnfc option on the create command. To add a VNFC after creating a project, complete the following:

  1. Create a new directory in the VNFC sub-directory:

    mkdir ./VNFC/vnfcC
    
  2. Add the required VNFC artifacts to the new sub-directory (artifacts depend on the intended RM type, see VNFC RM Packaging Types)

  3. Modify the lmproject.yaml file to include a definition for your VNFC and a package execution. It is best practice to make the VNFC name the same as the directory:

    vnfcs:
     definitions:
       ...
       vnfcC:
         directory: vnfcC
     packages:
       ansible-rm-vnfcs:
         packaging-type: ansible-rm
         executions:
         ...
         - vnfc: vnfcC
    

On the next build of this project the VNFC will be packaged and included.

VNFC RM Packaging Types

Currently LMCTL supports packaging VNFCs for the Ansible RM.

Ansible RM VNFCs

Any VNFC included in a project intended for the Ansible RM is expected to have the following structure:

Directory Requirement Description
descriptor mandatory must contain a Resource descriptor file with a file name matching the VNFCs name e.g. a VNFC named vnfcA must have a file called vnfcA.yml
lifecycle mandatory must contain valid ansible playbooks for each supported lifecycle: Install.yml, Start.yml, Configure.yml, Stop.yml, Uninstall.yml
Meta-Inf mandatory must contain a mainifest.MF file with details of the VNFC, see example below

The manifest.MF file must contain the name of the VNFC, its version and the resource manager. The name must match the name of the VNFC resource descriptor name, and the VNFC directory:

name: docker-network
version: 1.0
resource-manager: docker

Building a Project

The project build command is used to produce a distributable package for a project. A build does not require access to a Stratoss LM environment, so can be executed anytime on the project source by navigating to it’s directory and executing the command:

lmctl project build

This command will produce a .tgz package in the auto-created LMCTL build workspace directory (_lmctl/_build) relative to your project. This package includes:

The structure of the directories and artifacts in the package are determined by LMCTL and should not be altered.

Pushing a Project

The project push command is used to push the artifacts of a project to a target Stratoss LM environment. This command will:

In all cases the new versions of each artifact will overwrite any existing version present in the environment.

LMCTL performs a push by first executing a build, to produce a .tgz package, then orchestrates pushing the content of the package to the relevant services. As a result, it is not necessary to explicitly execute a build first.

Pushing a Project (without VNFCs)

To build and push your project, navigate to it’s directory then:

  1. Execute the project push command, naming the target environment from your LMCTL configuration file:

    lmctl project push dev
    
  2. Verify the descriptor and behavior scenarios/configurations are present in your Stratoss LM environment

Pushing a Project (with VNFCs)

If your project includes VNFCs, you will need to specify the name of the Ansible RM (from your LMCTL configuration file) to push them to:

  1. Execute the project push command, naming the target environment from your LMCTL configuration file and naming the Ansible RM to push VNFCs to:

    lmctl project push dev --armname defaultrm
    
  2. Verify the descriptor and behavior scenarios/configurations are present in your Stratoss LM environment

  3. Verify the VNFCs are present in the Ansible RM using it’s APIs

  4. Verify the resource descriptors for your VNFCs are present in Stratoss LM

Testing a Project

The project test command is used to execute the behavior scenarios included in the Behaviour/Tests sub-directory of your project. This command will:

LMCTL will perform a push prior to executing the tests, to ensure the environment has the latest changes. As a result, it is not necessary to explicitly execute a build or push first.

To test your project, navigate to it’s directory then complete the following:

  1. Execute the project test command, naming the target environment from your LMCTL configuration file and, if VNFCs are included, naming the Ansible RM to push VNFCs:

    lmctl project test dev --armname defaultrm
    
  2. Monitor the progress of the tests in the console OR by opening the behavior tab of your service design in the Stratoss LM user interface

Pulling Project changes from LM

As discussed in Creating a Project from existing sources in LM you may pull changes to the descriptor and behavior artifacts of your project from a Stratoss LM environment with the project pull command.

After making changes in the Stratoss LM user interfaces, pull the changes to your local copy by navigating to the project’s directory and completing the following:

  1. Execute the project pull command, naming the target environment from your LMCTL configuration file to pull from:

    lmctl project pull dev
    
  2. Verify the Descriptor/assembly.yml file has been populated with the design of your service and the Behaviour directory has been populated with any Assembly Configurations and/or Scenarios you have in Stratoss LM

A backup of project artifacts prior to the pull are stored in the _lmctl/_prepull directory relative to your project. If you realise you pulled changes from an environment by mistake, you can revert the changes by copying the contents from the pre-pull directory. Note: the pre-pull directory only maintains a backup version of each artifact prior to the last pull.

Distributing Project Packages

The distributable package produced by a build of your project (also produced on a push and test) can be shared to another user/system to be deployed to other Stratoss LM environments. Pushing a package works similar to a project push, the difference is it starts from a pre-built package rather than building from source.

To deploy a package produced by LMCTL, complete the following:

  1. Download/copy the .tgz package you intend to deploy, to a target location on your machine (navigate to this location)
  2. Execute the pkg push command, naming the target environment from your LMCTL configuration file. If VNFCs are included, also name the Ansible RM to push VNFCs:

    lmctl pkg push example-1.0.tgz dev --armname defaultrm
    
  3. Verify the descriptor and behavior scenarios/configurations are present in your Stratoss LM environment

  4. Verify the VNFCs are present in the Ansible RM using it’s APIs

  5. Verify the resource descriptors for your VNFCs are present in Stratoss LM

Command Reference

The following details the complete range of commands and their arguments/options in LMCTL. Note: similar information can be viewed using --help option with your installed LMCTL.

lmctl --help

env

Commands for inspecting available Stratoss LM environments

lmctl env --help

env list

List all available environments from an LMCTL configuration file. Uses the configuration file set on the LMCONFIG environment variable unless an alternative is provided with the --config option.

lmctl env list

Options

Option Description Default Example
config path to an LMCTL configuration file to use instead of the file specified on LMCONFIG environment variable - –config /home/user/my_lmctl_config.yaml

pkg

Commands for managing a package built from a NS/VNF Project

lmctl pkg --help

pkg push

Push a previously built pacakge to a Stratoss LM environment

lmctl pkg push PACKAGE ENVIRONMENT

Arguments

Argument Description Default
package path to the package to be pushed -
environment name of the environment from the LMCTL configuration file to push the contents of the package to -

Options

Option Description Default Example
config path to an LMCTL configuration file to use instead of the file specified on LMCONFIG environment variable - –config /home/user/my_lmctl_config.yaml
armname if using ansible-rm packaging the name of ARM to upload VNFCs to must be provided defaultrm –armname edgerm
pwd password used for authenticating with LM (only required if LM is secure and a username has been included in the environment config) - –pwd secret

project

Commands for managing a NS/VNF project

lmctl project --help

project build

Build distributable package for a project

lmctl project build PROJECT

Arguments

Argument Description Default
project path to the project directory (which includes a valid lmproject.yaml file) ./ (current directory)

project create

Create a new Project in a target directory

lmctl project create LOCATION

Arguments

Argument Description Default
location path to the directory the project should be created in ./ (current directory)

Options

Option Description Default Example
name name of the Service managed in the project (target directory name) –name myexample
version version of the Service managed in the project 1.0 –version 2.1
servicetype type of Service managed in this project (NS or VNF) NS –servicetype VNF
vnfc Names of VNFCs to initiate - –vnfc firstVnfc –vnfc anotherVnfc

project list

List element(s) of a Project

lmctl project list ELEMENT

Arguments

Argument Description Default
element name of the element to be listed (possible options: tests) -

Options

Option Description Default Example
project path to the project directory (which includes a valid lmproject.yaml file) ./ –project /home/user/example

project pull

Pull contents of the Project artifacts from a LM environment

lmctl project pull ENVIRONMENT

Arguments

Argument Description Default
environment name of the environment from the LMCTL configuration file to pull from -

Options

Option Description Default Example
project path to the project directory (which includes a valid lmproject.yaml file) ./ –project /home/user/example
config path to an LMCTL configuration file to use instead of the file specified on LMCONFIG environment variable - –config /home/user/my_lmctl_config.yaml
pwd password used for authenticating with LM (only required if LM is secure and a username has been included in the environment config) - –pwd secret

project push

Push project to a LM environment

lmctl project push ENVIRONMENT

Arguments

Argument Description Default
environment name of the environment from the LMCTL configuration file to pull from -

Options

Option Description Default Example
project path to the project directory (which includes a valid lmproject.yaml file) ./ –project /home/user/example
config path to an LMCTL configuration file to use instead of the file specified on LMCONFIG environment variable - –config /home/user/my_lmctl_config.yaml
armname if using ansible-rm packaging the name of ARM to upload VNFCs to must be provided defaultrm –armname edgerm
pwd password used for authenticating with LM (only required if LM is secure and a username has been included in the environment config) - –pwd secret

project test

Execute the behavior tests of the project

lmctl project test ENVIRONMENT

Arguments

Argument Description Default
environment name of the environment from the LMCTL configuration file to pull from -

Options

Option Description Default Example
project path to the project directory (which includes a valid lmproject.yaml file) ./ –project /home/user/example
config path to an LMCTL configuration file to use instead of the file specified on LMCONFIG environment variable - –config /home/user/my_lmctl_config.yaml
armname if using ansible-rm packaging the name of ARM to upload VNFCs to must be provided defaultrm –armname edgerm
tests specify individual tests to execute by name * (execute all) –tests ScaleTest –tests HealTest
pwd password used for authenticating with LM (only required if LM is secure and a username has been included in the environment config) - –pwd secret