Adding Netbox
This commit is contained in:
Patrick Toal
@@ -0,0 +1,48 @@
|
||||
Using the Network Engine Role
|
||||
----------------------------------
|
||||
|
||||
The Network Engine role is supported as a dependency of other Roles. The Network Engine Role extracts data about your network devices as Ansible facts in a JSON data structure, ready to be added to your inventory host facts and/or consumed by Ansible tasks and templates. You define the data elements you want to extract from each network OS command in parser templates, using either YAML or Google TextFSM syntax. The matching rules may be different on each network platform, but by defining the same variable names for the output on all platforms, you can normalize similar data across platforms. That's how the Network Engine Role supports truly platform-agnostic network automation.
|
||||
|
||||
The Network Engine role can also be used directly, though direct usage is not supported with your Red Hat subscription.
|
||||
|
||||
The initial release of the Network Engine role includes two parser modules:
|
||||
* [command_parser](https://github.com/ansible-network/network-engine/blob/devel/docs/user_guide/command_parser.md) accepts YAML input, uses an internally maintained, loosely defined parsing language based on Ansible playbook directives
|
||||
* [textfsm_parser](https://github.com/ansible-network/network-engine/blob/devel/docs/user_guide/textfsm_parser.md) accepts Google TextFSM input, uses Google TextFSM parsing language
|
||||
|
||||
Both modules iterate over the data definitions in your parser templates, parse command output from your network devices (structured ASCII text) to find matches, and then convert the matches into Ansible facts in a JSON data structure.
|
||||
|
||||
The task ```cli``` provided by the role, can also be directly implemented in your playbook. The documentation can be found here [tasks/cli](https://github.com/ansible-network/network-engine/blob/devel/docs/tasks/cli.md).
|
||||
|
||||
To manage multiple interfaces and vlans, the Network Engine role also offers [filter_plugins](https://github.com/ansible-network/network-engine/blob/devel/docs/plugins/filter_plugins.md) that turn lists of Interfaces or VLANs into ranges and vice versa.
|
||||
|
||||
Modules:
|
||||
--------
|
||||
- `command_parser`
|
||||
- `textfsm_parser`
|
||||
- `net_facts`
|
||||
|
||||
To use the Network Engine Role:
|
||||
----------------------------------------
|
||||
1. Install the role from Ansible Galaxy
|
||||
`ansible-galaxy install ansible-network.network-engine` will copy the Network Engine role to `~/.ansible/roles/`.
|
||||
1. Select the parser engine you prefer
|
||||
For YAML formatting, use `command_parser`; for TextFSM formatting, use `textfsm_parser`. The parser docs include
|
||||
examples of how to define your data and create your tasks.
|
||||
1. Define the data you want to extract (or use a pre-existing parser template)
|
||||
See the parser_template sections of the command_parser and textfsm_parser docs for examples.
|
||||
1. Create a playbook to extract the data you've defined
|
||||
See the Playbook sections of the command_parser and textfsm_parser docs for examples.
|
||||
1. Run the playbook with `ansible-playbook -i /path/to/your/inventory -u my_user -k /path/to/your/playbook`
|
||||
1. Consume the JSON-formatted Ansible facts about your device(s) in inventory, templates, and tasks.
|
||||
|
||||
Additional Resources
|
||||
-------------------------------------
|
||||
|
||||
* [README](https://galaxy.ansible.com/ansible-network/network-engine/#readme)
|
||||
* [command_parser tests](https://github.com/ansible-network/network-engine/tree/devel/tests/command_parser)
|
||||
* [textfsm_parser tests](https://github.com/ansible-network/network-engine/tree/devel/tests/textfsm_parser)
|
||||
* [Full changelog diff](https://github.com/ansible-network/network-engine/blob/devel/CHANGELOG.rst)
|
||||
|
||||
Contributing and Reporting Feedback
|
||||
-------------------------------------
|
||||
[Review issues](https://github.com/ansible-network/network-engine/issues)
|
||||
@@ -0,0 +1,223 @@
|
||||
# command_parser
|
||||
|
||||
The [command_parser](https://github.com/ansible-network/network-engine/blob/devel/library/command_parser.py)
|
||||
module is closely modeled after the Ansible playbook language.
|
||||
This module iterates over matching rules defined in YAML format, extracts data from structured ASCII text based on those rules,
|
||||
and returns Ansible facts in a JSON data structure that can be added to the inventory host facts and/or consumed by Ansible tasks and templates.
|
||||
|
||||
The `command_parser` module requires two inputs:
|
||||
- the output of commands run on the network device, passed to the `content` parameter
|
||||
- the parser template that defines the rules for parsing the output, passed to either the `file` or the `dir` parameter
|
||||
|
||||
## Parameters
|
||||
|
||||
### content
|
||||
|
||||
The `content` parameter for `command_parser` must point to the ASCII text output of commands run on network devices. The text output can be in a variable or in a file.
|
||||
|
||||
|
||||
### file
|
||||
|
||||
The `file` parameter for `command_parser` must point to a parser template that contains a rule for each data field you want to extract from your network devices.
|
||||
|
||||
Parser templates for the `command_parser` module in the Network Engine role use YAML notation.
|
||||
|
||||
|
||||
### dir
|
||||
|
||||
Points to a directory containing parser templates. Use this parameter instead of `file` if your playbook uses multiple parser templates.
|
||||
|
||||
## Sample Parser Templates
|
||||
|
||||
Parser templates for the `command_parser` module in the Network Engine role use YAML syntax.
|
||||
To write a parser template, follow the [parser_directives documentation](docs/directives/parser_directives.md).
|
||||
|
||||
Here are two sample YAML parser templates:
|
||||
|
||||
`parser_templates/ios/show_interfaces.yaml`
|
||||
```yaml
|
||||
|
||||
---
|
||||
- name: parser meta data
|
||||
parser_metadata:
|
||||
version: 1.0
|
||||
command: show interface
|
||||
network_os: ios
|
||||
|
||||
- name: match sections
|
||||
pattern_match:
|
||||
regex: "^(\\S+) is up,"
|
||||
match_all: yes
|
||||
match_greedy: yes
|
||||
register: section
|
||||
|
||||
- name: match interface values
|
||||
pattern_group:
|
||||
- name: match name
|
||||
pattern_match:
|
||||
regex: "^(\\S+)"
|
||||
content: "{{ item }}"
|
||||
register: name
|
||||
|
||||
- name: match hardware
|
||||
pattern_match:
|
||||
regex: "Hardware is (\\S+),"
|
||||
content: "{{ item }}"
|
||||
register: type
|
||||
|
||||
- name: match mtu
|
||||
pattern_match:
|
||||
regex: "MTU (\\d+)"
|
||||
content: "{{ item }}"
|
||||
register: mtu
|
||||
|
||||
- name: match description
|
||||
pattern_match:
|
||||
regex: "Description: (.*)"
|
||||
content: "{{ item }}"
|
||||
register: description
|
||||
loop: "{{ section }}"
|
||||
register: interfaces
|
||||
|
||||
- name: generate json data structure
|
||||
json_template:
|
||||
template:
|
||||
- key: "{{ item.name.matches.0 }}"
|
||||
object:
|
||||
- key: config
|
||||
object:
|
||||
- key: name
|
||||
value: "{{ item.name.matches.0 }}"
|
||||
- key: type
|
||||
value: "{{ item.type.matches.0 }}"
|
||||
- key: mtu
|
||||
value: "{{ item.mtu.matches.0 }}"
|
||||
- key: description
|
||||
value: "{{ item.description.matches.0 }}"
|
||||
loop: "{{ interfaces }}"
|
||||
export: yes
|
||||
register: interface_facts
|
||||
|
||||
```
|
||||
|
||||
`parser_templates/ios/show_version.yaml`
|
||||
|
||||
```yaml
|
||||
|
||||
---
|
||||
- name: parser meta data
|
||||
parser_metadata:
|
||||
version: 1.0
|
||||
command: show version
|
||||
network_os: ios
|
||||
|
||||
- name: match version
|
||||
pattern_match:
|
||||
regex: "Version (\\S+),"
|
||||
register: version
|
||||
|
||||
- name: match model
|
||||
pattern_match:
|
||||
regex: "^Cisco (.+) \\(revision"
|
||||
register: model
|
||||
|
||||
- name: match image
|
||||
pattern_match:
|
||||
regex: "^System image file is (\\S+)"
|
||||
register: image
|
||||
|
||||
- name: match uptime
|
||||
pattern_match:
|
||||
regex: "uptime is (.+)"
|
||||
register: uptime
|
||||
|
||||
- name: match total memory
|
||||
pattern_match:
|
||||
regex: "with (\\S+)/(\\w*) bytes of memory"
|
||||
register: total_mem
|
||||
|
||||
- name: match free memory
|
||||
pattern_match:
|
||||
regex: "with \\w*/(\\S+) bytes of memory"
|
||||
register: free_mem
|
||||
|
||||
- name: export system facts to playbook
|
||||
set_vars:
|
||||
model: "{{ model.matches.0 }}"
|
||||
image_file: "{{ image.matches.0 }}"
|
||||
uptime: "{{ uptime.matches.0 }}"
|
||||
version: "{{ version.matches.0 }}"
|
||||
memory:
|
||||
total: "{{ total_mem.matches.0 }}"
|
||||
free: "{{ free_mem.matches.0 }}"
|
||||
export: yes
|
||||
register: system_facts
|
||||
|
||||
```
|
||||
|
||||
## Sample Playbooks
|
||||
|
||||
To extract the data defined in your parser template, create a playbook that includes the Network Engine role and references the `content` and `file` (or `dir`) parameters of the `command_parser` module.
|
||||
|
||||
Each example playbook below runs a show command, imports the Network Engine role, extracts data from the text output of the command by matching it against the rules defined
|
||||
in your parser template, and stores the results in a variable. To view the content of that final variable, make sure `export: yes` is set in your parser template, and run your playbook in `verbose` mode: `ansible-playbook -vvv`.
|
||||
|
||||
Make sure the `hosts` definition in the playbook matches a host group in your inventory - in these examples, the playbook expects a group called `ios`.
|
||||
|
||||
The first example parses the output of the `show interfaces` command on IOS and creates facts from that output:
|
||||
|
||||
```yaml
|
||||
|
||||
---
|
||||
|
||||
# ~/my-playbooks/gather-interface-info.yml
|
||||
|
||||
- hosts: ios
|
||||
connection: network_cli
|
||||
|
||||
tasks:
|
||||
- name: Collect interface information from device
|
||||
ios_command:
|
||||
commands:
|
||||
- show interfaces
|
||||
register: ios_interface_output
|
||||
|
||||
- name: import the network-engine role
|
||||
import_role:
|
||||
name: ansible-network.network-engine
|
||||
|
||||
- name: Generate interface facts as JSON
|
||||
command_parser:
|
||||
file: "parser_templates/ios/show_interfaces.yaml"
|
||||
content: "{{ ios_interface_output.stdout.0 }}"
|
||||
|
||||
```
|
||||
|
||||
The second example parses the output of the `show version` command on IOS and creates facts from that output:
|
||||
|
||||
```yaml
|
||||
|
||||
---
|
||||
|
||||
# ~/my-playbooks/gather-version-info.yml
|
||||
|
||||
- hosts: ios
|
||||
connection: network_cli
|
||||
|
||||
tasks:
|
||||
- name: Collect version information from device
|
||||
ios_command:
|
||||
commands:
|
||||
- show version
|
||||
register: ios_version_output
|
||||
|
||||
- name: import the network-engine role
|
||||
import_role:
|
||||
name: ansible-network.network-engine
|
||||
|
||||
- name: Generate version facts as JSON
|
||||
command_parser:
|
||||
file: "parser_templates/ios/show_version.yaml"
|
||||
content: "{{ ios_version_output.stdout.0 }}"
|
||||
|
||||
```
|
||||
@@ -0,0 +1,82 @@
|
||||
# textfsm_parser
|
||||
|
||||
The [textfsm_parser](https://github.com/ansible-network/network-engine/blob/devel/library/textfsm_parser.py)
|
||||
module is based on [Google TextFSM](https://github.com/google/textfsm/wiki/TextFSM) definitions.
|
||||
This module iterates over matching rules defined in TextFSM format, extracts data from structured ASCII text based on those rules,
|
||||
and returns Ansible facts in a JSON data structure that can be added to inventory host facts and/or consumed by Ansible tasks and templates.
|
||||
|
||||
The `textfsm_parser` module requires two inputs:
|
||||
- the output of commands run on the network device, passed to the `content` parameter
|
||||
- the parser template that defines the rules for parsing the output, passed to either the `file` or the `src` parameter
|
||||
|
||||
## content
|
||||
|
||||
The `content` parameter for `textfsm_parser` must point to the ASCII text output of commands run on network devices. The text output can be in a variable or in a file.
|
||||
|
||||
## file
|
||||
|
||||
The `file` parameter for `textfsm_parser` must point to a parser template that contains a TextFSM rule for each data field you want to extract from your network devices.
|
||||
|
||||
Parser templates for the `textfsm_parser` module in the Network Engine role use TextFSM notation.
|
||||
|
||||
### name
|
||||
|
||||
The `name` parameter for `textfsm_parser` names the variable in which Ansible will store the JSON data structure. If name is not set, the JSON facts from parsing will not be displayed/exported.
|
||||
|
||||
### src
|
||||
|
||||
The `src` parameter for `textfsm_parser` loads your parser template from an external source, usually a URL.
|
||||
|
||||
## Sample Parser Templates
|
||||
|
||||
Here is a sample TextFSM parser template:
|
||||
|
||||
`parser_templates/ios/show_interfaces`
|
||||
```
|
||||
|
||||
Value Required name (\S+)
|
||||
Value type ([\w ]+)
|
||||
Value description (.*)
|
||||
Value mtu (\d+)
|
||||
|
||||
Start
|
||||
^${name} is up
|
||||
^\s+Hardware is ${type} -> Continue
|
||||
^\s+Description: ${description}
|
||||
^\s+MTU ${mtu} bytes, -> Record
|
||||
|
||||
```
|
||||
|
||||
## Sample Playbooks
|
||||
|
||||
To extract the data defined in your parser template, create a playbook that includes the Network Engine role and references the `content` and `file` parameters of the `command_parser` module.
|
||||
|
||||
The example playbook below runs a show command, imports the Network Engine role, extracts data from the text output of the command by matching it against the rules defined
|
||||
in your parser template, and stores the results in a variable. To view the content of that final variable, add it to the `name` parameter as shown in the example and run the playbook in `verbose` mode: `ansible-playbook -v`.
|
||||
|
||||
Make sure the `hosts` definition in the playbook matches a host group in your inventory - in these examples, the playbook expects a group called `ios`.
|
||||
|
||||
The example below parses the output of the `show interfaces` command on IOS and creates facts from that output:
|
||||
|
||||
```yaml
|
||||
|
||||
---
|
||||
|
||||
# ~/my-playbooks/textfsm-gather-interface-info.yml
|
||||
|
||||
- hosts: ios
|
||||
connection: network_cli
|
||||
|
||||
tasks:
|
||||
- name: Collect interface information from device
|
||||
ios_command:
|
||||
commands: "show interfaces"
|
||||
register: ios_interface_output
|
||||
|
||||
- name: Generate interface facts as JSON
|
||||
textfsm_parser:
|
||||
file: "parser_templates/ios/show_interfaces"
|
||||
content: "{{ ios_interface_output.stdout.0 }}"
|
||||
name: interface_facts
|
||||
|
||||
```
|
||||
Reference in New Issue
Block a user