[Proposal] GRPC connection plugin to interact with network devices that support gRPC

[GomathiselviS]

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:

1. 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.
2. 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.
3. 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.
4. 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:
  1. 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.
  2. state: The operation that needs to be performed on the candidate datastore. Valid values are merged, replaced, and deleted. The default value is merged. merged: If the value is merged the configuration data in the config option is merged with the configuration at the corresponding level in the target datastore. If the value is replaced the configuration data in the config option completely replaces the configuration in the target datastore. If the value is deleted the configuration data in the config option is deleted.
  3. 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.
  4. 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

[ganeshrn]

As a user, I want to connect to any gRPC enabled remote device and stream the data constantly in various streaming options provided by HTTP 2, bidirectionally.

This might not be possible and ansible work with request and response model

[ganeshrn]

grpc_nw_get module can be renamed to grpc_get since the module will be in netcommon collection nw is not required in the name. Applicable for other modules as well.

[ganeshrn]

section option can be replace with filter to be in sync with other network modules (eg. netconf_get)

[ganeshrn]

default_operation option is applicable for netconf modules. If in case the grpc server doesn't support these options we might able to add that functionality within the module. Can mention this in the module docs