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.

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.

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