BWCTL CLI Manual

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

First, start the BWXTL initalization process by running the command:

]$ bwctl init

You should see this output:

[2019-09-25 17:30:12.156] Welcome to bwctl initialization
[2019-09-25 17:30:12.156]  Fabric manager
[2019-09-25 17:30:12.156]   Company name (value is required):

In interactive mode, provide all required values when prompted.

Note

Press <Enter> to accept the default values.

After the initialization you should have a configuration similar to:

[2019-09-25 17:30:12.156]  Welcome to bwctl initialization
[2019-09-25 17:30:12.156]  Fabric manager
[2019-09-25 17:30:12.156]   Company name (value is required): myorg3
[2019-09-25 17:30:30.113]  Global
[2019-09-25 17:30:30.113]   Cloud providers credentials file [~/.bwctl/credentials.yml]:
[2019-09-25 17:30:34.004]   DNS hosted zone (value is required): poc.bayware.io
[2019-09-25 17:30:37.325]   Debug enabled [true]:
[2019-09-25 17:30:42.062]   Production mode enabled [true]:
[2019-09-25 17:30:44.548]   Marketplace images to be used [false]:
[2019-09-25 17:30:48.624]  Components
[2019-09-25 17:30:48.624]   Family version [1.2]:
[2019-09-25 17:30:51.959]  Cloud storage
[2019-09-25 17:30:51.959]   Store bwctl state on AWS S3 [false]:
[2019-09-25 17:30:58.786]   Store terraform state on AWS S3 [true]:
[2019-09-25 17:31:05.633]    AWS S3 bucket name [terraform-states-sandboxes]:
[2019-09-25 17:31:12.933]    AWS region [us-west-1]:
[2019-09-25 17:31:15.876]  SSH keys
[2019-09-25 17:31:15.876]   SSH Private key file []:
[2019-09-25 17:31:21.268]  Configuration is done

To view the file with your cloud provider credentials, cat to where the cloud credentials.yml file was specified during the initialization by running the command with the path to the file–in this example /home/ubuntu/.bwctl/credentials.yml –as argument:

]$ cd /home/ubuntu/.bwctl/credentials.yml

You should see this output:

---

# 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:
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:
  azr_client_secret:
  azr_resource_group_name:
  azr_subscription_id:
  azr_tennant_id:
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:

Use your editor of choice (ex: vim, nano) to add your public cloud credentials to credentials.yml.

Changing BWCTL configuration

If you need to change BWCTL configuration, run bwctl init again or update its configuration file stored locally at /home/ubuntu/.bwctl/config.

To check your current configuration, run this command:

$ cat .bwctl/config
cloud_storage:
  state:
    bucket: terraform-states-sandboxes
    enabled: false
    region: us-west-1
  terraform:
    bucket: terraform-states-sandboxes
    enabled: true
    region: us-west-1
components:
  branch: release
  family: '1.2'
credentials_file: ~/.bwctl/credentials.yml
current_fabric: myfab6
debug: true
fabric_manager:
  company_name: myorg4
  id: bangkok-c0_54.200.219.211_ubuntu
  ip: 54.200.219.211
  production: bangkokinc
hosted_zone: poc.bayware.io
marketplace: false
production: true
ssh_keys:
  private_key: ''

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. 126 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:
--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.
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 REGION [OPTIONS]

The command creates a VPC in the current fabric. The VPC is created in the specified region 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 regions by running the command bwctl show vpc --regions.

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:
    region: '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:

--all
configures all orchestrator nodes.
--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:

--all
updates all orchestrator 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 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:
--all
configures all processor nodes.
--orchestrator <FQDN>
orchestrator FQDN.
--location <name>
location name.
--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:
--all
configures all workload nodes.
--orchestrator <FQDN>
orchestrator FQDN.
--location <name>
location name.
--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. 127 BWCTL-CLI Cheat Sheet