Ansible Collection - ansible.yang
This repo hosts the ansible.yang Ansible Collection.
The collection includes the ansible plugins to help support Yang mainly with network devices.
Ansible version compatibility
This collection has been tested against following Ansible versions: >=2.14.0.
For collections that support Ansible 2.9, please ensure you update your network_os to use the
fully qualified collection name (for example, cisco.ios.ios).
Plugins and modules within a collection may be tested with only specific Ansible versions.
A collection may contain metadata that identifies these versions.
PEP440 is the schema used to describe the versions of Ansible.
Supported connections
The Ansible yang collection supports netconf connections.
Included content
Lookup plugins
| Name | Description |
|---|
| ansible.yang.json2xml | Validates json configuration against yang data model and convert it to xml. |
| ansible.yang.spec | This plugin reads the content of given yang document and generates json and xml configuration skeleton and a tree structure of yang document. |
| ansible.yang.xml2json | Converts xml input to json structure output by mapping it against corresponding Yang model |
Modules
Installation and Usage
Installing the Collection from Ansible Galaxy
Before using the Ansible Yang collection, you need to install it with the ansible-galaxy CLI:
ansible-galaxy collection install ansible.yang
You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml using the format:
---
collections:
- name: ansible.yang
Platforms test against
1. Cisco IOSXR 6.1.3
Use modules from the yang Collection in your playbooks
It's preferable to use content in this collection using their Fully Qualified Collection Namespace (FQCN), for example ansible.yang.configure:
---
- hosts: iosxr
gather_facts: false
connection: ansible.netcommon.netconf
tasks:
- name: "Fetch given yang model and all the dependent models from remote host"
ansible.yang.fetch:
name: Cisco-IOS-XR-ifmgr-cfg
- name: get interface configuration in json/xml format
ansible.yang.get:
filter: |
<interface-configurations xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg"><interface-configuration>
</interface-configuration></interface-configurations>
file: "./files/cisco/iosxr/*.yang"
search_path: "./files/cisco/iosxr"
register: result
- name: Configure interface description providing json input file
ansible.yang.configure:
config: "{{ lookup('file', config_file) }}"
file: "{{ yang_file }}"
search_path: "{{ search_path }}"
register: result
- name: Configure interface description with json input
ansible.yang.configure:
config:
{
"Cisco-IOS-XR-ifmgr-cfg:interface-configurations": {
"interface-configuration": [
{
"active": "act",
"description": "test for ansible 400",
"interface-name": "Loopback888",
"interface-virtual": [
null
],
"shutdown": [
null
]
},
{
"active": "act",
"description": "This interface is configures with Ansible",
"interface-name": "GigabitEthernet0/0/0/4"
}
]
}
}
file: "{{ yang_file }}"
search_path: "{{ search_path }}"
register: result
- name: generate spec from open-config interface yang model data and represent in xml, json and yang tree
ansible.yang.generate_spec:
file: "{{ spec_yang_file }}"
search_path: "{{ spec_search_path }}"
doctype: config
json_schema:
path: "./output/{{ inventory_hostname }}/openconfig-interfaces-config.json"
defaults: True
xml_schema:
path: "./output/{{ inventory_hostname }}/openconfig-interfaces-config.xml"
defaults: True
annotations: True
tree_schema:
path: "./output/{{ inventory_hostname }}/openconfig-interfaces-config.tree"t
For documentation on how to use individual modules and other content included in this collection, please see the links in the 'Included content' section earlier in this README.
Testing and Development
If you want to develop new content for this collection or improve what's already here, the easiest way to work on the collection is to clone it into one of the configured COLLECTIONS_PATHS, and work on it there.
Testing with ansible-test
The tests directory contains configuration for running sanity and integration tests using ansible-test.
To run these network integration tests, use ansible-test network-integration --inventory :
ansible-test network-integration --inventory ~/myinventory -vvv <name of the plugin>
Publishing New Versions
Releases are automatically built and pushed to Ansible Galaxy for any new tag. Before tagging a release, make sure to do the following:
- Update
galaxy.yml and this README's requirements.yml example with the new version for the collection.
- Update the CHANGELOG:
- Make sure you have
antsibull-changelog installed.
- Make sure there are fragments for all known changes in
changelogs/fragments.
- Run
antsibull-changelog release.
- Commit the changes and create a PR with the changes. Wait for tests to pass, then merge it once they have.
- Tag the version in Git and push it to GitHub.
After the version is published, verify it exists on the [Ansible Yang Community Collection Galaxy page](https://galaxy.ansible.com/ansible/yang).
See Also:
Contributing to this collection
We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the Ansible Yang collection repository.
- Make changes
- Detail changes in a fragment. example
- Submit PR
You can also join us on:
- IRC - the
#ansible-network libera.chat channel
- Slack - https://ansiblenetwork.slack.com
See the Ansible Community Guide for details on contributing to Ansible.
Changelogs
Change log
Roadmap
More information
Licensing
GNU General Public License v3.0 or later.
See LICENSE to see the full text.
