Skip to content

Latest commit

 

History

History
525 lines (486 loc) · 26.4 KB

community.yang.configure_module.rst

File metadata and controls

525 lines (486 loc) · 26.4 KB
Raw

community.yang.configure

Reads the input configuration in JSON format and pushes to the remote host over netconf

Synopsis

  • The module takes the JSON configuration as input.
  • Pre-validates the config with the corresponding YANG model.
  • Converts input JSON configuration to XML payload to be pushed on the remote host using netconf connection.

Requirements

The below requirements are needed on the host that executes this module.

  • ncclient (>=v0.5.2)
  • pyang

Parameters

Parameter Choices/Defaults Comments
config
dictionary / required
The running-configuration to be pushed onto the device in JSON format (as per RFC 7951).
file
list / elements=path / required
The file path of the YANG model that corresponds to the configuration fetch from the remote host. This options accepts wildcard (*) as well for the filename in case the configuration requires to parse multiple yang file. For example "openconfig/public/tree/master/release/models/interfaces/*.yang"
get_filter
string
The filter in xml string format to fetch a subset of the running-configuration for the YANG model given in file option. If this option is provided it will compare the current running-configuration on the device with what is provided in the config option and push to config value to device only if it is different to ensure idempotent task run.
netconf_options
dictionary
Pass arguments to the lower level component, ansible.netcommon.netconf_config, that this module uses.
backup
boolean
    Choices:
  • no ←
  • yes
This argument will cause the module to create a full backup of the current running-config from the remote device before any changes are made. If the backup_options value is not given, the backup file is written to the backup folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created.
backup_options
dictionary
This is a dict object containing configurable options related to backup file path. The value of this option is read only when backup is set to yes, if backup is set to no this option will be silently ignored.
dir_path
path
This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.
filename
string
The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>
commit
boolean
    Choices:
  • no
  • yes ←
This boolean flag controls if the configuration changes should be committed or not after editing the candidate datastore. This option is supported only if remote Netconf server supports :candidate capability. If the value is set to False commit won't be issued after edit-config operation and user needs to handle commit or discard-changes explicitly.
confirm
integer
Default:
0
This argument will configure a timeout value for the commit to be confirmed before it is automatically rolled back. If the confirm_commit argument is set to False, this argument is silently ignored. If the value of this argument is set to 0, the commit is confirmed immediately. The remote host MUST support :candidate and :confirmed-commit capability for this option to .
confirm_commit
boolean
    Choices:
  • no ←
  • yes
This argument will execute commit operation on remote device. It can be used to confirm a previous commit.
default_operation
string
    Choices:
  • merge
  • replace
  • none
The default operation for <edit-config> rpc, valid values are merge, replace and none. If the default value is merge, the configuration data in the content option is merged at the corresponding level in the target datastore. If the value is replace the data in the content option completely replaces the configuration in the target datastore. If the value is none the target datastore is unaffected by the configuration in the config option, unless and until the incoming configuration data uses the operation operation to request a different operation.
delete
boolean
    Choices:
  • no ←
  • yes
It instructs the module to delete the configuration from value mentioned in target datastore.
error_option
string
    Choices:
  • stop-on-error ←
  • continue-on-error
  • rollback-on-error
This option controls the netconf server action after an error occurs while editing the configuration.
If error_option=stop-on-error, abort the config edit on first error.
If error_option=continue-on-error, continue to process configuration data on error. The error is recorded and negative response is generated if any errors occur.
If error_option=rollback-on-error, rollback to the original configuration if any error occurs. This requires the remote Netconf server to support the error_option=rollback-on-error capability.
lock
string
    Choices:
  • never
  • always ←
  • if-supported
Instructs the module to explicitly lock the datastore specified as target. By setting the option value always is will explicitly lock the datastore mentioned in target option. It the value is never it will not lock the target datastore. The value if-supported lock the target datastore only if it is supported by the remote Netconf server.
save
boolean
    Choices:
  • no ←
  • yes
The save argument instructs the module to save the configuration in target datastore to the startup-config if changed and if :startup capability is supported by Netconf server.
source_datastore
string
Name of the configuration datastore to use as the source to copy the configuration to the datastore mentioned by target option. The values can be either running, candidate, startup or a remote URL

aliases: source
target
string
    Choices:
  • auto ←
  • candidate
  • running
Name of the configuration datastore to be edited. - auto, uses candidate and fallback to running - candidate, edit <candidate/> datastore and then commit - running, edit <running/> datastore directly

aliases: datastore
validate
boolean
    Choices:
  • no ←
  • yes
This boolean flag if set validates the content of datastore given in target option. For this option to work remote Netconf server should support :validate capability.
search_path
path
Default:
"~/.ansible/yang/spec"
is a colon : separated list of directories to search for imported yang modules in the yang file mentioned in path option. If the value is not given it will search in the default directory path.

Notes

Note

  • This module requires the NETCONF system service be enabled on the remote device being managed.
  • This module supports the use of connection=ansible.netcommon.netconf

Examples

- name: configure interface using structured data in JSON format
  community.yang.configure:
    config:
        {
            "openconfig-interfaces:interfaces":
             {
                "interface": [{
                    "name" : "GigabitEthernet0/0/0/2",
                    "config" : {
                        "name" : "GigabitEthernet0/0/0/2",
                        "enabled": true,
                        "description": "configured by Ansible yang role",
                        "mtu": 1024
                    }
                }]
             }
        }
    get_filter: |
        <interface-configurations xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg"><interface-configuration>
        </interface-configuration></interface-configurations>
    file: "{{ playbook_dir }}/public/release/models/interfaces/openconfig-interfaces.yang"
    search_path: "{{ playbook_dir }}/public/release/models"

- name: configure by reading data from file and ensure idempotent task run
  community.yang.configure:
    config: "{{ lookup('file', 'interfaces-config.json') }}"
    get_filter: |
        <interface-configurations xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg"><interface-configuration>
        </interface-configuration></interface-configurations>
    file: "{{ playbook_dir }}/public/release/models/interfaces/openconfig-interfaces.yang"
    search_path: "{{ playbook_dir }}/public/release/models"

- name: Configure native data to running-config
  community.yang.configure:
    config: "{{ candidate['json_data'] }}"
    file: "{{ yang_file }}"
    search_path: "{{ search_path }}"

- name: Netconf options
  community.yang.configure:
    config: "{{ lookup('file', 'interfaces-config.json') }}"
    file: "{{ playbook_dir }}/public/release/models/interfaces/openconfig-interfaces.yang"
    search_path: "{{ playbook_dir }}/public/release/models"
    netconf_options:
      lock: never
      username: system
      password: complex_password

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
diff
dictionary
when diff is enabled
If --diff option in enabled while running, the before and after configuration change are returned as part of before and after key.

Sample:
{'after': '<rpc-reply> <data> <configuration> <version>17.3R1.10</version>...<--snip-->', 'before': '<rpc-reply> <data> <configuration> <version>17.3R1.10</version>...<--snip-->'}


Status

Authors

  • Rohit Thakur (@rohitthakur2590)