BWCTL-API CLI User Guide

About BWCTL-API

BWCTL-API is a command line interface (CLI) tool that enables you to interact with the SIF Orchestrator using commands in your command-line shell. The tool offers all the functionality provided by the Orchestrator Graphical User Interface (GUI) as they both utilize the same Orchestrator’s RESTful Northbound Interface (NBI).

BWCTL-API CLI for SIF policy management

Fig. 99 Fig. BWCTL-API CLI for SIF policy management

In general, you can manage all policy entities in your service interconnection fabric using interchangeably one of the three tools:

  • Browser-based GUI
  • BWCTL-API CLI
  • RESTful NBI

To use BWCTL-API tool, you can install it on your local Linux machine or access remotely the tool already installed on your fabric manager node from any Linux, macOS, or Windows machine.

When the tool installed locally, use a common shell program, e.g. bash, to run BWCTL-API commands. To run the commands remotely, 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.

BWCTL-API enables you to monitor policy entities and configure them. You can show, create, update, enable, disable, and delete policy entities of the service interconnection fabric: domains, administrators, contracts, templates, services, service tokens, resources, zones, locations. Also, the tool allows you to perform the same operation on a batch of different policy entities.

Installing BWCTL-API

Ways to install

BWCTL-API tool comes already preinstalled on the fabric manager image available in AWS, Azure and GCP clouds.

To install BWCTL-API on your own Linux machine, you have first to install the Bayware repository on the machine and after that you can deploy the most recent version of the tool from the repository.

To add the repo, run the command (the command shown assumes you install the repo on a Debian machine):

]$ add-apt-repository 'deb https://s3-us-west-1.amazonaws.com/bayware-repo-devel/public/<specify_family_here>/ubuntu bionic main'

Note: BWCTL-API version must be from the same family as the other Bayware components in your service interconnection fabric, so use the right family version when installing repo. If BWCTL-API version is incompatible with the orchestrator, the tool will fail to establish a connection to orchestrator with an error message specifying the required family. The family is specified in the form of platform version and might look like 1.2 or 2.x.

Installing BWCTL-API with apt on Debian/Ubuntu

Installing BWCTL-API on Debian/Ubuntu with apt provides isolation for the tool and its dependencies. Also, it’s easy to upgrade when a new version of BWCTL-API tool is released.

To install BWCTL-API on the machine with the Bayware repository already installed, run the command:

]$ apt-get install bwctl-api

Verify that BWCTL-API installed correctly by running the command:

]$ bwctl-api --version
]$ bwctl-api/1.2.0

Upgrading BWCTL-API to the latest version

You can upgrade BWCTL-API tool already installed on your machine to the latest version in the family by running the command:

]$ apt-get update
]$ apt-get --only-upgrade install bwctl-api

Uninstalling BWCTL-API

If you need to uninstall BWCTL-API tool, run the command:
]$ apt-get --purge remove bwctl-api

Configuring BWCTL-API

Configuring BWCTL-API after installation

Before you can run BWCTL-API, you must configure the tool with your orchestrator credentials. You store configuration locally in the file called config.yaml located at:

/home/ubuntu/.bwctl-api/config.yml

The file contains BWCTL-API credential details. To verify information in the configuration file, run the command:

]$ cat /home/ubuntu/.bwctl-api/config.yml
---
hostname: orchestrator-fab1.example.com
Domain: EXAMPLEDOMAIN
login: EXAMPLELOGIN
password: EXAMPLEPASSWORD

The hostname is an FQDN of the fabric orchestrator which you access with BWCTL-API tool. The domain, login, and password are your credentials at the orchestrator that determine what permissions you have for managing the service interconnection fabric.

To run BWCTL-API commands you must have an account on the orchestrator with one of the two administrative roles: systemAdmin or domainAdmin. See how to create an administrator account in the documentation on orchestrator GUI.

Note: If you are configuring BWCTL-API on the fabric manager node, the credentials can be automatically retrieved when the orchestrator’s controller node created. For more information, see BWCTL CLI documentation.

Changing BWCTL-API configuration

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

Getting started with BWCTL-API

Typing the first command

To give a command in BWCTL-API, you will type bwctl-api along with the required input and press the <return> key.

To start using BWCTL-API tool, run the command:

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

Bayware CLI (Policy management)

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

Commands:
  create   Create policy entity
  delete   Delete policy entity
  disable  Disable policy entity
  enable   Enable policy entity
  show     Show policy entity
  update   Update policy entity

The output above is the same as from running the command:

]$ bwctl-api --help

Command structure

The command line is comprised of several components:
  • bwctl-api,
  • any options required by bwctl-api to execute the command,
  • the command and, in most cases, subcommand,
  • any arguments required by the command.
]$ bwctl-api --help
Usage: bwctl-api [OPTIONS] COMMAND [ARGS]...

Command line options

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

--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-api show --help
Usage: bwctl-api show COMMAND [ARGS] [OPTIONS]

To show policy entity, enter <command>.

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

Commands:
  administrator  Show administrator
  contract       Show contract
  domain         Show domain
  link           Show links
  location       Show location
  resource       Show resource
  service        Show service
  service_token  Show service_token
  template       Show template
  zone           Show zone

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

]$ bwctl-api show contract --help

Usage: bwctl-api show contract [OPTIONS] [CONTRACT@DOMAIN]

  To show contract, enter <contract>@<domain>. To show all contracts within
  a domain, use --domain <domain>.

Options:
  -d, --domain TEXT         Domain name.
  -c, --config_file TEXT    Path to config file.
  -o, --output_format TEXT  Output format: json or yaml.
  -h, --help                Show this message and exit.

Different commands support different options. Detail information on options find in the documentation section Using commands.

Commands

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

BWCTL-API supports the following commands:

create KIND NAME [OPTIONS]
The command creates one or multiple entities. The specification file is mandatory for this command.
delete KIND NAME [OPTIONS]
The command deletes one or multiple entities. The specification file is mandatory for the batch kind.
disable KIND NAME
The command disables a single entity.
enable KIND NAME
The command enables a single entity.
show KIND NAME [OPTIONS]
The command shows one or multiple entities. For some entity types, the entity name is optional in this command.
update KIND NAME [OPTIONS]
The command updates one or multiple entities. The specification file is mandatory for this command.

Kinds

The diagram below depicts the policy entities and relationships between them.

Policy entity

Fig. 100 Fig. Policy entity

To see the entity types you can run any command without subcommand:

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

  Show policy entity commands

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

Commands:
  administrator  Show administrator
  contract       Show contract
  domain         Show domain
  link           Show link
  location       Show location
  resource       Show resource
  service        Show service
  service_token  Show service token
  template       Show template
  zone           Show zone

BWCTL-API manages the following entity types:

administrator NAME@DOMAIN
The administrator entity is an account of the service interconnection fabric administrator.
contract NAME@DOMAIN
The contract entity represents a communication microsegment for application services.
domain NAME
The domain entity serves as an administrative boundary between different portions of the service interconnection fabric.
link NAME
The link entity represents a connection between the service interconnection fabric resources: workload node and processor node or between two processor nodes.
location NAME
The location entity is an abstraction of the site where the workload nodes are deployed, e.g. cloud VPC or private datacenter.
resource NAME
The resource entity represents compute and network resources in the service interconnection fabric: a workload node with policy agent or a processor node with policy engine.
service NAME@DOMAIN
A set of applications, an individual application or an application microservice is represented in the policy model as the service entity.
service_token NAME@DOMAIN
The service_token entity is a service credential that defines the service access permissions to the communication microsegments.
template NAME
The template entity represents a predefined set of communication rules that can be used in contracts.
zone NAME
The zone entity is a service zone for processors, which bounds the processors to the workload nodes in one or multiple locations.

Batch

With BWCTL-API 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-api create batch getaway-app.yml

Using commands

Supported commands for each entity type

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

show, create, update, delete, enable, disable

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

- ADMINISTRATOR

- CONTRACT

- LINK

- SERVICE

- TEMPLATE

show, create, update, delete

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

- DOMAIN

- LOCATION

- RESOURCE

- ZONE

show, create, delete

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

- SERVICE_TOKEN

create, update, delete

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

- BATCH

Managing administrators

You can manage administrators using the following commands:

show administrator [OPTIONS]

The command shows all administrators. You can use the options in this command as follows: -d, --domain – domain name to show administrators within a domain only.

-o, --output_format – output format, either json or yaml.

show administrator NAME@DOMAIN [OPTIONS]
The command shows the administrator. You can use the options in this command as follows: -o, --output_format – output format for this command, either json or yaml.
create administrator NAME@DOMAIN [OPTIONS]
The command creates the administrator. The specification file is mandatory for this command. -f, --file – path to the specification file.
update administrator NAME@DOMAIN [OPTIONS]

The command updates the administrator. You can use the specification file or the options in this command as follows:

-f, --file – path to the specification file.

-desc, --description – description.

-auth, --auth_method – administrator authentication method, either LocalAuth or LDAP (if both are allowed in the domain).

-pass, --password – administrator password.

-role, --admin_role – administrator role.

delete administrator NAME@DOMAIN
The command deletes the administrator.
enable administrator NAME@DOMAIN
The command enables the administrator.
disable administrator NAME@DOMAIN
The command disables the administrator.

An example of the administrator specification file is shown below.

]$ cat administrator-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Administrator
metadata:
  username: admin
  user_domain: default
spec:
  is_active: true
  roles:
  - systemAdmin
  user_auth_method: LDAP

Managing contracts

You can manage contracts using the following commands:

show contract [OPTIONS]

The command shows all contracts. You can use the options in this command as follows:

-d, --domain – domain name to show contracts within a domain only.

-o, --output_format – output format, either json or yaml.

show contract NAME@DOMAIN [OPTIONS]

The command shows the contract. You can use the options in this command as follows:

-o, --output_format – output format for this command, either json or yaml.

create contract NAME@DOMAIN [OPTIONS]

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

-f, --file – path to the specification file.

update contract NAME@DOMAIN [OPTIONS]

The command updates the contract. You can use the specification file or the options in this command as follows:

-f, --file – path to the specification file.

-desc, --description – description.

delete contract NAME@DOMAIN
The command deletes the contract.
enable contract NAME@DOMAIN
The command enables the contract.
disable contract NAME@DOMAIN
The command disables the contract.

An example of the contract specification file is shown below.

]$ cat contract-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Contract
metadata:
  name: frontend
  domain: getaway-app
spec:
  template: anycast-cross-all-vpcs
  contract_roles:
  - template_role: Originator
  - template_role: Responder
    ingress_rules:
    - protocol: icmp
    - protocol: tcp
      ports:
      - 8080
      - 5201

Managing domains

You can manage domains using the following commands:

show domain [OPTIONS]

The command shows all domains. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

show domain NAME [OPTIONS]

The command shows the domain. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

create domain NAME [OPTIONS]

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

-f, --file – path to the specification file.

update domain NAME [OPTIONS]

The command updates the domain. You can use the specification file or the options in this command as follows:

-f, --file – path to the specification file.

-desc, --description – description.

-auth, --auth_method – domain authentication method, LocalAuth or LDAP (both can be allowed in the domain).

delete domain NAME
The command deletes the domain.

An example of the domain specification file is shown below.

]$ cat domain-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Domain
metadata:
  domain: getaway-app
spec:
  auth_method:
  - LocalAuth
  domain_type: Application

Managing locations

You can manage locations using the following commands:

show location [OPTIONS]

The command shows all locations. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

show location NAME [OPTIONS]

The command shows the location. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

create location NAME [OPTIONS]

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

-f, --file – path to the specification file.

update location NAME [OPTIONS]

The command updates the location. You can use the specification file or the options in this command as follows:

-f, --file – path to the specification file.

-desc, --description – description.

delete location NAME
The command deletes the location.

An example of the location specification file is shown below.

]$ cat location-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Location
metadata:
  name: aws2
spec:

Managing resources

You can manage resources using the following commands:

show resource [OPTIONS]

The command shows all resources. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

show resource NAME [OPTIONS]

The command shows the resource. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

create resource NAME [OPTIONS]

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

-f, --file - path to the specification file.

update resource NAME [OPTIONS]

The command updates the resource. You can use the specification file or the options in this command as follows:

-f, --file – path to the specification file.

-desc, --description – description.

delete resource NAME
The command deletes the resource.

An example of the resource specification file is shown below.

]$ cat resource-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Resource
metadata:
  name: aws2-p01-fab1
  domain: cloud-net
spec:
  location: aws2
  node_type: processor

Managing services

You can manage services using the following commands:

show service [OPTIONS]

The command shows all services. You can use the options in this command as follows:

-d, --domain – domain name to show services within a domain only.

-o, --output_format – output format, either json or yaml.

show service NAME@DOMAIN [OPTIONS]

The command shows the service. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

create service NAME@DOMAIN [OPTIONS]

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

-f, --file – path to the specification file.

update service NAME@DOMAIN [OPTIONS]

The command updates the service. You can use the specification file or the options in this command as follows:

-f, --file – path to the specification file.

-desc, --description – description.

delete service NAME@DOMAIN
The command deletes the service.
enable service NAME@DOMAIN
The command enables the service.
disable service NAME@DOMAIN
The command disables the service.

An example of the service specification file is shown below.

]$ cat service-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Service
metadata:
  name: http-proxy
  domain: getaway-app
spec:
  contract_roles:
  - contract: frontend
    contract_role: Originator

Managing service tokens

You can manage services using the following commands:

show service_token SERVICE@DOMAIN [OPTIONS]

The command shows the service token. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

create service_token SERVICE@DOMAIN [OPTIONS]

The command creates the service token. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

delete service_token SERVICE@DOMAIN OPTIONS

The command deletes the service token. The following option is mandatory for this command:

-iden, --token_iden – token identifier.

An example of the service token specification file is shown below.

]$ cat serviceToken-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Token
metadata:
  name: aws-proxy
spec:
  service: http-proxy
  domain: getaway-app

Managing templates

You can manage templates using the following commands:

show template [OPTIONS]

The command shows all templates. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

show template NAME [OPTIONS]

The command shows the template. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

create template NAME [OPTIONS]

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

-f, --file – path to the specification file.

update template NAME [OPTIONS]

The command updates the template. You can use the specification file or the options in this command as follows:

-f, --file – path to the specification file.

-desc, --description – description.

delete template NAME
The command deletes the template.
enable template NAME
The command enables the template.
disable template NAME
The command disables the template.

An example of the template specification file is shown below.

]$ cat template-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Template
metadata:
  name: multicast-cross-all-vpcs
spec:
  is_multicast: true
  orientation: directed
  roles:
  - name: Publisher
    code_binary: "409C470100E7846300E000EF0A500793C11C004000EF409C470500E7846300C000EF5795C11C004000EF409C00178713C0989002"
    propagation_interval_default: 5
    program_data_default:
      ppl: 0
      params:
      - name: hopCount
        value: 0
    code_map:
      Publisher: 0
    path_binary: "000000000001"
  - name: Subscriber
  code_binary: "409C470100E7846300C000EF5791C11C004000EF409C470500E7846300C000EF5791C11C004000EF409C00178713C0989002"
    propagation_interval_default: 5
    program_data_default:
      ppl: 0
      params:
      - name: hopCount
        value: 0
    code_map:
      Subscriber: 0
    path_binary: "000000000001"

Managing zones

You can manage zones using the following commands:

show zone [OPTIONS]

The command shows all zones in the fabric. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

show zone NAME [OPTIONS]

The command shows the zone. You can use the options in this command as follows:

-o, --output_format – output format, either json or yaml.

create zone NAME [OPTIONS]

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

-f, --file – path to the specification file.

update zone NAME [OPTIONS]

The command updates the zone. You can use the specification file or the options in this command as follows:

-f, --file – path to the specification file.

-desc, --description – description.

delete zone NAME
The command deletes the zone.

An example of the zone specification file is shown below.

]$ cat zone-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Zone
metadata:
  name: AWS Zone
spec:
  locations:
  - name: aws2
  processors:
  - name: aws2-p01-fab1
    domain: cloud-net
    tunnel_ip_type: private
    ipsec_enable: true

Working with batches

You can manage batches using the following commands:

create batch [OPTIONS]

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

-f, --file – path to the specification file.

update batch [OPTIONS]

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

-f, --file – path to the specification file.

delete batch [OPTIONS]

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

-f, --file – path to the specification file.

An example of the batch specification file is shown below.

]$ cat batch-spec.yml
---
apiVersion: policy.bayware.io/v2
kind: Batch
metadata:
  name: getaway-app
spec:
- kind: Domain
  metadata:
  domain: getaway-app
spec:
  auth_method:
    - LocalAuth
  domain_type: Application
- kind: Contract
  metadata:
    name: frontend
    domain: getaway-app
spec:
    template: anycast-cross-all-vpcs
    contract_roles:
    - template_role: Originator
      endpoint_rules:
        ingress:
          - protocol: icmp
    - template_role: Responder
      endpoint_rules:
        ingress:
          - protocol: icmp
          - protocol: tcp
            ports:
              - 8080
              - 5201
- kind: Service
  metadata:
    name: http-proxy
    domain: getaway-app
spec:
    contract_roles:
    - contract: frontend
      contract_role: Originator
- kind: Service
  metadata:
    name: getaway-svc
    domain: getaway-app
spec:
    contract_roles:
    - contract: frontend
      contract_role: Responder

BWCTL-API cheat sheet

BWCTL-API CLI cheat sheet

Fig. 101 Fig. BWCTL-API CLI cheat sheet