MPLS L3VPN Manager (vpnm)

This playbook is true infrastructure-as-code. Users declare a list of VRFs
under Ansible's control, then specify which route-targets should exist.
Any unspecified route-targets are automatically and idempotently removed.
Whenever changes occur, routing and ping reachability is validated.

Contact information:
Email: njrusmc@gmail.com
Twitter: @nickrusso42518

• Supported platforms
• Variables
• Task summary
• Testing

Supported platforms

At present, only Cisco IOS platforms are supported. Cisco IOS-XR may
be added in the future.

Testing was conducted on the following platforms and versions:

• Cisco CSR1000v, version 16.08.01a, running in AWS
• Cisco CSR1000v, version 16.09.02, running in AWS
• Cisco CSR1000v, version 16.12.01a, running in AWS

$ cat /etc/redhat-release
Red Hat Enterprise Linux Server release 7.4 (Maipo)

$ uname -a
Linux ip-10-125-0-100.ec2.internal 3.10.0-693.el7.x86_64 #1 SMP
  Thu Jul 6 19:56:57 EDT 2017 x86_64 x86_64 x86_64 GNU/Linux
$ ansible --version
ansible 2.8.7
  config file = /home/ec2-user/racc/ansible.cfg
  configured module search path = ['/home/ec2-user/.ansible/plugins/modules',
    '/usr/share/ansible/plugins/modules']
  ansible python module location =
    /home/ec2-user/environments/racc287/lib/python3.7/site-packages/ansible
  executable location = /home/ec2-user/environments/racc287/bin/ansible
  python version = 3.7.3 (default, Aug 27 2019, 16:56:53)
    [GCC 4.8.5 20150623 (Red Hat 4.8.5-36)]

Variables

For each host (or group of hosts), a vrf list is defined. This list of
dictionaries has the following format:

---
vrfs:
  - name: "VRF1"
    description: "first VRF"
    rd: "65000:1"
    route_import:
      - "65000:1"
    route_export:
      - "65000:2"
    check:
      routes:
        - "10.3.3.0/30"
        - "10.4.4.0/24"
      pings:
        - "10.3.3.1"
        - "10.4.4.44"
  - name: "VRF2"
    description: "second VRF"
    rd: "65000:2"
    route_import:
      - "65000:1"
    route_export:
      - "65000:2"
    check:
      routes:
        - "10.3.3.0/30"
        - "10.4.4.0/24"
      pings:
        - "10.3.3.1"
        - "10.4.4.44"

The individual components in each dictionary are as follows:

• name: The name of the VRF. Numbers can be used, but should be quoted
  as strings to prevent type mismatches later.
• description: The description of the VRF.
• rd: The BGP route distinguisher that makes all routes in this VRF
  unique from the perspective of BGP.
• route_import: The list of route target (RT) extended communities,
  ideally quoted as strings, which should be imported. Any import RTs not
  in this list that are present on the target host are removed.
• route_export: The list of route target (RT) extended communities,
  ideally quoted as strings, which should be exported. Any export RTs not
  in this list that are present on the target host are removed.
• check: Optional nested dictionary that helps with verification. To
  disable checking entirely, remove this dictionary or set it to false.
  • routes: List of prefixes in CIDR notation which should be present
    in the VRF FIB (CEF table) after RT changes are made. This ensures
    that the configuration actually work, and may help surface unrelated
    issues, such as a BGP VPN route advertisement problem.
  • pings: List of single IP addreses which should be pinged from
    within the VRF. Often this will be an IP from inside one of the
    prefixes specified in the routes key, but it does not have to be.
    This helps surface reachability problems or routing loops.

Task summary

The playbook begins by collecting the existing VRF configuration and parsing
it to retrieve the currently configured import and export RTs for all VRFs
on the router, even those not being managed by this playbook. Next, the
parsed RT information from the router is compared against the user-provided
intended RT configuration. For each user-defined VRF, the playbook determines
which RTs must be added or deleted. RTs absent from the intended RT
configuration are automatically and idempotently removed.

The playbook also configures VRFs in BGP and redistributes any connected
routes. If a user-defined VRF does not exist in the current configuration, it
is added, along with all defined RTs. If a VRF exists in the current
configuration but does not exist in the user-defined configuration, it is
ignored. This conservative behavior allows some VRFs to remain outside of
Ansible's control (for example, a management VRF).

If any changes were made, the system waits for a configurable amount of time,
with a default of 60 seconds. This allows the router to import new routes into
the VRF and affix new exported RTs. It also accounts for the time needed for
VRF FIBs to install their routes upon receipt from BGP. The system also
prints the changes made to stdout. When there are no changes, there is no
wait period and no stdout output.

Last, the routing and ping verification runs. These test cases are run
regardless of whether changes occurred or not.

Please see the outputs in the samples/ directory to see the playbook output.

Testing

This playbook comes with three test phases, executed in sequence:

1. Linting: Perform YAML and Python linting, as well as Python static code
   analysis first. Immediately fail if linting fails to prevent executing
   insecure or syntactically incorrect code. Uses the pylint package.
2. Formatting: Ensure Python files are formatted in a simple, consistent
   way using the black package.
3. Unit tests: Perform regression testing on custom Python filters with mock
   inputs. Immediately fail if unit tests fail to prevent playbook issues.
4. Integration tests: These tests the entire system minus the actual
   login to a network device. All actions requiring network device interaction
   are tagged with do_ssh which is skipped when these tests are run. Mock
   inputs are supplied as variables when the playbook is invoked through the
   test playbook wrapper.

To simplify testing both for CI and for manual executions, a GNU Makefile
with phony targets is used. Use the following shortcuts to test the playbook.
It is recommend to run all tests immediately after cloning to save yourself
the pain of discovering bugs during development.

1. make lint: Runs the linting process
2. make unit: Runs the unit tests
3. make pb: Runs the playbook tests
4. make test: Runs all tests (linting, unit, and playbook, in that order)

Please see .travis.yml for more details on how the tests are executed.

Use Case