BWCTL CLI User Guide

About BWCTL

BWCTL is a command line interface (CLI) tool that enables you to interact with public clouds using commands from your shell. The tool offers all the functionality required for SIF component management. With BWCTL you can build your fabric from scratch by setting up VPCs, orchestrator nodes, processor nodes, and workload nodes.

BWCTL-CLI SIF Management

Fig. 102 FIG. BWCTL CLI for SIF component management

BWCTL tool comes preinstalled on your fabric manager node. To use BWCTL tool, access your fabric manager node from any Linux, macOS, or Windows machine.

To run the commands, you will need a terminal window with an SSH client:

  • MacOS – Use Terminal application with built-in SSH client.
  • Linux – Use your favorite terminal window with built-in SSH client.
  • Windows 10 – If you haven’t already enabled an SSH client to use with PowerShell, PuTTY is an easy alternative. PuTTY can act as both your terminal window and your SSH client.

When creating the fabric manager in a public cloud, you are able to specify how you would like to access the virtual machine using SSH. That is, you may specify a username and password or a public key. Use these credentials to log into your VM.

However, BWCTL tools run under the username ubuntu. If you have created a different username during VM creation, simply su into ubuntu before proceeding:

jsmith@my-fabric-manager:~$ sudo su - ubuntu

BWCTL enables you to install fabric components and configure them. You can show, create, update, start, stop, and delete components of the service interconnection fabric: fabric, vpc, orchestrator, processor, workload. Also, the tool allows you to perform the same operations in batch mode i.e., on a grouping of fabric components.

Upgrading BWCTL

BWCTL tool comprises two packages: one with business logic, called bwctl, and another with resource templates, called bwctl-resources.

You can upgrade the bwctl package already installed on your fabric manager to the latest version in the family by running the command:

]$ pip3 install --upgrade bwctl

Verify that the bwctl package installed correctly by running the command:

]$ bwctl --version
bwctl/0.7.1

To upgrade the bwctl-resources package, run the command:

]$ pip3 install --upgrade bwctl-resources

Verify that the bwctl-resources package installed correctly by running the command:

]$ bwctl-resources --version
bwctl-resources/0.7.1

Configuring BWCTL

Configuring BWCTL after installation

Before you can start using BWCTL for fabric deployment, you must configure the tool with your cloud credentials.

Cloud credentials are stored in credentials.yaml located on the fabric manager at:

/home/ubuntu/.bwctl/credentials.yml

The file contains BWCTL credential details. To verify information in the configuration file, run the following command from your homedir:

]$ cat .bwctl/credentials.yml
---
# Add cloud-provider credentials that will be used when creating
# infrastructure and accessing repositories.
aws:
  # In the AWS console, select the IAM service for managing users and keys.
  # Select Users, and then Add User.  Type in a user name and check
  # programmatic access.  Users require access to EC2, S3, and Route53.
  # Copy and paste the secret access key and key ID here.
  aws_secret_access_key: *************************
  aws_access_key_id: AKIAXENPO3YJEGO5R
azr:
  # Azure provides detailed steps for generating required credentials
  # on the command line, which you can find at this URL:
  # https://docs.microsoft.com/en-us/azure/virtual-machines/linux/terraform-install-configure#set-up-terraform-access-to-azure
azr_client_id: d629229e-64f3-4c44ad1-d74d71a22209
azr_client_secret: ***********************
azr_resource_group_name: bayware-dbox
azr_subscription_id: d48827e-3c590e-9b27-54efe298b8aa
azr_tennant_id: 8deaeff5-4be7-4e11f0-1d02adf9db68
gcp:
  # Google uses a GCP Service Account that is granted a limited set of
  # IAM permissions for generating infrastructure.  From the IAM & Admin
  # page, select the service account to use and then click "create key"
  # in the drop-down menu on the right.  The JSON file will be downloaded
  # to your computer.  Put the path to that file here.
 google_cloud_keyfile_json: /home/ubuntu/credentials/gcp-credentials.json
s3_repo:
  # Access to Bayware Ubuntu APT and CentOS YUM repositories is restricted.
  # Please contact Bayware for the appropriate credentials.
  aws_secret_access_key: *************************
  aws_access_key_id: AKIAXENPO3YJEKOP
s3_state:
  aws_secret_access_key: *************************
  aws_access_key_id: AKIAXENPO3GFN8725R

Note: You can use more than one configuration file on your fabric manager node. As an example, you can use a separate file for each fabric. You will need to add the path to a given credential file at the command line when you create a fabric or in a batch file for the kind fabric.

Changing BWCTL configuration

If you need to change BWCTL configuration, update its configuration file stored locally at /home/ubuntu/.bwctl/credentials.yml.

Getting started with BWCTL

Typing the first command

Using Linux command line

To give a command in BWCTL using the Linux command line, you will type bwctl along with the required input and press the <return> key.

To start using BWCTL tool, run the command:

]$ bwctl --help
Usage: bwctl-api [OPTIONS] COMMAND [ARGS]...

  Bayware CLI

Options:
 -v, --version  Print version and exit.
 -h, --help     Show this message and exit.

Commands:
  configure  Configure commands
  create     Create commands
  delete     Delete commands
  export     Export fabric specification to file
  leave      Leave commands
  restart    Restart commands
  set        Set commands
  show       Show commands
  start      Start commands
  stop       Stop commands
  update     Update commands

Using BWCTL command line

To switch from the Linux command line to the BWCTL command line, you will type bwctl and press the <return> key:

]$ bwctl
(None) bwctl>

The BWCTL command line begins with the fabric name in parentheses. If no fabric is set, the parentheses contain the word None.

To get help in the BWCTL command line, run the command:

(None) bwctl> help

To quit the BWCTL command line, run the command:

(None) bwctl> quit

Command structure

The BWCTL command line is comprised of several components:

  • bwctl
  • any options required by bwctl to execute the command
  • the command and, in most cases, subcommand
  • any arguments required by the command
]$ bwctl --help
Usage: bwctl [OPTIONS] COMMAND [ARGS]...

Command line options

You can use the following command line options by typing them on the command line immediately after bwctl:

–version, -v
A boolean switch that displays the current version of BWCTL-API tool.
–help, -h
A boolean switch that displays the commands available for execution.

You can finish the command line with the --help option following either command or subcommand. The output will always give you a hint about what else you need to type.

To see the help for the command, type the command only followed by --help and press <return>:

]$ bwctl show --help
Usage: bwctl show [OPTIONS] COMMAND [ARGS]...

  Show commands

Options:
  -h, --help  Show this message and exit.

Commands:
  fabric        Show fabric information
  orchestrator  Show orchestrator information
  processor     Show processor information
  vpc           Show VPC information
  workload      Show workload information

To see the help for the subcommand, type the command followed by the subcommand and --help and press <return>:

]$ bwctl show workload --help
Usage: bwctl show workload [OPTIONS]

  Show workload information

Options:
  --name TEXT                Show full information on a given workload.
  --cloud [azr|aws|gcp|all]  List workloads or show full information on them.
  --full                     Show full information on workloads.
  -h, --help                 Show this message and exit.

Different commands support different options. Detailed information on the available options can be found in the documentation section Using commands.

Commands

With BWCTL you can manage all fabric components in your service interconnection fabric. Each command includes the entity kind as a subcommand and the entity name as an argument. Some commands have an entity specification file as a mandatory argument.

BWCTL supports the following commands:

configure KIND NAME [OPTIONS]
The command configures one or multiple entities. The specification file is optional for this command.
create KIND NAME [OPTIONS]
The command creates one or multiple entities. The specification file is mandatory for the batch kind only.
delete KIND NAME [OPTIONS]
The command deletes one or multiple entities. The specification file is mandatory for the batch kind only.
export KIND FILE [OPTIONS]
The command exports the fabric specification to a file.
leave KIND
The command causes the tool to exit from the current fabric (namespace).
restart KIND NAME [OPTIONS]
The command restarts one or multiple entities. You can use options instead of the name to specify entities in the command.
set KIND NAME
The command causes the tool to enter the specified fabric (namespace).
show KIND NAME [OPTIONS]
The command shows one or multiple entities. You can use options instead of the name to specify entities in the command.
start KIND NAME [OPTIONS]
The command starts one or multiple entities. You can use options instead of the name to specify entities in the command.
stop KIND NAME [OPTIONS]
The command updates one or multiple entities. You can use options instead of the name to specify entities in the command.
update KIND NAME [OPTIONS]
The command updates one or multiple entities. You can use options instead of the name to specify entities in the command.

Kinds

The diagram below depicts the service interconnection fabric components and relationships between them.

BWCTL-CLI Fabric Components

Fig. 103 FIG. Fabric components

To see the entity types, you can run the show command without a subcommand:

]$ bwctl show
Usage: bwctl show [OPTIONS] COMMAND [ARGS]...

  Show commands

Options:
  -h, --help  Show this message and exit.

Commands:
  fabric        Show fabric information
  orchestrator  Show orchestrator information
  processor     Show processor information
  vpc           Show VPC information
  workload      Show workload information

BWCTL manages the following entity types:

fabric NAME
The fabric entity represents a fabric itself.
orchestrator NAME
The orchestrator entity represents a VM playing orchestrator node role.
processor NAME
The processor entity represents a VM playing processor node role.
vpc NAME
The vpc entity represents a cloud VPC.
workload NAME
The workload entity represents a VM playing workload node role.

Batch

With BWCTL CLI, you can use a single batch command to manage a set of entities of the same or different types. Below is an example of the command.

]$ bwctl create batch azr-infra-batch.yml

Using commands

Supported commands for each entity type

There are five groups of entities, each of which has its own set of commands.

configure, create, delete, export, leave, set, show

This set of commands is applicable to the following types of entities:

  • FABRIC
create, delete, show

This set of commands is applicable to the following types of entities:

  • VPC
configure, create, delete, show, update

This set of commands is applicable to the following types of entities:

  • ORCHESTRATOR
configure, create, delete, show, start, stop, update

This set of commands is applicable to the following types of entities:

  • PROCESSOR
  • WORKLOAD
create, delete

This set of commands is applicable to the following types of entities:

  • BATCH

Managing fabrics

You can manage fabrics using the following commands:

configure fabric NAME [OPTIONS]
The command configures the fabric. You can use the options in this command as follows:
--company-name <company-name>
fabric’s company name.
--credentials-file <ceredentials-file>
path to file with credentials for public clouds.
--ssh-private-key <ssh-private-key>
fabric manager’s SSH private key. The SSH private key is optional. If not specified, the tool will create an SSH key dedicated to the fabric.
--file <filename>
file with fabric manager configuration.
create fabric NAME
The command creates the fabric.
delete fabric NAME
The command deletes the fabric.
leave fabric
The command leaves the current fabric.
set fabric NAME
The command sets the fabric as current.
show fabric [OPTIONS]
The command shows the current fabric components if the fabric is set. If not set, the command outputs the list of all available fabrics. Also, you can always use this option:
--list-all
to show the list of all available fabrics.
export fabric FILE
The command exports all fabric components and their specifications into a file.

An example of the fabric specification file is shown below.

]$ cat fabric-spec.yml
---
apiVersion: fabric.bayware.io/v2
kind: Fabric
metadata:
  description: 'Fabric ohio5784'
  name: 'ohio5784'
spec:
  companyName: ohioinc
  credentialsFile: /home/ubuntu/credentials/credentials.yml
  sshKeys:
    privateKey: {}

Managing VPCs

You can manage VPCs using the following commands:

create vpc aws|azr|gcp ZONE [OPTIONS]

The command creates a VPC in the current fabric. The VPC is created in the specified availability zone of the selected public cloud provider. You can use the options in this command as follows:

--file <filename>
file with VPC configuration.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.

Note: You can see a list of availability zones by running the command bwctl show vpc --zones.

delete vpc NAME

The command deletes the vpc in the current fabric. You can use the options in this command as follows:

--dry-run

running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
show vpc [OPTIONS]

The command shows the list of all VPCs in the current fabric if run without any option. You can use the options in this command as follows:

--name <vpc-name> shows information on a given VPC.

--cloud <aws|azr|gcp|all> lists all VPCs in a given cloud.

--full instead of list, provides full information on vpc.

--zones outputs the list of zones in which VPC can be created.

An example of the VPC specification file is shown below.

]$ cat vpc-spec.yml
---
apiVersion: fabric.bayware.io/v2
kind: Vpc
metadata:
  description: 'Azure VPC'
  fabric: 'ohio5784'
  name: 'azr1-vpc-ohio5784'
spec:
  cloud: 'azr'
  properties:
    zone: 'southcentralus'

Managing orchestrators

You can manage orchestrators using the following commands:

configure orchestrator NAME [OPTIONS]

The command configures the orchestrator node in the current fabric. You can use the options in this command as follows:

--file <filename>
file with orchestrator configuration.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
create orchestrator controller|telemetry|events VPC [OPTIONS]

The command creates the vpc in the current fabric. You can use the options in this command as follows:

--file <filename>
file with vpc configuration.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
delete orchestrator NAME

The command deletes the orchestrator node in the current fabric. You can use the options in this command as follows:

--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
show orchestrator [OPTIONS]

The command shows the list of all orchestrators in the current fabric if run without any option. You can use the options in this command as follows:

--name <node-name>
shows information on a given orchestrator node.
--cloud <aws|azr|gcp|all>
lists all VPCs in a given cloud.
--full
instead of list, provides full information on orchestrator nodes.
update orchestrator NAME

The command updates the orchestrator node in the current fabric. You can use the options in this command as follows:

--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.

An example of the orchestrator specification file is shown below.

]$ cat orchestrator-spec.yml
---
apiVersion: fabric.bayware.io/v2
kind: Orchestrator
metadata:
  description: 'Policy controller'
  fabric: 'ohio5784'
  name: 'aws1-c01-ohio5784'
spec:
  role: 'manager'
  type: 'controller'
  properties:
     vpc: 'aws1-vpc-ohio5784'
state: 'configured'

Managing processors

You can manage processors using the following commands:

configure processor NAME [OPTIONS]
The command configures the processor node in the current fabric. You can use the options in this command as follows:
--orchestrator <FQDN>
orchestrator FQDN.
--file <filename>
file with processor configuration.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
create processor VPC [OPTIONS]
The command creates the processor node in the current fabric. You can use the options in this command as follows:
--file <filename>
file with processor configuration.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
delete processor NAME
The command deletes the processor node in the current fabric. You can use the options in this command as follows:
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
show processor [OPTIONS]
The command shows the list of all processors in the current fabric if run without any option. You can use the options in this command as follows:
--name <node-name>
shows information on a given processor node.
--cloud <aws|azr|gcp|all>
lists all processors in a given cloud.
--full
instead of list, provides full information on processor nodes.
start processor [NAME] [OPTIONS]
The command starts the given processor node in the current fabric if the node’s name is specified. You can use the options in this command as follows:
--all
starts all processor nodes.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
stops processor [NAME] [OPTIONS]
The command stops the given processor node in the current fabric if the node’s name is specified. You can use the options in this command as follows:
--all
stops all processor nodes.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
update processor [NAME] [OPTIONS]
The command updates the given processor node in the current fabric if the node’s name is specified. You can use the options in this command as follows:
--all
updates all processor nodes.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.

An example of the processor specification file is shown below.

]$ cat processor-spec.yml
---
apiVersion: fabric.bayware.io/v2
kind: Processor
metadata:
  description: 'Azure processor'
  fabric: 'ohio5784'
  name: 'azr1-p01-ohio5784'
spec:
  config:
    orchestrator: 'controller-ohio5784.ohioinc.poc.bayware.io'
  properties:
    vpc: 'azr1-vpc-ohio5784'
state: 'started'

Managing workloads

You can manage workloads using the following commands:

configure workload NAME [OPTIONS]
The command configures the workload node in the current fabric. You can use the options in this command as follows:
--orchestrator <FQDN>
orchestrator FQDN.
--file <filename>
file with workload configuration.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
create workload VPC [OPTIONS]
The command creates the workload node in the current fabric. You can use the options in this command as follows:
--file <filename>
file with processor configuration.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
delete workload NAME
The command deletes the workload node in the current fabric. You can use the options in this command as follows:
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
show workload [OPTIONS]
The command shows the list of all workloads in the current fabric if run without any option. You can use the options in this command as follows:
--name <node-name>
shows information on a given workload node.
--cloud <aws|azr|gcp|all>
lists all workloads in a given cloud.
--full
instead of list, provides full information on workload nodes.
start workload [NAME] [OPTIONS]

The command starts the given workload node in the current fabric if the node’s name is specified. You can use the options in this command as follows:

--all
starts all workload nodes.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
stops workload [NAME] [OPTIONS]

The command stops the given workload node in the current fabric if the node’s name is specified. You can use the options in this command as follows:

--all
stops all workload nodes.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
update workload [NAME] [OPTIONS]

The command updates the given workload node in the current fabric if the node’s name is specified. You can use the options in this command as follows:

--all
updates all workload nodes.
--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.

An example of the workload specification file is shown below.

]$ cat workload-spec.yml
---
apiVersion: fabric.bayware.io/v2
kind: Workload
metadata:
  description: 'Azure workload'
  fabric: 'ohio5784'
  name: 'azr1-w01-ohio5784'
spec:
  config:
    orchestrator: 'controller-ohio5784.ohioinc.poc.bayware.io'
  properties:
    vpc: 'azr1-vpc-ohio5784'
state: 'started'

Working with batches

You can manage batch file execution using the following commands:

create batch FILE [OPTIONS]

The command creates the batch. The specification file is mandatory for this command.

--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.
delete batch FILE [OPTIONS]

The command deletes the batch. The specification file is mandatory for this command.

--dry-run
running the command with this option doesn’t make any changes but shows which changes will be made if you run the command without the --dry-run option.

An example of the batch specification file is shown below.

---
apiVersion: fabric.bayware.io/v2
kind: Batch
metadata:
  name: backend-infra-and-config-template
  description: 'Creates VPC, processor, and three workloads'
spec:
  - kind: Workload
    metadata:
      description: 'optional description'
      fabric: 'texas2270'
      name: 'azr1-w01-texas2270'
    spec:
      config:
        domain: 'cloud-net'
        orchestrator: 'controller-texas2270.texasinc.poc.bayware.io'
        password: 'messycard58'
        username: 'wkld-azr'
      properties:
      vpc: 'azr1-vpc-texas2270'
    state: 'started'
  - kind: Workload
    metadata:
      description: 'optional description'
      fabric: 'texas2270'
      name: 'azr1-w02-texas2270'
    spec:
      config:
        orchestrator: 'controller-texas2270.texasinc.poc.bayware.io'
      properties:
      vpc: 'azr1-vpc-texas2270'
    state: 'started'
  - kind: Processor
    metadata:
      description: 'optional description'
      fabric: 'texas2270'
      name: 'azr1-p01-texas2270'
    spec:
      config:
        orchestrator: 'controller-texas2270.texasinc.poc.bayware.io'
      properties:
      vpc: 'azr1-vpc-texas2270'
     state: 'started'
  - kind: Vpc
    metadata:
      description: 'optional description'
      fabric: 'texas2270'
      name: 'azr1-vpc-texas2270'
    spec:
      cloud: 'azr'
      properties:
      zone: 'southcentralus'

BWCTL cheat sheet

../_images/bwctl-cli-cheat-sheet.png

Fig. 104 Fig. BWCTL-CLI Cheat Sheet