nrekretep / nsxtea Goto Github PK

Nsxtea is a small CLI to interact with the VMware NSX-T Search API. Sip a cup of tea while others search in the GUI!

The CLI will only work with NSX-T versions 3.0 and above. Unfortunately, the API endpoints nsxtea relies on are not available in previous versions.

The CLI can be installed via two methods.

Binaries for Linux, macOS and Windows are available on the repos's release page.
To the install nsxtea this way, follow these steps:

# Set a variable to the release version you want to download
export NSXTEA_VERSION=0.2.0
# Download the release for your platform (macOS in this example)
curl -L https://github.com/uempfel/nsxtea/releases/download/v${NSXTEA_VERSION}/nsxtea_${NSXTEA_VERSION}_Darwin_x86_64.tar.gz -o nsxtea.tar.gz

# Unpack the compressed folder 
tar -xvzf nsxtea.tar.gz
x LICENSE
x README.md
x nsxtea
# Move the binary to your PATH
mv nsxtea /usr/local/bin

Assuming you have already installed go:

export GO111MODULE=on
go get github.com/uempfel/nsxtea

If you're getting a command not found error, you might have to add your "go binary" directory to your PATH. To do so, run:

export PATH=$PATH:$(go env GOPATH)/bin

The CLI is configured via environment variables. Just replace the following sample values with your own, and you're good to go:

export NSXTEA_URL='nsxteamgr.mydomain.com'
export NSXTEA_USERNAME='admin'
export NSXTEA_PASSWORD='VMware1!VMware1!'
export NSXTEA_INSECURE='true'

Currently, nsxtea supports two commands, which are documented below:

• search
• apply

Simply type nsxtea --help to get help about nsxtea's usage

To configure the CLI, set the following environment variables:

NSXTEA_URL (required)
NSXTEA_USERNAME (required)
NSXTEA_PASSWORD (required)
NSXTEA_INSECURE (optional, default false)

Usage:
  nsxtea [command]

Available Commands:
  apply       Interact with the Hierarchical Policy API
  help        Help about any command
  search      Interact with the Policy or Manager Search API

Flags:
  -h, --help   help for nsxtea

Use "nsxtea [command] --help" for more information about a command.

This command lets you interact with the Policy or Manager search API. It's a powerful tool to find all kinds of objects and filter results. The command returns a JSON string, which can be used for further processing.
By default, the command searches for Policy objects. If you would like to search for Manager objects instead, simply use the --manager flag.

Usage:
  nsxtea search <query> [flags]

Flags:
  -c, --cursor string            Opaque cursor to be used for getting next page of records (supplied by current result page)
  -h, --help                     help for search
  -f, --included_fields string   Comma separated list of fields that should be included in query result
  -m, --manager                  Use the Manager API for the search request
  -p, --page_size string         Maximum number of results to return in this page 
                                 Min: 0, Max: 1000 (default "1000")
  -a, --sort_ascending           Sorting order of the query results (default true)
  -s, --sort_by string           Field by which records are sorted

The Query Syntax is exactly the same as described in the offical VMware NSX-T API docs and is copied below for reference. For convenience, the Query Syntax is also returned by calling

nsxtea search --help

A query is broken up into terms and operators. A term is case insensitive and can be a single word such as "Hello" or " World " or a phrase surrounded by double quotes such as "Hello World", which would search for the exact phrase.

By default, all the fields will be searched for the search term specified. Specific fields to be searched on can be provided via the field name followed by a colon ":" and then the search term.

• To search for all the entities where display_name field is "App-VM-1", use display_name:App-VM-1
• Use the dot notation to search on nested fields tags.scope:prod

Wildcard searches can be run using ? to substitute a single character or * to substitute zero or more characters

• *vm* will match all the entities that contains the term "vm" in any of its fields
• display_name:App-VM-? will match App-VM-1, App-VM-2, App-VM-A etc..
• display_name:App* will match everything where display_name begins with App

Warning: Be aware that using wildcards especially at the beginning of a word i.e. *vm can use a large amount of memory and may perform badly.

Search terms can be combined using boolean operators AND, OR and NOT. (Note: Boolean operators must be ALL CAPS).

The AND ( && ) operator matches entities where both terms exist in any of the fields of an entity. To search for Firewall rule with display_name containing block, use display_name:*block* AND resource_type:FirewallRule

The OR ( || ) operator links two terms and finds matching entities if either of the terms exists in an entity. To search for Firewall rule with display_name containing either block or allow, use

• display_name:*block* OR display_name:*allow* AND resource_type:FirewallRule
• display_name:(*block* OR *allow*) AND resource_type:FirewallRule

The NOT ( ! ) operator excludes entities that contain the term after NOT. To search for Firewall rule with display_name does not contain the term block

• NOT display_name:*block* AND resource_type:FirewallRule
• !display_name:*block* AND resource_type:FirewallRule

Ranges can be specified for numeric or string fields and use the following syntax

• vni:>50001
• vni:>=50001
• vni:<90000
• vni:<=90000

To combine an upper and lower bound, you would need to join two clauses with AND operator:

• vni:(>=50001 AND <90000)

If characters which function as operators are to be used in the query (not as operators), then they should be escaped with a leading backslash. To search for (a+b)=c

• \(a\+b\)\=c.

The reserved characters are: + - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /

Failing to escape these reserved characters correctly would lead to syntax errors and prevent the query from running.

This command lets you interact with Hierarchical Policy API. It's enables declarative creation, updates and deletion of Policy Objects. To get an overview on how to create objects with the Hierarchical API, this VMware Blog by Madhukar Krishnarao is highly recommended.
Please refer to the official API docs for all objects that can be created.

Decalaratively apply configurations via yaml or json
files.

Examples:
nsxtea apply -f infra.yaml
nsxtea apply -f infra.json

Usage:
  nsxtea apply [flags]

Flags:
  -f, --filepath string   Path to the file that contains the configuration to apply
  -h, --help              help for apply

The following example is taken from the Blog referenced above. It creates a Tier0 and a connected Tier1 Router in one call.

1. Create a file containing the Objects you want to create. The apply command accepts json and yaml input.

• Example as yaml: infra.yaml

resource_type: Infra
display_name: infra
children:
  - resource_type: ChildTier1
    marked_for_delete: "false"
    Tier1:
      resource_type: Tier1
      display_name: my-Tier-1-GW-Prod
      id: my-Tier-1-GW-Prod
      tier0_path: /infra/tier-0s/Tier-0-GW-West-01
  - resource_type: ChildTier0
    marked_for_delete: "false"
    Tier0:
      resource_type: Tier0
      display_name: Tier-0-GW-West-01-Disconnected
      id: Tier-0-GW-West-01

• The same objects as json (taken from Madhukar Krishnarao's Blog): infra.json

{
  "resource_type": "Infra",
  "display_name": "infra",
  "children": [
    {
      "resource_type": "ChildTier1",
      "marked_for_delete": "false",
      "Tier1": {
        "resource_type": "Tier1",
        "display_name": "my-Tier-1-GW-Prod",
        "id": "my-Tier-1-GW-Prod",
        "tier0_path": "/infra/tier-0s/Tier-0-GW-West-01"
      }
    },
    {
      "resource_type": "ChildTier0",
      "marked_for_delete": "false",
      "Tier0": {
        "resource_type": "Tier0",
        "display_name": "Tier-0-GW-West-01-Disconnected",
        "id": "Tier-0-GW-West-01"
      }
    }
  ]
}

2. Run the apply command providing the path to the file you created

# Apply as yaml
nsxtea apply -f path/to/infra.yaml
# Apply as json
nsxtea apply -f path/to/infra.json

That's it! The objects should be created and be available after a short time.

To update objects, simply adapt the file with the necessary configuration and re-run nsxtea apply.

Deleting the objects created in the example above is as simple as changing the marked_for_delete properties from false to true. Once you've done that, simply re-run nsxtea apply and the objects should be deleted after a short time.

• Gopher: Maria Letta - Free Gophers Pack
• Teacup: RROOK, NL