cisco_node_utils 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5972809d82dc9ad3991f11217e174556220418c6
-  data.tar.gz: abec7a2fbd8757cdf73bb5eb84c7e154e777ffbc
+  metadata.gz: 04e705a28917168a277c351451f63491ff3c1177
+  data.tar.gz: 4e2be35191668158a0b757b831cd1ee135ae7525
 SHA512:
-  metadata.gz: f8d80e3c768ebbd436ce9d2d0f6e795941932c517834e5c644aa12bce22fddee6ee82efb545857900de5a0127bdfa58911d4e411bbf6dfc5dd887fbb52a1567c
-  data.tar.gz: 9a0ac0b2beb5cad046e28ba570f5afdf3c98543b1d11e76dadd1ca33fa3c57757d6e136e2fe55f984d3c6ed6e448f0f2e0cd07ba72088f024ab90a5ecd7033c3
+  metadata.gz: 734d65543eeedb4f766a74c8d56f397e638f5fe446846bc4196ec3facfd1f5378f1eefe11364a67089f67a6851f2101438b87526536ab44477df6181281fb39b
+  data.tar.gz: a0d7aaebf7dd5d00a432f4a6c4067860750dd61df4e1fa73da11e6c8440f859f32d1155a412a5a00791a15a1ed024d5e3a08129b6ce74abed9a326ef55cdddfc

data/.gitignore

@@ -2,6 +2,8 @@
 pkg/*
 vendor/*
 coverage
+ext/Rakefile
 Gemfile.lock
 *.gem
 *.swp
+TAGS

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -1,4 +1,11 @@
 # Rubocop configuration
+AllCops:
+  Exclude:
+    # Auto-generated files
+    - lib/cisco_node_utils/client/grpc/ems.rb
+    - lib/cisco_node_utils/client/grpc/ems_services.rb
+    # Files we don't own
+    - vendor/**/*
 
 # Code complexity metrics are tracked separately for lib/ vs. tests/
 # See lib/.rubocop.yml and tests/.rubocop.yml
@@ -40,6 +47,9 @@ Style/AlignHash:
   EnforcedHashRocketStyle: table
   EnforcedColonStyle: table
 
+Style/ClassAndModuleChildren:
+  Enabled: false
+
 # Template files have wildcard strings in class names
 Style/ClassAndModuleCamelCase:
   Exclude:
@@ -75,6 +85,9 @@ Style/SpaceAroundEqualsInParameterDefault:
 Style/TrailingComma:
   EnforcedStyleForMultiline: comma
 
+Style/TrivialAccessors:
+  AllowPredicates: true
+
 # Because an SnmpServer cannot be destroyed, we end most of the SnmpServer
 # test cases by explicitly returning the configuration to default.
 # Rubocop thinks this is a no-op but it isn't.

data/.travis.yml

@@ -6,4 +6,7 @@ cache: bundler
 rvm:
   - 2.2.2
   - 2.1.6
-  - 2.0.0
+  - 2.0.0-p648 # specify non-clang version of ruby
+
+script:
+ - bundle exec rake

data/CHANGELOG.md

@@ -1,6 +1,80 @@
 Changelog
 =========
 
+## [v1.3.0]
+
+### New feature support
+
+#### Cisco Resources
+* Itd
+  * itd_device_group (@saichint)
+  * itd_device_group_node (@saichint)
+  * itd_service (@saichint)
+* Spanning Tree
+  * stp_global (@saichint)
+* Bridge Domain
+  * bridge_domain (@rkorlepa)
+  * bridge_domain_vni (@rkorlepa)
+* Encapsulation Profile
+  * vni_encapsulation_profile (@rkorlepa)
+
+#### NetDev Resources
+*
+
+### Added
+
+* Added a new property fabric-control for vlan MT-FULL fabricpath
+* Added support for bdi interfaces to interface provider.
+* Added a new node util to handle bridge domain range cli for member vni
+* Added Bridge Domain, VNI and encapsulation profile node utils for MT-FULL on Nexus 7k.
+* Minitests can declare the YAML feature they are exercising, and if the feature is `_exclude`d on the node under test, the test case will automatically be skipped in full.
+* CliErrors raised by any `NodeUtil` subclass or instance will automatically prepend the `to_s` method output to make troubleshooting easier.
+* `test_feature` minitest
+* Extend interface with attributes:
+  * `ipv4_forwarding`
+  * `stp_bpdufilter`, `stp_bpduguard`, `stp_cost`, `stp_guard`, `stp_link_type`, `stp_mst_cost`
+  * `stp_mst_port_priority`, `stp_port_priority`, `stp_port_type`, `stp_vlan_cost`, `stp_vlan_port_priority`
+  * `switchport_private_vlan_trunk_allowed_vlan`, `switchport_private_vlan_trunk_native_vlan`
+  * `switchport_mode_private_vlan_host`, `switchport_mode_private_vlan_host_association`
+  * `switchport_mode_private_vlan_host_promiscous`, `switchport_mode_private_vlan_trunk_promiscous`, `switchport_mode_private_vlan_trunk_secondary`
+  * `switchport_private_vlan_association_trunk`, `switchport_private_vlan_mapping_trunk`
+  * `private_vlan_mapping`
+* Extend Feature class with a class method to list feature compatible interfaces
+* Extend vdc with interface_membership methods
+* Extend vpc with vpc+ attributes on Nexus 5k/6k/7k:
+  * `fabricpath_emulated_switch_id`
+  * `fabricpath_multicast_load_balance` (only on Nexus 7k)
+  * `port_channel_limit` (only on Nexus 7k)
+* Extend vlan with attributes:
+  * `private_vlan_association`, `private_vlan_type`
+* Added N3k native support for portchannel_global
+
+### Changed
+
+* Major refactor and enhancement of `CommandReference` YAML files:
+  - Filtering by platform is now by platform name only.
+  - Replaced `config_get(_token)?(_append)?` with `get_command`, `get_context`, and `get_value`
+  - Replaced `config_set(_append)?` with `set_context`, and `set_value`
+  - Individual token values can be explicitly marked as optional (e.g., VRF context); tokens not marked as optional are mandatory.
+  - Data format (CLI, NXAPI structured) is now assumed to be CLI unless explicitly specified otherwise using the new `(get_|set_)?data_format` YAML key. No more guessing based on whether a key looks like a hash key or a Regexp.
+* `cisco_nxapi` Gem is no longer a dependency as the NXAPI client code has been merged into this Gem under the `Cisco::Client` namespace.
+* Improved minitest logging CLI.
+  - `ruby test_foo.rb -l debug` instead of `ruby test_foo.rb -- <host> <user> <pass> debug`
+  - `rake test TESTOPTS='--log-level=debug'`
+* Client connectivity is now specified in `/etc/cisco_node_utils.yaml` or `~/cisco_node_utils.yaml` instead of environment variables or command-line arguments to minitest.
+  - `ruby test_foo.rb -e <node name defined in YAML>`
+  - `rake test TESTOPTS='--environment=default'`
+
+### Fixed
+
+* Interface:
+  - Correctly restore IP address when changing VRF membership
+  - MTU is not supported on loopback interfaces
+
+### Removed
+* Removed `Node.lazy_connect` internal API.
+* Removed `vni` node util class
+
 ## [v1.2.0]
 
 ### New feature support
@@ -40,7 +114,7 @@ Changelog
   * vxlan_vtep (@dcheriancisco)
   * vxlan_vtep_vni (@mikewiebe)
 
-  
+
 ### Additional platform support added to existing classes
 #### Cisco Nexus 56xx, 60xx and 7xxx
 * AAA
@@ -110,7 +184,11 @@ Changelog
   * `vpc_id`, `vpc_peer_link`
   * switchport mode `fabricpath`
 * Extend vrf with attributes:
+  * `mhost_ipv4`
+  * `mhost_ipv6`
+  * `remote_route_filtering`
   * `vni`
+  * `vpn_id`
 * Extend vlan with attribute:
   * `mode`
 
@@ -119,7 +197,7 @@ Changelog
 * Major refactor and enhancement of `CommandReference` YAML files:
   - Added support for `auto_default`, `default_only`, `kind`, and `multiple`
   - Added filtering by product ID (`/N7K/`) and by client type (`cli_nexus`)
-  - `CommandReference` methods that do key-value style wildcard substitution now raise an `ArgumentError` if the result is empty (because not enough parameters were supplied). 
+  - `CommandReference` methods that do key-value style wildcard substitution now raise an `ArgumentError` if the result is empty (because not enough parameters were supplied).
 
 ## [v1.1.0]
 
@@ -216,6 +294,7 @@ Changelog
 [git-flow]: https://github.com/petervanderdoes/gitflow-avh
 [SimpleCov]: https://github.com/colszowka/simplecov
 
+[v1.3.0]: https://github.com/cisco/cisco-network-node-utils/compare/v1.2.0...v1.3.0
 [v1.2.0]: https://github.com/cisco/cisco-network-node-utils/compare/v1.1.0...v1.2.0
 [v1.1.0]: https://github.com/cisco/cisco-network-node-utils/compare/v1.0.1...v1.1.0
 [v1.0.1]: https://github.com/cisco/cisco-network-node-utils/compare/v1.0.0...v1.0.1

data/CONTRIBUTING.md

@@ -9,28 +9,13 @@ Cisco Network Elements support a rich set of features to make networks robust, e
 ## Making Changes
 
 * Fork and clone the repository
-  * Run the `bin/git/update-hooks` script to install our recommended Git hooks into your local repository.
+  * Run the `bin/git/update-hooks` script to install our recommended Git hooks into your local repository.  (Note: some of the hooks require additional tools, such as the `rubocop` ruby gem, be installed and available in your `$PATH`.  See [Ruby Prerequisites](docs/README-develop-node-utils-APIs.md#prereq_ruby) for a list of recommended ruby gems.)
   * Pull a branch under the "develop" branch for your changes.
   * Follow all guidelines documented in [README-develop-node_utils-APIs](docs/README-develop-node-utils-APIs.md)
   * Make changes in your branch.
 * Testing
   * Create a minitest script for any new APIs or new functionality
-  * Run all the tests to ensure there was no collateral damage to existing code. There are two ways you can specify the Nexus switch (virtual or physical) to test against when running the full test suite:
-    1. Use the NODE environment variable to specify the address, username, and password:
-
-        ```bash
-        export NODE="192.168.100.1 user password"
-        rake test
-        ```
-
-    2. Enter the connection information at runtime:
-
-        ```
-        rake test
-        Enter address or hostname of node under test: 192.168.100.1
-        Enter username for node under test:           user
-        Enter password for node under test:           password
-        ```
+  * Run all the tests to ensure there was no collateral damage to existing code. See [README-test-execution](docs/README-test-execution.md) for details.
 
 * Committing
   * Check for unnecessary whitespace with `git diff --check` before committing.

data/Gemfile

@@ -2,3 +2,8 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in cisco_node_utils.gemspec
 gemspec
+
+# These are optional dependencies in the Gem itself,
+# but we need them for Bundler to use.
+gem 'net_http_unix'
+gem 'grpc'

data/README.md

@@ -23,12 +23,13 @@ Please see [Learning Resources](#resources) for additional references.
 #### Table of Contents
 
 1. [Overview](#overview)
-2. [Installation](#installation)
-3. [Examples](#examples)
-4. [Documentation](#documentation)
-5. [Changelog](#changelog)
-6. [Learning Resources](#resources)
-7. [License Information](#license_info)
+1. [Installation](#installation)
+1. [Configuration](#configuration)
+1. [Documentation](#documentation)
+1. [Examples](#examples)
+1. [Changelog](#changelog)
+1. [Learning Resources](#resources)
+1. [License Information](#license_info)
 
 
 ## <a name="overview">Overview</a>
@@ -39,17 +40,13 @@ open source management tools.
 
 This CiscoNodeUtils gem release supports the following:
 
-Platform         | OS    | OS Version           |
------------------|-------|----------------------|
-Cisco Nexus 30xx | NX-OS | 7.0(3)I2(1) and later
-Cisco Nexus 31xx | NX-OS | 7.0(3)I2(1) and later
-Cisco Nexus 93xx | NX-OS | 7.0(3)I2(1) and later
-Cisco Nexus 95xx | NX-OS | 7.0(3)I2(1) and later
-Cisco N9kv       | NX-OS | 7.0(3)I2(1) and later
-Cisco Nexus 56xx | NX-OS | 7.3(0)N1(1) and later
-Cisco Nexus 60xx | NX-OS | 7.3(0)N1(1) and later
-Cisco Nexus 7xxx | NX-OS | 7.3(0)D1(1) and later
-
+Platform         | OS     | OS Version           |
+-----------------|--------|----------------------|
+Cisco Nexus N9k  | NX-OS  | 7.0(3)I2(1) and later
+Cisco Nexus N3k  | NX-OS  | 7.0(3)I2(1) and later
+Cisco Nexus N5k  | NX-OS  | 7.3(0)N1(1) and later
+Cisco Nexus N6k  | NX-OS  | 7.3(0)N1(1) and later
+Cisco Nexus N7k  | NX-OS  | 7.3(0)D1(1) and later
 
 Please note: For Cisco Nexus 3k and 9k platforms, a virtual Nexus N9000/N3000 may be helpful for development and testing. Users with a valid [cisco.com](http://cisco.com) user ID can obtain a copy of a virtual Nexus N9000/N3000 by sending their [cisco.com](http://cisco.com) user ID in an email to <get-n9kv@cisco.com>. If you do not have a [cisco.com](http://cisco.com) user ID please register for one at [https://tools.cisco.com/IDREG/guestRegistration](https://tools.cisco.com/IDREG/guestRegistration)
 
@@ -64,53 +61,41 @@ To install the CiscoNodeUtils, use the following command:
 Alternatively, if you've checked the source out directly, you can call
 `rake install` from the root project directory.
 
-## <a name="examples">Examples</a>
+## Configuration
 
+This gem may require configuration in order to be used. Two configuration file locations are supported:
 
-These utilities can be used directly on a Cisco device (as used by Puppet
-and Chef) or can run on a workstation and point to a Cisco device (as used
-by the included minitest suite).
+* `/etc/cisco_node_utils.yaml` (system and/or root user configuration)
+* `~/cisco_node_utils.yaml` (per-user configuration)
 
-### Usage on a Cisco device
+If both files exist and are readable, configuration in the user-specific file will take precedence over the system configuration.
 
-```ruby
-require 'cisco_node_utils'
+This file specifies the host, port, username, and/or password to be used to connect to one or more nodes.
 
-# get a connection to the local device
-node = Cisco::Node.instance()
-
-version = node.config_get("show_version", "system_image")
-
-node.config_set("vtp", "domain", "mycompany.com")
-```
-
-### Remote usage
-
-```ruby
-require 'cisco_node_utils'
+* When developing for or testing this gem, this file can specify one or more NX-OS nodes to run tests against. In this case:
+  - A node labeled as `default` will be the default node to test against.
+  - Nodes with other names can be selected at test execution time.
+  - NX-OS nodes must be defined with a `host` (hostname or IP address), `username`, and `password`.
 
-Cisco::Node.lazy_connect = true
+An example configuration file (illustrating each of the above scenarios) is provided with this gem at [`docs/cisco_node_utils.yaml.example`](docs/cisco_node_utils.yaml.example).
 
-node = Cisco::Node.instance()
-node.connect("n3k.mycompany.com", "username", "password")
+## <a name="documentation">Documentation</a>
 
-version = node.config_get("show_version", "system_image")
+### Client
 
-node.config_set("vtp", "domain", "mycompany.com")
-```
+The `Client` class provides a low-level interface for communicating with the Cisco network node. It provides the base APIs `create`, `get`, and `set`.
 
-## <a name="documentation">Documentation</a>
+* `Cisco::Client::NXAPI` - client for communicating with NX-OS 7.0(3)I2(1) and later, using NX-API.
 
+For a greater level of abstraction, the `Node` class is generally used, but the `Client` classes can be invoked directly if desired.
 
 ### Node
 
-The `Node` class is a singleton which provides for management of a given Cisco
-network node. It provides the base APIs `config_set`, `config_get`, and
-`config_get_default`.
+The `Node` class is a singleton which wraps around the `Client` class to provide for management of a given Cisco network node. It provides the base APIs `config_set`, `config_get`, and `config_get_default`.
 
 ### CommandReference
 
-The `CommandReference` class abstracts away the differences between various supported `Node` types, be that API differences (CLI vs. YANG), platform differences (NX-OS vs. IOS XR), or hardware differences (Nexus 9xxx vs. Nexus 3xxx). A series of YAML files describe various `feature` groupings. Each file describes a set of `attributes` of the given feature and the specifics of how to inspect and manage these attributes for any supported `Node` types.  When a `Node` is connected, the platform identification of the Node is used to construct a `CommandReference` instance containing a set of `CmdRef` objects specific to this `Node`. The `Node` APIs `config_set`, `config_get`, and `config_get_default` all rely on the `CmdRef`.
+The `CommandReference` class abstracts away the differences between various supported `Node` types, be that API differences (CLI vs. YANG) or hardware differences (Nexus N9k vs. Nexus N3k). A series of YAML files describe various `feature` groupings. Each file describes a set of `attributes` of the given feature and the specifics of how to inspect and manage these attributes for any supported `Node` types.  When a `Node` is connected, the platform identification of the Node is used to construct a `CommandReference` instance containing a set of `CmdRef` objects specific to this `Node`. The `Node` APIs `config_set`, `config_get`, and `config_get_default` all rely on the `CmdRef`.
 
 See also [README_YAML](lib/cisco_node_utils/cmd_ref/README_YAML.md).
 
@@ -132,6 +117,66 @@ code duplication between the Cisco Puppet modules and the Cisco Chef cookbooks.
 Generally speaking, Puppet and Chef should only interact with the feature
 provider classes, and not directly call into `CommandReference` or `Node`.
 
+## <a name="examples">Examples</a>
+
+
+These utilities can be used directly on a Cisco device (as used by Puppet
+and Chef) or can run on a workstation and point to a Cisco device (as used
+by the included minitest suite).
+
+### Usage on a Cisco device
+
+#### Low-level Client API
+
+```ruby
+require 'cisco_node_utils'
+
+# get a connection to the local device
+client = Cisco::Client.create()
+
+client.get(command: 'show version')
+client.set(values: 'vtp domain mycompany.com')
+```
+
+#### High-level Node API
+
+```ruby
+require 'cisco_node_utils'
+
+# get a connection to the local device
+node = Cisco::Node.instance()
+
+version = node.config_get("show_version", "system_image")
+
+node.config_set("vtp", "domain", "mycompany.com")
+```
+
+### Remote usage
+
+#### Low-level Client API
+
+```ruby
+require 'cisco_node_utils'
+
+client = Cisco::Client.create('n3k.mycompany.com', 'username', 'password')
+
+client.get(command: 'show version')
+client.set(values: 'vtp domain mycompany.com')
+```
+
+#### High-level Node API
+
+```ruby
+require 'cisco_node_utils'
+
+node = Cisco::Node.new("n3k.mycompany.com", "username", "password")
+
+version = node.config_get("show_version", "system_image")
+
+node.config_set("vtp", "domain", "mycompany.com")
+```
+
+
 ## <a name="changelog">Changelog</a>
 
 

data/Rakefile

@@ -1,13 +1,35 @@
 require 'bundler/gem_tasks'
 require 'rubocop/rake_task'
 require 'rake/testtask'
+require 'rspec/core/rake_task'
 
 # test task is not part of default task list,
 # because it requires a node to test against
-task default: %w(rubocop build)
+task default: %w(rubocop spec build)
 
 RuboCop::RakeTask.new
 
+RSpec::Core::RakeTask.new(:spec_common) do |t|
+  t.pattern = 'spec/*_spec.rb'
+  t.rspec_opts = '--format documentation'
+  t.verbose = false
+end
+spec_tasks = [:spec_common]
+
+# Because each of the below specs requires a clean Ruby environment,
+# they need to be run individually instead of as a single RSpec task.
+Dir.glob('spec/isolate/*_spec.rb').each do |f|
+  task = File.basename(f, '.rb').to_sym
+  RSpec::Core::RakeTask.new(task) do |t|
+    t.pattern = f
+    t.rspec_opts = '--format documentation'
+    t.verbose = false
+  end
+  spec_tasks << task
+end
+
+task spec: spec_tasks
+
 task :build do
   system 'gem build cisco_node_utils.gemspec'
 end