Python Client for VMC on AWS

VMware Cloud on AWS version 1.9 and later:

Getting Started

Install Python

This tool is dependent on Python3, you can find installation instructions for your operating system in the Python documentation (https://wiki.python.org/moin/BeginnersGuide/Download).

Download code

Download the pyVMC.zip from the Flings site

If you know git, clone the repo with

git clone https://github.com/vmware/python-client-for-vmware-cloud-on-aws.git

Install Python modules and packages

When you navigate to the python-client-for-vmware-cloud-on-aws folder, you will find a requirements.txt file that lists all your Python packages. They can all be installed by running the following command on Linux/Mac:

pip3 install -r requirements.txt

On Windows, use

python -m pip install -r requirements.txt

Update config.ini

Obtain a refresh token from the VMware Cloud Service Portal, as well as the ORG ID and SDDC ID of the environment you wish to interact with . Copy config.ini.example to config.ini and edit the config.ini with your own SDDC ID, Organization (Org) ID and your access token.

Note: The token must be scoped as either Org Member or Org Owner. It must be given the VMware Cloud on AWS roles of NSX Cloud Admin and Administrator. API calls with a role of Administrator (Delete Restricted) do not work. If you are using the VCDR components of PyVMC, the token must also have a role with full administrative rights to VCDR.

Do I need to know Python?

No! You can simply use it to consume and manage your VMware Cloud on AWS SDDC (Software-Defined Data Center).

Running the Script

This is super easy… - run ./pyVMC.py to see the current list of supported commands. - use ‘-h’ with any super-command or with any subcommand to see the supported arguments / parameters.

For example, to see the supported sub-commands for the ‘system’ super-command: ./pyVMC.py system -h

To see the arguments for the show-routes command: ./pyVMC.py system show-routes -h

Try to view the route table for your SDDC: ./pyVMC.py system show-routes -rt t0

Authentication

pyVMC supports both refresh_token and OAuth AppId/Secret way to authenticate. Values for it needs to be specified in config.ini file. Default auth method is to use refresh_token.

If one wants to use OAuth, then –oauth switch needs to be provided when running the command.

Examples:

Using default ‘refresh_token’

./pyVMC.py sddc show-sddcs

Using OAuth

./pyVMC.py sddc show-sddcs --oauth

Support

Is it officially supported by VMware?

Sorry but no, this is a community-based effort. Use it at your own risk. It has extensively been tested though and we’ll endeavour to fix any bugs.

Which version of VMware Cloud on AWS has it been tested against?

Versions 1.9, 1.10, 1.11, 1.12, 1.14… all the way up through 1.20. We don’t guarantee support with previous versions. We will, however, endeavour to verify compatibility as we release new versions.

What if I find a bug or need a new feature?

Please raise it on GitHub and we will look into it.

Documentation

Where can I find documentation about VMware Cloud on AWS:

Please check the online documentation: https://docs.vmware.com/en/VMware-Cloud-on-AWS/index.html

Where can I find documentation about each pyVMC commands?

Current Supported Commands

Here are the currently supported ‘super’ commands:

    csp                                 Commands related to the Cloud Service Portal itself.
    sddc                                Commands related to the Software Defined Datacenter (SDDC) itself.
    tkg                                 Commands related to the Tanzu Kubernetes Service (TKG).
    segment                             Create, delete, update, and show Virtual Machine network segments.
    vpn                                 Create, delete, update, and show virtual private network (VPN) settings.
    nat                                 Show and update Network Address Translation (NAT) rules.
    t1                                  Create, delete, update, and show secondary T1 gateways.
    vtc                                 Commands related to VMware Transit Connect (VTC).
    gwfw                                Show and update policies and rules associated with NSX Gateway Firewall (mgw, cgw, etc.).
    dfw                                 Show and update policies and rules associated with NSX Distributed Firewall.
    nsxaf                               Commands related to the NSX Advanced Firewall - e.g. IDS.
    inventory                           Show and update objects in the NSX Inventory (groups, services, etc).
    system                              Show and update configuration data associated with the NSX-T System (DNS, public IP, etc).
    search-nsx                          Search the NSX Manager inventory.
    vcdr                                Create, delete, update, and show information about VMware Cloud Disaster Recovery.
    flexcomp                            Commands related to the Cloud Flex Compute itself.

Getting Help

To see the supported commands for any given category / super-command, simply use ‘-h’… for example:

./pyVMC.py vcdr -h
usage:  vcdr [-h] {scfs,pg,snaps,rsddc,psite,vms} ...

positional arguments:
  {scfs,pg,snaps,rsddc,psite,vms}
                        vcdr sub-command help
    scfs                VCDR cloud file system - use '-h' for help.
    pg                  VCDR Protection Groups - use '-h' for help.
    snaps               VCDR Snapshots - use '-h' for help.
    rsddc               VCDR Recovery SDDC - use '-h' for help.
    psite               VCDR Protected Site - use '-h' for help.
    vms                 VCDR cloud file system - use '-h' for help.

optional arguments:
  -h, --help            show this help message and exit

Similarly, to see the options for any given command, run the individual command with the -h option:

./pyVMC.py vcdr scfs -h               
usage: vcdr scfs [-h] {show} ...

positional arguments:
  {show}      vcdr scfs sub-command help
    show      Show information about the VCDR Scale-out file System(s).

optional arguments:
  --oauth [OAUTH]       Used to specify use of OAuth app ID and secret in config.ini instead of 'refresh_token' (default)
  -h, --help  show this help message and exit

Check comprehensive listing of all currently supported commands.

Release Notes:

Please see the release notes found here.

Known Issues:

Please see the release notes found here.

Contributing

For a quick overview of how the project is structured as well as how the files relate to each other, how the argparse module is being used, etc, please refer to the pyvmc-structure.md.

The python-client-for-vmware-cloud-on-aws project team welcomes contributions from the community. Before you start working with python-client-for-vmware-cloud-on-aws, please read our Developer Certificate of Origin. All contributions to this repository must be signed as described on that page. Your signature certifies that you wrote the patch or have the right to pass it on as an open-source patch. For more detailed information, refer to CONTRIBUTING.md.

License

SPDX-License-Identifier: BSD-2-Clause

Version 2.1

• Bugfix: Amended "create-sddc" function

Version 2.0

Highlights of this release include:

• Brand new project architecture - makes it easier to locate, update, and troubleshoot functions
• Over 200 new commits
• Over 5500 new lines of code
• Significantly improved error handling
• More intuitive command structure and argument framework with 100% coverage of all commands using python argparse - enables complete scriptability
• Over 30 new commands, including support for:
  • Creating a SDDC!
  • Secondary T1 gateways!
  • T1 VPN!
  • Fixed and Flexible network segments!
  • NSX Advanced Firewall IDS and IPS!
  • VMware Transit Connect attachments to DXGW and VPC!
  • FlexCompute (experimental)!
• Many more!

Version 1.8.0

New Features:

• Support for the long-awaited initial release of the VCDR API
• Significant function refactoring. The team has spent a lot of time splitting API calls into separate libraries. This makes re-use of the API calls much easier for anybody wanting to use the code in this project

Bug Fixes:

• Fixed an issue where using any group name with lowercase characters caused errors when creating firewall rules

Documentation:

• Clarify args for new-network function
• Add clarifying documentation for new-group function

Version 1.7.0

• New commands - create-sddc-group, delete-sddc-group, get-group-info, get-sddc-info, get-nsx-info, attach-sddc, detach-sddc, connect-aws, disconnect-aws, attach-vpc, detach-vpc, vpc-prefixes, attach-dxgw, detach-dxgw, show-tgw-routes, show-t0-bgp-routes
• Bugfixes - Better error handling when config.ini is missing sections or values inside config.ini are missing
• Improvements - show-t0-routes displays in table format, sorted, with a legend

Version 1.6.5

• Bugfixes - Fixed handling of blank and invalid values values for prefix scope and length
• Feature - Update prefix attachment to allow both inbound and outbound prefix lists
• Feature - Update show function to show BGP neighbors with multiple lists

Version 1.6.0

• bug: Fixed display of route filters in show-t0-bgp-neighbors
• feature: added attach-t0-prefix list, detach-t0-prefix-list

Version 1.5.2

• New, clearer help section makes it easier to find commands
• Improved menu for new-t0-prefix-list

Version 1.5

find-csp-user-by-service-role - search for any user with a specific role

get-csp-service-roles - list all roles assigned to the current user

show-t0-prefix-lists - Display any BGP prefix lists attached to the SDDC

show-t0-bgp-neighbors - Show all Tier0 router BGP neighbors

new-t0-prefix-list - Create a new Tier0 BGP prefix list

remove-t0-prefix-list - Delete a Tier0 BGP prefix list

Version 1.4

Added ability to display CSP groups and group members

Added ability to add users to a CSP group

Added ability to display members of a CSP org

Added ability to display a diff of org member permissions in an org vs roles granted to a group

Version 1.3

Added show-csp-groups and show-csp-group members functions

Version 1.2

Added a Dockerfile to build a Docker image to run PyVMC

Added Egress counters visibility

Added routing table visibility

Added L2VPN support

Added Nested Group support

Version 1.1

Added support for Distributed Firewall.