gNMI は Google によって開発された gRPC ネットワーク管理インターフェイスです。gNMI はネットワーク デバイスの設定をインストール、操作、および削除し、また、運用データの表示も実行するメカニズムです。gNMI を通じて提供されるコンテンツは YANG を使用してモデル化できます。

gRPC は、クラウド サーバと通信するモバイル クライアントを使用して低遅延で拡張可能な配布を実現するために Google によって開発されたリモート プロシージャ コールです。gRPC は gNMI を伝送し、データと動作要求を公式化して送信する手段を提供します。

gNMI サービスの障害が発生した場合、gNMI ブローカ（GNMIB）によって、up から down への動作状態の変化が示され、データベースが起動して実行されるまではすべての RPC がサービス利用不可のメッセージを返します。リカバリ時には、GNMIB によって down から up への動作状態の変化が示され、RPC の通常の処理が再開されます。

gNMI は <subscribe> RPC サービスをサポートします。詳細については、「モデル駆動型テレメトリ」の章を参照してください。

RFC 7951 では、YANG データ ツリーとそのサブツリーの JavaScript オブジェクト表記（JSON）エンコーディングが規定されています。gNMI は、コンテンツ層でのデータのエンコードに JSON を使用します。

JSON タイプは、値が JSON 文字列としてエンコードされていることを示します。JSON_IETF でエンコードされたデータは、RFC 7951 で規定されている JSON シリアル化のルールに準拠している必要があります。クライアントとターゲットの両方が JSON エンコーディングをサポートしている必要があります。

YANG データ ノード（リーフ、コンテナ、リーフリスト、リスト、anydata ノード、および anyxml ノード）のインスタンスは、JSON オブジェクトまたは名前と値のペアのメンバーとしてエンコードされます。エンコーディング ルールは、設定データ、状態データ、RPC 操作のパラメータ、アクション、通知など、すべてのタイプのデータ ツリーで同じです。

データ ノード インスタンスはすべて名前と値のペアとしてエンコードされ、その名前はデータ ノード識別子から形成されます。値は、データ ノードのカテゴリによって異なります。

leaf foo {
 type uint8;
}

"foo": 123

gNMI Get RPC は、データ ツリーから、1 つ以上の設定属性、状態属性、派生状態属性、またはサポートされているモードに関連付けられたすべての属性を取得する方法を指定します。データ ツリーから値を取得するために、GetRequest がクライアントからターゲットに送信されます。GetRequest への応答として GetResponse が送信されます。

The following is a path for the 
openconfig-interfaces model
++++++++ Sending get request: ++++++++
path {
  elem {
    name: "interfaces"
  }
  elem {
    name: "interface"
    key {
      key: "name"
      value: "Loopback111"
    }
  }
}
 

encoding: JSON_IETF
++++++++ Received get response: ++++++++
notification {
  timestamp: 1521699434792345469
  update {
    path {
      elem {
        name: "interfaces"
      }
      elem {
        name: "interface"
        key {
          key: "name"
          value: "\"Loopback111\""
        }
      }
    }


    val {
      json_ietf_val: "{\n\t\"openconfig-interfaces:name\":\t\
      "Loopback111\",\n\t\
       "openconfig-interfaces:config\":\t{\n\t\t\
       "openconfig-interfaces:type\":\t\"ianaift:
        softwareLoopback\",\n\t\t\
       "openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\
       "openconfig-interfaces:enabled\":\t\"true\"\n\t},\n\t\
       "openconfig-interfaces:state\":\t{\n\t\t\
       "openconfig-interfaces:type\":\t\"ianaift:
        softwareLoopback\",\n\t\t\
       "openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\
       "openconfig-interfaces:enabled\":\t\"true\",\n\t\t\
       "openconfig-interfaces:ifindex\":\t52,\n\t\t\


       "openconfig-interfaces:admin-status\":\t\"UP\",\n\t\t\
       "openconfig-interfaces:oper-status\":\t\"UP\",\n\t\t\
       "openconfig-interfaces:last-change\":\t2018,\n\t\t\
       "openconfig-interfaces:counters\":\t{\n\t\t\t\
       "openconfig-interfaces:in-octets\":\t0,\n\t\t\t\
       "openconfig-interfaces:in-unicast-pkts\":\t0,\n\t\t\t\
       "openconfig-interfaces:in-broadcast-pkts\":\t0,\n\t\t\t\
       "openconfig-interfaces:in-multicast-pkts\":\t0,\n\t\t\t\
       "openconfig-interfaces:in-discards\":\t0,\n\t\t\t\
       "openconfig-interfaces:in-errors\":\t0,\n\t\t\t\
       "openconfig-interfaces:in-unknown-protos\":\t0,\n\t\t\t\
       "openconfig-interfaces:out-octets\":\t0,\n\t\t\t\
       "openconfig-interfaces:out-unicast-pkts\":\t0,\n\t\t\t\
       "openconfig-interfaces:out-broadcast-pkts\":\t0,\n\t\t\t\
       "openconfig-interfaces:out-multicast-pkts\":\t0,\n\t\t\t\
       "openconfig-interfaces:out-discards\":\t0,\n\t\t\t\
       "openconfig-interfaces:out-errors\":\t0,\n\t\t\t\
       "openconfig-interfaces:last-clear\":\t2018\n\t\t},\n\t\t\

       "openconfig-platform:hardware-port\":\t\
       "Loopback111\"\n\t},\n\t\
       "openconfig-interfaces:subinterfaces\":\t{\n\t\t\
       "openconfig-interfaces:index\":\t0,\n\t\t\
       "openconfig-interfaces:config\":\t{\n\t\t\t\
       "openconfig-interfaces:index\":\t0,\n\t\t\t\
       "openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\t\
       "openconfig-interfaces:enabled\":\t\"true\"\n\t\t},\n\t\t\
       "openconfig-interfaces:state\":\t{\n\t\t\t\
       "openconfig-interfaces:index\":\t0,\n\t\t\t\
       "openconfig-interfaces:name\":\t\"Loopback111.0\",\n\t\t\t\
       "openconfig-interfaces:enabled\":\t\"true\",\n\t\t\t\
       "openconfig-interfaces:admin-status\":\t\"UP\",\n\t\t\t\
       "openconfig-interfaces:oper-status\":\t\"UP\",\n\t\t\t\
       "openconfig-interfaces:last-change\":\t2018,\n\t\t\t\
       "openconfig-interfaces:counters\":\t{\n\t\t\t\t\
       "openconfig-interfaces:in-octets\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:in-unicast-pkts\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:in-broadcast-pkts\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:in-multicast-pkts\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:in-discards\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:in-errors\":\t0,\n\t\t\t\t\

       "openconfig-interfaces:out-octets\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:out-unicast-pkts\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:out-broadcast-pkts\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:out-multicast-pkts\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:out-discards\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:out-errors\":\t0,\n\t\t\t\t\
       "openconfig-interfaces:last-clear\":\
        t2018\n\t\t\t}\n\t\t},\n\t\t\
       "openconfig-if-ip:ipv6\":\t{\n\t\t\t\
       "openconfig-if-ip:config\":\t\"false\",\n\t\t\t\
       "openconfig-if-ip:state\":\t\"false\"\n\t\t}\n\t}\n}"
    }
  }
}
 
 

++++++++ Sending get request: ++++++++
path {
  elem {
    name: "interfaces"
  }
  elem {
    name: "interface"
    key {
      key: "name"
      value: "Loopback111"
    }
  }
  elem {
    name: "state"
  }
  elem {
    name: "oper-status"
  }
}

encoding: JSON_IETF
++++++++ Received get response: ++++++++
notification {
  timestamp: 1521699326012374332
  update {
    path {
      elem {
        name: "interfaces"
      }
      elem {
        name: "interface"
        key {
          key: "name"
          value: "\"Loopback111\""
        }
      }
      elem {
        name: "state"
      }
      elem {
        name: "oper-status"
      }
    }
    val {
      json_ietf_val: "\"UP\""
    }
  }
}

Set RPC は、サポートされているモデルに関連付けられた 1 つ以上の設定可能な属性を設定する方法を指定します。データツリー内の値を更新するために、SetRequest がクライアントからターゲットに送信されます。

SetRequest は JSON キーもサポートしており、キーには YANG プレフィックスが含まれている必要があります。このプレフィックスでは要素の名前空間が親とは異なります。

たとえば、openconfig-vlan.yang の拡張から派生した routed-vlan は、親ノードの名前空間とは異なるため（親ノードのプレフィックスは oc-if）、oc-vlan:routed-vlan と入力する必要があります。

1 つの SetRequest に含まれる削除、置換、および更新は、全体で 1 つのトランザクション セットとして扱われます。トランザクションのいずれかの下位要素で障害が発生した場合は、トランザクション全体が拒否されてロールバックされます。SetRequest に対して SetResponse が返信されます。

++++++++ Sending set request: ++++++++
update {
  path {
    elem {
      name: "interfaces"
    }
    elem {
      name: "interface"
      key {
        key: "name"
        value: "Loopback111"
      }
    }
    elem {
      name: "config"
    }
  }
  val {
    json_ietf_val: "{\"openconfig-interfaces:enabled\":\"false\"}"
  }
}

++++++++ Received set response: ++++++++
response {
  path {
    elem {
      name: "interfaces"
    }
    elem {
      name: "interface"
      key {
        key: "name"
        value: "Loopback111"
      }
    }
    elem {
      name: "config"
    }
  }
  op: UPDATE
}
timestamp: 1521699342123890045
 
 
 

++++++++ Sending set request: ++++++++
update {
  path {
    elem {
      name: "interfaces"
    }
    elem {
      name: "interface"
      key {
        key: "name"
        value: "Loopback111"
      }
    }
    elem {
      name: "config"
    }
    elem {
      name: "description"
    }
  }
  val {
    json_ietf_val: "\"UPDATE DESCRIPTION\""
  }
}

++++++++ Received set response: ++++++++
response {
  path {
    elem {
      name: "interfaces"
    }
    elem {
      name: "interface"
      key {
        key: "name"
        value: "Loopback111"
      }
    }
    elem {
      name: "config"
    }
    elem {
      name: "description"
    }
  }
  op: UPDATE
}
timestamp: 1521699342123890045

名前空間は、メッセージの origin フィールドで使用されるパス プレフィックスを指定します。

ここでは、Cisco IOS XE Gibraltar 16.10.1 以降のリリースで使用される名前空間について説明します。

• RFC 7951 で指定された名前空間：パス プレフィックスは、RFC 7951 で定義されている YANG モジュール名を使用します。

  RFC 7951 で指定された値のプレフィックスは、YANG モジュール名を使用します。

  値のプレフィックスは、選択されたパス プレフィックスの名前空間の影響を受けません。次に、RFC 7951 で指定された値のプレフィックスの例を示します。

  val {
  	  json_ietf_val:"{
  	    "openconfig-interfaces:config": {
  	      “openconfig-interfaces:description":
  	        “DESCRIPTION”
  	    }
  	  }"
  	}
  

  RFC 7951 で指定された名前空間プレフィックスは、YANG モジュール名も使用します。たとえば、ループバック インターフェイスへの openconfig パスは次のようになります。

  /openconfig-interfaces:interfaces/interface[name=Loopback111]/
  
  

  次の例は、RFC 7951 の名前空間指定を使用した gNMI パスを示しています。

  path {
    origin: “rfc7951"
    elem {
      name: "openconfig-interface:interfaces"
    }
    elem {
      name: "interface"
      key {
        key: "name"
        value: "Loopback111"
      }
    }
  }
  

• openconfig：パスプレフィックスを使用しません。これらは openconfig モデルへのパスでのみ使用できます。

  openconfig 名前空間プレフィックスの動作は、発信元または名前空間が指定されていない場合と同じです。たとえば、ループバック インターフェイスへの openconfig パスは次のようになります。

  /interfaces/interface[name=Loopback111]/

  次の例は、openconfig 名前空間指定を使用した gNMI パスを示しています。

  path {
    origin: “openconfig"
    elem {
      name: "interfaces"
    }
    elem {
      name: "interface"
      key {
        key: "name"
        value: "Loopback111"
      }
    }
  }
  

• 空：openconfig プレフィックスと同じです。これがデフォルトです。

  次の例は、空の openconfig 名前空間指定を使用した gNMI パスを示しています。

  path {
  elem {
      name: "interfaces"
    }
    elem {
      name: "interface"
      key {
        key: "name"
        value: "Loopback111"
      }
    }
  }
  

ここでは、Cisco IOS XE Gibraltar 16.10.1 より前のリリースで使用されるパス プレフィックスについて説明します。

/oc-if:interfaces/interface[name=Loopback111]/

path {
  origin: “legacy"
  elem {
    name: "oc-if:interfaces"
  }
  elem {
    name: "interface"
    key {
      key: "name"
      value: "Loopback111"
    }
  }
}

gNMI プロトコルは、Get パスのワイルドカードをサポートしています。これは、複数の要素を一致させるためにパス内でワイルドカードを使用する機能です。これらのワイルドカードは、スキーマ内の指定されたサブツリーにあるすべての要素を示します。

elem は要素であり、xPath 内の / 文字の間の値です。elem は gNMI パスでも使用できます。たとえば、 elem 名を基準とするワイルドカードの位置は、ワイルドカードがインターフェイスを表し、すべてのインターフェイスとして解釈されることを暗に意味します。

ワイルドカードには暗黙的と明示的の 2 つのタイプがあり、どちらもサポートされています。Get パスは、パス ワイルドカードのすべてのタイプと組み合わせをサポートします。

• 暗黙的なワイルドカード：これらは、要素ツリー内の要素のリストを展開します。暗黙的なワイルドカードは、リストの要素にキー値が指定されていない場合に出現します。

  次に、パスの暗黙的なワイルドカードの例を示します。このワイルドカードは、デバイスにあるすべてのインターフェイスの説明を返します。

  path {
    elem {
      name: "interfaces"
    }
    elem {
      name: "interface"
    }
    elem {
      name: "config"
    }
    elem {
      name: "description"
    }
  }
  

• 明示的なワイルドカード：下記の指定によって同じ機能を提供します。

  • パス要素名またはキー名のいずれかにアスタリスク（*）を指定します。

    次に、パスのアスタリスクワイルドカードをキー名として使用する例を示します。このワイルドカードは、デバイスにあるすべてのインターフェイスの説明を返します。

    path {
      elem {
        name: "interfaces"
      }
      elem {
        name: "interface"
        key {
         key: "name"
          value: "*"
        }
      }
      elem {
        name: “config"
      }
      elem {
        name: "description"
      }
    }
    

    次に、パスのアスタリスク ワイルドカードをパス名として使用する例を示します。このワイルドカードは、Loopback111 インターフェイスで使用可能なすべての要素の説明を返します。

    path {
      elem {
        name: "interfaces"
      }
      elem {
        name: "interface"
        key {
          key: "name"
          value: "Loopback111"
        }
      }
       elem {
        name: "*"
      }
      elem {
        name: "description"
      }
    }
    

  • 要素名として省略記号（...）または空のエントリを指定します。これらのワイルドカードは、パス内の複数の要素に展開できます。

    次に、パスの省略記号ワイルドカードの例を示します。このワイルドカードは、/interfaces 配下で使用可能なすべての説明フィールドを返します。

    path {
      elem {
        name: "interfaces"
      }
      elem {
        name: "..."
      }
      elem {
        name: "description"
      }
    }
    

次に、暗黙的なワイルドカードを使用した GetRequest の例を示します。この GetRequest は、デバイスにあるすべてのインターフェイスの oper-status を返します。

path {
  elem {
    name: "interfaces"
    }
  elem {
    name: "interface"
  }
  elem {
    name: "state"
  }
  elem {
    name: "oper-status"
  }
},
type: 0,
encoding: 4

次に、暗黙的なワイルドカードを使用した GetResponse の例を示します。

notification {
  timestamp: 1520627877608777450
  update {
    path {
      elem {
        name: "interfaces"
      }
      elem {
        name: "interface"
        key {
          key: "name"
          value: "\"FortyGigabitEthernet1/1/1\""
        }
      }
      elem {
        name: "state"
}
      elem {
        name: "oper-status"
      }
    }
    val {
      json_ietf_val: "\"LOWER_LAYER_DOWN\""
    }
  },

<snip>
…
</snip>

update {
    path {
      elem {
        name: "interfaces"
      }
      elem {
        name: "interface"
        key {
          key: "name"
          value: "\"Vlan1\""
        }
      }
      elem {
        name: "state"
      }
      elem {
        name: "oper-status"
      }
    }
    val {
      json_ietf_val: "\"DOWN\""
    }
  }
}

ユーザログイン情報、ユーザ名、およびパスワードは、各 gNMI RPC でメタデータとして承認を提供します。次に、ユーザ名とパスワードを使用するサンプル gNMI 機能 RPC を示します。

metadata = [('username','admin'), ('password','lab')]  
cap_request = gnmi_pb2.CapabilityRequest() 
# pass metadata to the gnmi_pb2_grpc.gNMIStub object  
secure_stub.Capabilities(cap_request, metadata=metadata)

エラーが発生すると、gNMI は説明的なエラー メッセージを返します。次のセクションでは gNMI エラー メッセージをいくつか示します。

次に、パスが無効な場合に表示されるエラー メッセージの例を示します。

gNMI Error Response:
  <_Rendezvous of RPC that terminated with (StatusCode.TERMINATED, 
   An error occurred while parsing provided xpath: unknown tag: 
   “someinvalidxpath" Additional information: badly formatted or nonexistent path)>

次に、非実装エラーが発生した場合に表示されるエラー メッセージの例を示します。

gNMI Error Response:
  <_Rendezvous of RPC that terminated with (StatusCode.UNIMPLEMENTED, 
    Requested encoding "ASCII" not supported)>

次に、データ要素が空の場合に表示されるエラー メッセージの例を示します。

gNMI Error Response:
  <_Rendezvous of RPC that terminated with (StatusCode.NOT_FOUND, 
   Empty set returned for path "/oc-if:interfaces/noinfohere")>

証明書とトラストポイントは、セキュア gNMI サーバにのみ必要です。

# Setting up a CA
openssl genrsa -out rootCA.key 2048
openssl req -subj /C=/ST=/L=/O=/CN=rootCA -x509 -new -nodes -key rootCA.key -sha256 -out rootCA.pem
 
# Setting up device cert and key
openssl genrsa -out device.key 2048
openssl req -subj /C=/ST=/L=/O=/CN=<hostnameFQDN> -new -key device.key -out device.csr
openssl x509 -req -in device.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out device.crt -sha256
# Encrpyt device key - needed for input to IOS
openssl rsa -des3 -in device.key -out device.des3.key -passout pass:<password - remember this for later>
 
# Setting up client cert and key
openssl genrsa -out client.key 2048
openssl req -subj /C=/ST=/L=/O=/CN=gnmi_client -new -key client.key -out client.csr
openssl x509 -req -in client.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out client.crt -sha256

次の例は、デバイスに証明書をインストールする方法を示しています。

# Send:
Device# configure terminal
Device(config)# crypto pki import trustpoint1 pem terminal password password1 
 
# Receive:
% Enter PEM-formatted CA certificate.
% End with a blank line or "quit" on a line by itself.
 
# Send:
# Contents of rootCA.pem, followed by newline + 'quit' + newline:
-----BEGIN CERTIFICATE-----
<snip>
-----END CERTIFICATE-----
quit
 
# Receive:
% Enter PEM-formatted encrypted private General Purpose key.
% End with "quit" on a line by itself.
 
# Send:
# Contents of device.des3.key, followed by newline + 'quit' + newline:
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,D954FF9E43F1BA20
<snip>
-----END RSA PRIVATE KEY-----
quit
 
# Receive:
% Enter PEM-formatted General Purpose certificate.
% End with a blank line or "quit" on a line by itself.
 
# Send:
# Contents of device.crt, followed by newline + 'quit' + newline:
-----BEGIN CERTIFICATE-----
<snip>
-----END CERTIFICATE-----
quit
 
# Receive:
% PEM files import succeeded.
Device(config)#
 
# Send:
Device(config)# crypto pki trustpoint trustpoint1
Device(ca-trustpoint)# revocation-check none
Device(ca-trustpoint)# end
Device#

以前に設定したクライアント証明書とルート証明書を使用して gNMI クライアントが接続されます。

# gRPC Must be compiled in local dir under path below:
>>> import sys
>>> sys.path.insert(0, "reference/rpc/gnmi/")
>>> import grpc
>>> import gnmi_pb2
>>> import gnmi_pb2_grpc
>>> gnmi_dir = '/path/to/where/openssl/creds/were/generated/'
 
# Certs must be read in as bytes
>>> with open(gnmi_dir + 'rootCA.pem', 'rb') as f:
>>>     ca_cert = f.read()
>>> with open(gnmi_dir + 'client.crt', 'rb') as f:
>>>     client_cert = f.read()
>>> with open(gnmi_dir + 'client.key', 'rb') as f:
>>>     client_key = f.read()
 
# Create credentials object
>>> credentials = grpc.ssl_channel_credentials(root_certificates=ca_cert, private_key=client_key, certificate_chain=client_cert)
 
# Create a secure channel:
# Default port is 50051, can be changed on ios device with 'gnmi-yang secure-port ####'
>>> port = 50051
>>> host = <HOSTNAME FQDN>
>>> secure_channel = grpc.secure_channel("%s:%d" % (host, port), credentials)
 
# Create secure stub:
>>> secure_stub = gnmi_pb2_grpc.gNMIStub(secure_channel)
 
# Done! Let's test to make sure it works:
>>> secure_stub.Capabilities(gnmi_pb2.CapabilityRequest())
supported_models {
<snip>
}
supported_encodings: <snip>
gNMI_version: "0.4.0"