pygnmi: gNMI Client for Network Automation

Common errors

• _InactiveRpcError: <_InactiveRpcError of RPC that terminated with: status = StatusCode.UNAUTHENTICATED details = "Authentication failed"

  cause Incorrect username/password, or missing authentication details in the gNMI client configuration.
  fix Verify the `username` and `password` in the `target` dictionary. Ensure these credentials match what the gNMI server expects.

• _InactiveRpcError: <_InactiveRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE details = "Connect Failed"

  cause The gNMI server is unreachable, incorrect host/port in the target address, or a firewall is blocking the connection.
  fix Check the `addr` in the `target` dictionary for correct host and port. Ensure the gNMI server is running and network connectivity exists between the client and server.

• TypeError: 'NoneType' object is not subscriptable

  cause Attempting to access elements of a gNMI response that is `None` or empty, often due to an invalid gNMI path or the requested data not existing on the device.
  fix Verify the gNMI `path` is correct and exists on the target device. Add checks for `None` or empty responses (e.g., `if response and response.notification:`) before processing data.

• TypeError: subscribe() got an unexpected keyword argument 'qos'

  cause Using arguments (like `qos`) that are only supported by the `subscribe2()` method with the older `subscribe()` method, or attempting to use a feature not supported by the target device.
  fix Migrate from `subscribe()` to `subscribe2()` for all telemetry subscriptions, as `subscribe2()` is the recommended and actively developed method. Ensure all arguments are appropriate for `subscribe2()` and supported by your gNMI target.

Warnings

• deprecated The `subscribe()` method is being deprecated in favor of `subscribe2()`. It is strongly recommended to migrate telemetry collection to `subscribe2()` for future compatibility and improved functionality.
  Fix: Refactor telemetry code to use `pygnmi.client.gNMIclient.subscribe2()` for all new and existing telemetry collection.
• gotcha Prior to v0.8.9, `encoding` had a default value. From v0.8.9, `encoding` defaults to `None` and `capabilities()` is called on connect to auto-detect the supported encoding (with `json` and `json_ietf` preferred). Explicitly setting an encoding might be necessary if auto-detection doesn't pick the desired one or if upgrading from older versions.
  Fix: When creating `gNMIclient` or calling `get`/`subscribe2`, explicitly pass the `encoding` parameter (e.g., `encoding='JSON_IETF'`) if auto-detection is not sufficient or if migrating from pre-0.8.9 code.
• breaking Version 0.8.11 fixed a telemetry break for Juniper devices caused by inconsistencies between `Capabilities()` communicated encodings and actual `Subscribe()` support. If experiencing issues with Juniper telemetry on versions prior to 0.8.11, upgrade immediately.
  Fix: Upgrade `pygnmi` to v0.8.11 or later to resolve Juniper telemetry issues and ensure correct encoding handling.
• gotcha By default, `gNMIclient` uses `insecure=True`, which is suitable for development but not for production. For secure deployments, TLS must be configured.
  Fix: For production, set `insecure: False` in the `target` dictionary and provide `root_certificates`, `private_key`, and `certificate_chain` for proper TLS authentication.

Install

• pip install pygnmi Install latest version

Imports

• gNMIclient

  from pygnmi.client import gNMIclient

Quickstart

This quickstart demonstrates how to connect to a gNMI target, retrieve its capabilities, and perform a 'Get' operation for a specific path. It includes placeholders for host, port, and credentials, defaulting to common local development values or environment variables. An example for 'Subscribe' is provided but commented out.

import os
from pygnmi.client import gNMIclient

# Environment variables for connection details or default values
GNMI_HOST = os.environ.get('GNMI_HOST', 'localhost')
GNMI_PORT = int(os.environ.get('GNMI_PORT', '50051'))
GNMI_USERNAME = os.environ.get('GNMI_USERNAME', 'admin')
GNMI_PASSWORD = os.environ.get('GNMI_PASSWORD', 'admin')

# Configure the gNMI target
target = {
    'addr': f'{GNMI_HOST}:{GNMI_PORT}',
    'username': GNMI_USERNAME,
    'password': GNMI_PASSWORD,
    'insecure': True,  # Set to False for secure TLS connections and provide certificates
    'encoding': 'JSON_IETF', # Or None to auto-detect based on device capabilities
}

try:
    with gNMIclient(target=target) as c:
        # Get device capabilities
        capabilities = c.capabilities()
        print("\n--- Device Capabilities ---")
        print(capabilities)

        # Example: Get system hostname (path may vary by device/OS)
        # Using a common path, adjust as needed for your device
        hostname_path = ['/system/state/hostname']
        get_response = c.get(path=hostname_path, encoding='JSON_IETF')
        print("\n--- Get Response (Hostname) ---")
        print(get_response)

        # Example: Subscribe to an operational state (uncomment to run)
        # subscription_paths = [
        #    ('/interfaces/interface[name=eth0]/state/oper-status', True)
        # ]
        # print("\n--- Subscribe (Streaming) ---")
        # for update in c.subscribe2(path_tuples=subscription_paths, subscribe_mode='STREAM', encoding='JSON_IETF'):
        #    print(update)
        #    # Add logic to break from loop after a few updates or a timeout

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure the gNMI server is running and accessible with correct credentials.")