ansible.network
ansible.network copied to clipboard
[Proposal] GRPC connection plugin to interact with network devices that support gRPC
Proposal:
GRPC connection plugin to interact with network devices that support gRPC Author: Gomathi Selvi Srinivasan (@GomathiselviS)
Date: 2021/05/20
- Status: New
- Proposal type:
- Targeted Release:
- Associated PR:
- Estimated time to implement: 6 weeks
Motivation
Describe the reasons for this proposal. Provide GRPC modules to interact with devices that have gRPC services enabled.
Problems
- As a user, I want to connect to any gRPC enabled remote device and fetch configuration from running/ startup datastore based on device capability.
- As a user, I want to connect to any gRPC enabled remote device and fetch operational state data
- As a user, I want to connect to any gRPC enabled remote device and edit the configuration running/candidate datastore based on device capability.
- As a user, I want to connect to any gRPC enabled remote device and call methods supported by the remote device directly on the device
- As a user, I want to connect to any gRPC enabled remote device and take a back up of the current configuration on the device.
Solution proposal
-
grpc_get
module: The module fetches configuration and state data from a remote gRPC enabled target host. Options:
-
section
: This argument specifies the string which acts as a filter to restrict the portions of the data to be are retrieved from remote device. If this option is not specified the entire configuration or state data is returned in response provided it is supported by the target host. -
command
: The option specifies the command to be executed on the target host and returns the response in the result. This option is supported if the gRPC target host supports executing the CLI command over the gRPC connection. -
display
: This argument specifies an encoding scheme to use when serializing output from the device. The encoding scheme value depends on the capability of the gRPC server running on the target host. The values can be I(json), I(text) etc. -
data_type
: This argument specifies the type of data that should be fetched from the target host. The value depends on the capability of the gRPC server running on the target host. The values can be I(config), I(oper) etc. based on what is supported by the gRPC server. By default, it will return both configuration and operational state data in response.
-
grpc_config
module: The module will be used to edit the configuration, copy the configuration from one datastore to another or delete a complete configuration datastore on a remote gRPC enabled host. Options:-
config
: This option specifies the string which acts as a filter to restrict the portions of the data to be retrieved from the target host device. If this option is not specified the entire configuration or state data is returned in response provided it is supported by the target host. -
state
: The operation that needs to be performed on the candidate datastore. Valid values aremerged
,replaced
, anddeleted
. The default value ismerged
. merged: If the value ismerged
the configuration data in theconfig
option is merged with the configuration at the corresponding level in the target datastore. If the value isreplaced
the configuration data in theconfig
option completely replaces the configuration in the target datastore. If the value isdeleted
the configuration data in theconfig
option is deleted. -
backup
: This argument will cause the module to create a full backup of the current C(running-config) from the remote device before any changes are made. If the C(backup_options) value is not given, the backup file is written to the C(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:
: This is a dict object containing configurable options related to backup file path. The value of this option is read only when C(backup) is set to I(yes), if C(backup) is set to I(no) this option will be silently ignored.
-
- name: run cli command
grpc_get:
command: 'show version'
display: text
- name: Get bgp configuration data
grpc_get:
section: '{"Cisco-IOS-XR-ipv4-bgp-cfg:bgp": [null]}'
- name: Get configuration JSON format over secure TLS channel
grpc_get:
display: json
data: config
vars:
ansible_root_certificates_file: /home/username/ems.pem
ansible_grpc_channel_options:
'grpc.ssl_target_name_override': 'ems.cisco.com'
- name: Merge static route config
ansible.netcommon.grpc_config:
config:
Cisco-IOS-XR-ip-static-cfg:router-static:
default-vrf:
address-family:
vrfipv4:
vrf-unicast:
vrf-prefixes:
vrf-prefix:
- prefix: "1.2.3.6"
prefix-length: 32
vrf-route:
vrf-next-hop-table:
vrf-next-hop-next-hop-address:
- next-hop-address: "10.0.2.2"
state: merged
- name: Find diff
diff: True
ansible.netcommon.grpc_config:
config: "{{ lookup('file', 'bgp_start.yml') }}"
state: merged
- name: Backup running config
ansible.netcommon.grpc_config:
backup: yes
- name: Replace bgp config
ansible.netcommon.grpc_config:
config: "{{ lookup('file', 'bgp.yml') }}"
state: replaced
- name: Delete bgp config
ansible.netcommon.grpc_config:
config: "{{ lookup('file', 'bgp.yml') }}"
state: deleted
Testing (optional)
- Add integration and unit test for
grpc_config
module. - Add integration and unit test for
grpc_get
module.
Documentation (optional)
- Update module documentation for
grpc_get
,grpc_config