JunosデバイスのYANGメタデータの注釈
概要 Junosデバイスは、メタデータの注釈を定義するYANG拡張機能をサポートしています。
JunosデバイスはYANG拡張をサポートし、YANGデータノードのインスタンスにメタデータに注釈を付けます。サポートされているデバイスでは、以下の拡張機能を使用できます。
-
junos-configuration-metadata—特定の設定操作の実行に使用できるジュニパーの注釈。 -
openconfig-metadata-OpenConfig 作業グループによって定義された注釈。
YANGメタデータのアノテーションとそれに対応するJSONおよびXMLエンコーディングは、RFC 7952の 「YANGによるメタデータの定義と使用」で定義されています。モジュールは ietf-yang-metadata YANG 拡張 annotationを定義します。
YANGメタデータの注釈は、 設定モードコマンドを使用 annotate するなどして、設定に含まれるコメントであるJunos設定注釈と混乱させるべきではありません。
junos 構成メタデータ モジュールの概要
ジュニパーネットワークス junos-configuration-metadata モジュールは、Junos設定で特定の操作を実行できるメタデータの注釈を定義します。
user@host> show system schema module junos-configuration-metadata output-directory /var/tmp
user@host> file show /var/tmp/junos-configuration-metadata.yang
/*
* junos-configuration-metadata.yang -- Defines annotations (RFC 7952) for
* Junos configuration metadata operations.
*
* Copyright (c) 2021, Juniper Networks, Inc.
* All rights reserved.
*/
module junos-configuration-metadata {
namespace "http://yang.juniper.net/junos/jcmd";
prefix "jcmd";
import ietf-yang-metadata {
prefix "md";
}
organization
"Juniper Networks, Inc.";
contact
"yang-support@juniper.net";
description
"This Yang module defines annotations (RFC 7951) for Junos configuration
metadata operations.";
revision 2021-09-01 {
description
"Initial version.";
}
md:annotation active {
type boolean;
description
"This annotation can be used in configuration XML/JSON to
deactivate/activate a configuration element. Specifying the value
'false' deactivates the configuration element. Specifying the
value 'true' activates the configuration element. When the
configuration element is deactivated and committed, the element
remains in the configuration, but the element does not affect the
functioning of the device.";
}
md:annotation protect {
type boolean;
description
"This annotation can be used in configuration XML/JSON to
protect/unprotect the configuration hierarchies and statements.
Specifying the value 'true' protects the configuration
hierarchy/statement. Specifying the value 'false' unprotects the
configuration hiearchy/statement. The protect operation
prevents changes to selected (protected) configuration hierarchies
and statements.";
}
md:annotation comment {
type string;
description
"This annotation must be used in configuration XML/JSON to
add comments to a configuration element. To remove the existing
comment, empty string has to be supplied as a value for this
annotation.";
}
}
注釈をサポートするデバイスは、 junos-configuration-metadata NETCONF 機能交換で次の機能をアドバタイズします。
<capability>http://yang.juniper.net/junos/jcmd?module=junos-configuration-metadata&revision=2021-09-01</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-yang-metadata?module=ietf-yang-metadata&revision=2016-08-05</capability>
表 1 は、注釈の概要を junos-configuration-metadata 示しています。アノテーションは、名前空間の http://yang.juniper.net/junos/jcmd URI と名前空間のプレフィックスを jcmd 使用します。
| アノテーション | 値 | の説明 |
|---|---|---|
active |
|
指定された設定ステートメントを無効にします。ステートメントは設定に残りますが、デバイスの動作には影響しません。 |
true |
指定された設定ステートメントをアクティブにします。以前に無効化されたステートメントをアクティブにするには、この注釈を使用します。 |
|
comment |
string |
指定された設定ステートメントに関する追加情報を含むコメントを追加するか、値を空の文字列("")に設定して既存のコメントを削除します。 |
protect |
false |
以前に適用 |
true |
状態が削除されるまで、指定されたステートメントに今後の変更を |
設定データでの注釈の使用junos-configuration-metadata
YANG準拠の junos-configuration-metadata NETCONFセッションで注釈を使用して、設定上の特定のメタデータ操作を実行できます。サポートされる操作には、以下のセクションで説明するように、設定へのコメントの追加、設定階層とステートメントの無効化またはアクティブ化、設定階層とステートメントの保護が含まれます。
コンテナ(ステートメント階層)、リーフリスト、リーフステートメント、またはリストアイテム(識別子を持つステートメント)にアノテーションを適用 junos-configuration-metadata できます。リーフリストステートメントに注釈を適用する場合、個別のリーフリストエントリーではなく、リーフリストレベルでのみ適用できます。
表 2 で説明したように、YANG アノテーションは JSON または XML 設定データで使用できます。NETCONF <edit-config> 操作を使用して XML 構成データを読み込み、Junos XML プロトコル<load-configuration>操作を使用して、デバイス上の JSON または XML 構成データを読み込むことができます。
| エンコード | 構文の | 例 |
|---|---|---|
| JSON(メタデータオブジェクト) |
"module-name:annotation" : ""value |
|
| XML(XML 属性) |
|
|
コンフィギュレーションにコメントを追加する
アノテーションを使用して、 comment コンフィギュレーション・ステートメントにコメントを追加することができます。以下のセクションでは、JSON または XML 構成データを読み込む際にコメントを追加する方法について概要を説明します。
Json
JSON設定データを読み込む際にコメントを追加するには、そのステートメントの junos-configuration-metadata:comment メタデータオブジェクトにアノテーションを含め、コメントを文字列として指定します。コメントを削除するには、空の文字列("")を含めます。
以下の例では、1つのコメントを階層に関連付け、別のコメントを識別子を必要とするリストエントリーに関連付け、3番目のコメントを既存のリーフステートメントに関連付けます。
<rpc>
<load-configuration format="json">
<configuration-json>
{
"configuration" : {
"protocols" : {
"ospf" : {
"@" : {
"junos-configuration-metadata:comment" : "/* OSPF comment */"
},
"area" : [
{
"name" : "0.0.0.0",
"interface" : [
{
"@" : {
"junos-configuration-metadata:comment" : "/* From jnpr1 \n to jnpr2 */"
},
"name" : "et-0/0/1.0",
"@hello-interval" : {
"junos-configuration-metadata:comment" : "# set by admin"
}
}
]
}
]
}
}
}
}
</configuration-json>
</load-configuration>
</rpc>
]]>]]>
Xml
XML 設定データを読み込む際にコメントを追加するには、その構成要素の jcmd:comment 開始タグにアノテーションを XML 属性として含め、そのコメントを文字列として指定します。コメントを削除するには、空の文字列("")を含めます。
以下の例では、1つのコメントを階層に関連付け、別のコメントを識別子を必要とするリストエントリーに関連付け、3つ目のコメントをリーフステートメントに関連付けます。
<rpc>
<edit-config>
<target>
<candidate/>
</target>
<config>
<configuration>
<protocols>
<ospf xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:comment="/* OSPF comment */">
<area>
<name>0.0.0.0</name>
<interface xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:comment="/* From jnpr1 \n to jnpr2 */">
<name>et-0/0/1.0</name>
<hello-interval xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:comment="# set by admin">5</hello-interval>
</interface>
</area>
</ospf>
</protocols>
</configuration>
</config>
</edit-config>
</rpc>
コンフィギュレーション・ステートメントのアクティブ化または無効化
アノテーションを active 使用して、コンフィギュレーション・ステートメントを非アクティブにしたり、以前に無効化されたコンフィギュレーション・ステートメントをアクティブにすることができます。ステートメントを無効にするには、 を に設定 active します false。ステートメントをアクティブにするには、 を に設定 active します true。
以下のセクションでは、JSONおよびXML設定データで設定ステートメントを無効化およびアクティブ化する方法について概要を説明します。
Json
JSONの設定オブジェクトを無効化または再有効化するには、そのステートメントの "junos-configuration-metadata:active" : (false | true) メタデータオブジェクトにアノテーションを含めます。
<configuration-json>
{
"configuration" : {
/* JSON objects for parent levels */
"@leaf-list-statement-name" : {
"junos-configuration-metadata:comment" : "/* activate or deactivate a leaf-list */",
"junos-configuration-metadata:active" : (false | true)
},
"level-or-container" : {
"@" : {
"junos-configuration-metadata:comment" : "/* activate or deactivate a hierarchy */",
"junos-configuration-metadata:active" : (false | true)
},
"object" : [
{
"@" : {
"junos-configuration-metadata:comment" : "/* activate or deactivate an object with an identifier */",
"junos-configuration-metadata:active" : (false | true)
},
"name" : "identifier",
"@statement-name" : {
"junos-configuration-metadata:comment" : "/* activate or deactivate a statement */",
"junos-configuration-metadata:active" : (false | true)
}
}
]
}
/* closing braces for parent levels */
}
}
</configuration-json>
例えば、以下の RPC は階層を [edit protocols isis] 非アクティブ化し、リーフリスト ステートメントを apply-groups アクティブ化し、指定されたイベント ポリシーを変更してイベント スクリプト アクションを無効化し、raise-trap アクションを再有効化します。
<rpc>
<load-configuration format="json">
<configuration-json>
{
"configuration" : {
"@apply-groups" : {
"junos-configuration-metadata:active" : true
},
"protocols" : {
"isis" : {
"@" : {
"junos-configuration-metadata:active" : false
}
}
},
"event-options" : {
"policy" : [
{
"name" : "raise-trap-on-ospf-nbrdown",
"then" : {
"event-script" : [
{
"@" : {
"junos-configuration-metadata:active" : false
},
"name" : "ospf.xsl"
}
],
"@raise-trap" : {
"junos-configuration-metadata:active" : true
}
}
}
]
}
}
}
</configuration-json>
</load-configuration>
</rpc>
Xml
設定オブジェクトを無効化または再有効化するには、その構成要素の jcmd:active="false" 開始タグに それぞれ または jcmd:active="true" アノテーションを XML 属性として含めます。
以下の RPC は階層を [edit protocols isis] 非アクティブ化し、リーフリスト ステートメントを apply-groups アクティブ化し、指定されたイベント ポリシーを変更してイベント スクリプト アクションを無効化し、raise-trap アクションを再有効化します。
<rpc>
<edit-config>
<target>
<candidate/>
</target>
<config>
<configuration>
<apply-groups xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:active="true"/>
<protocols>
<isis xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:active="false"/>
</protocols>
<event-options>
<policy>
<name>raise-trap-on-ospf-nbrdown</name>
<then>
<event-script xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:active="false">
<name>ospf.xsl</name>
</event-script>
<raise-trap xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:active="true"/>
</then>
</policy>
</event-options>
</configuration>
</config>
</edit-config>
</rpc>
保護または保護対策の設定ステートメント
選択した Junos 設定階層とステートメントを保護し、保護属性が削除されるまでステートメントの変更を防ぐことができます。
以下のセクションでは、JSON および XML 設定データにおける保護または保護対策の設定ステートメントの方法について概要を説明します。
Json
JSON の設定オブジェクトの保護または保護保護対策を行う場合は、そのステートメントの "junos-configuration-metadata:protect" : (true | false) メタデータ オブジェクトにアノテーションを含めます。
<configuration-json>
{
"configuration" : {
/* JSON objects for parent hierarchies */
"@leaf-list-statement-name" : {
"junos-configuration-metadata:comment" : "/* protect a leaf-list */",
"junos-configuration-metadata:protect" : (false | true)
},
"hierarchy" : {
"@" : {
"junos-configuration-metadata:comment" : "/* protect a hierarchy */",
"junos-configuration-metadata:protect" : (false | true)
},
"object" : [
{
"@" : {
"junos-configuration-metadata:comment" : "/* protect an object with an identifier */",
"junos-configuration-metadata:protect" : (false | true)
},
"name" : "identifier",
"@statement-name" : {
"junos-configuration-metadata:comment" : "/* protect a statement */",
"junos-configuration-metadata:protect" : (false | true)
}
}
]
}
/* closing braces for parent hierarchies */
}
}
</configuration-json>
たとえば、以下の RPC は、階層レベル、apply-groupsリーフリスト ステートメント、リーフ ステートメントをhost-name保護[edit protocols isis]し、指定されたイベント ポリシーの保護属性を削除します。
<rpc>
<load-configuration format="json">
<configuration-json>
{
"configuration" : {
"@apply-groups" : {
"junos-configuration-metadata:protect" : true
},
"system" : {
"@host-name" : {
"junos-configuration-metadata:protect" : true
}
},
"event-options" : {
"policy" : [
{
"@" : {
"junos-configuration-metadata:protect" : false
},
"name" : "raise-trap-on-ospf-nbrdown"
}
]
},
"protocols" : {
"isis" : {
"@" : {
"junos-configuration-metadata:protect" : true
}
}
}
}
}
</configuration-json>
</load-configuration>
</rpc>
Xml
構成オブジェクトの保護または保護保護を行うために、その構成要素の jcmd:protect="true" 開始タグに それぞれ または jcmd:protect="false" のアノテーションを XML 属性として含めます。
以下の RPC は、階層レベル、apply-groupsリーフリスト ステートメント、リーフ ステートメントをhost-name保護[edit protocols isis]し、指定されたイベント ポリシーの保護属性を削除します。
<rpc>
<edit-config>
<target>
<candidate/>
</target>
<config>
<configuration>
<apply-groups xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:protect="true"/>
<system>
<host-name xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:protect="true"/>
</system>
<protocols>
<isis xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:protect="true"/>
</protocols>
<event-options>
<policy xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:protect="false">
<name>raise-trap-on-ospf-nbrdown</name>
</policy>
</event-options>
</configuration>
</config>
</edit-config>
</rpc>
openconfig-metadata モジュールの概要
openconfig-metadata YANG モジュールには、OpenConfig 作業グループによって定義されたメタデータ注釈が含まれています。モジュールはアノテーションをprotobuf-metadata定義します。これにより、コンフィギュレーションに関するメタデータをコンフィギュレーション内に直接保存して、簡単に参照することができます。
Junosデバイスは、以下の openconfig-metadata:protobuf-metadata 制約を持つアノテーションをサポートしています。
-
アノテーションは 1 つだけ
protobuf-metadata、設定階層のルート レベルでのみ設定できます。 -
JSON 設定データでのみアノテーションを設定および表示できます。
-
アノテーションはバイナリ型ですが、デバイスにアノテーションを読み込む前に、base64エンコード方式でバイナリ値をエンコードする必要があります。
Junosデバイスは、デフォルトでアノテーションの設定を openconfig-metadata:protobuf-metadata サポートしています。ただし、デバイスが NETCONF 機能の機能を交換して設定データに出力できるようにするには、デバイスを次のように設定する必要があります。
-
NETCONF サーバーは、機能交換で OpenConfig モジュールなどの標準 YANG モジュールをアドバタイズする必要があります。
[edit] user@host# set system services netconf hello-message yang-module-capabilities advertise-standard-yang-modules
-
デバイスを設定して、YANG準拠のNETCONFセッションを適用します。
[edit] user@host# set system services netconf yang-compliant
-
(オプション)CLI で注釈を含む OpenConfig ステートメントを表示する場合は、OpenConfig スキーマを非表示にします。
[edit] user@host# set system schema openconfig unhide
-
設定をコミットします。
[edit] user@host# commit
NETCONF 機能交換で標準 YANG モジュールをアドバタイズするようにデバイスを設定した後、注釈をサポート openconfig-metadata するデバイスはメッセージ内で次の機能を hello アドバタイズします。
<capability>http://openconfig.net/yang/openconfig-metadata?module=openconfig-metadata&revision=2020-08-06</capability>
gNMI set() 操作を使用して、JSON 構成データの openconfig-metadata:protobuf-metadata 一部としてアノテーションを読み込みます。
{
"configuration" : {
"@" : {
"openconfig-metadata:protobuf-metadata": "dGhpcyBpcyB0ZXN0IGRhdGEK" // base64 encoded string per RFC 7951 encoding rules.
},
// configuration statements
}
}
[構成データの メタデータの注釈を表示] の説明に従って JSON 構成データを要求すると、Junos 構成データの後に、アノテーションを含む OpenConfig 構成が出力されます。例えば：
<rpc><get-configuration format="json"/></rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/22.3R1/junos">
{
"configuration" : {
"@" : {
"xmlns" : "http://xml.juniper.net/xnm/1.1/xnm",
"junos:changed-seconds" : "1658526284",
"junos:changed-localtime" : "2022-07-22 14:44:44 PDT"
},
"version" : "22.3R1-EVO",
...
},
"@" : {
"openconfig-metadata:protobuf-metadata" : "dGhpcyBpcyB0ZXN0IGRhdGEK"
},
"openconfig-interfaces:interfaces" : {
"interface" : [
{
"name" : "et-1/0/1",
"config" : {
"type" : "IF_ETHERNET",
"description" : "CE1"
}
}
]
}
}
</rpc-reply>
構成データでのメタデータの注釈の表示
Junos デバイスは、YANG に準拠した NETCONF セッション内の Junos 設定で YANG メタデータの注釈を出力します。NETCONF セッションを YANG に準拠するように設定し、 または <get-configuration/> RPC を使用して<get-config/>設定を取得すると、デバイスは RFC 7952、 YANG によるメタデータの定義と使用に従ってアノテーションをエンコードします。
RFC 7952に従ってエンコードされたYANG注釈を使用して設定を表示するには: