RFC 8529
YANG Data Model for Network Instances
Internet Engineering Task Force (IETF) 💖
RFC 8529: YANG Data Model for Network Instances ✨
Okay so, bestie, let's get the title block sorted first 🎀. This one was written by L. Berger (LabN Consulting), C. Hopps (LabN Consulting), A. Lindem (Cisco Systems), D. Bogdanovic (Volta Networks), and X. Liu (Volta Networks) 👑. It's dated March 2019 📅 and it's a Standards Track doc, so it's the real deal 🔥. The ISSN is 2070-1721 🌸.
It doesn't obsolete anything and doesn't update anything either, so it's a fresh start 🦋. It's the second of two modules in the family, and it's all about VRFs and VSIs 💅.
Abstract 🌈
Okay so this doc defines a network instance module 🧚. You can use it to manage the virtual resource partitioning that can show up on a network device 💜. Common industry names for this are VPN Routing and Forwarding (VRF) instances and Virtual Switch Instances (VSIs) ✨.
The YANG data model in here conforms to the Network Management Datastore Architecture (NMDA) defined in RFC 8342 🫶.
Status of This Memo 📜
This is an Internet Standards Track document 💅.
It's a product of the Internet Engineering Task Force (IETF) 🌈. It represents the consensus of the IETF community 🫶. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 👑. If you want more info on Internet Standards, check out Section 2 of RFC 7841 🎀.
For the current status, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc8529 🦋.
Copyright Notice ©️
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved 💖.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stood on the date of publication 📚. Please read these carefully, bestie, because they spell out your rights and restrictions 🙈. Code Components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 💀.
Table of Contents 🗂️
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Network Instances . . . . . . . . . . . . . . . . . . . . . . 6
3.1. NI Types and Mount Points . . . . . . . . . . . . . . . . 7
3.1.1. Well-Known Mount Points . . . . . . . . . . . . . . . 8
3.1.2. NI Type Example . . . . . . . . . . . . . . . . . . . 9
3.2. NIs and Interfaces . . . . . . . . . . . . . . . . . . . 9
3.3. Network Instance Management . . . . . . . . . . . . . . . 11
3.4. Network Instance Instantiation . . . . . . . . . . . . . 14
4. Security Considerations . . . . . . . . . . . . . . . . . . . 14
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
6. Network Instance Model . . . . . . . . . . . . . . . . . . . 16
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.1. Normative References . . . . . . . . . . . . . . . . . . 22
7.2. Informative References . . . . . . . . . . . . . . . . . 23
Appendix A. Example NI Usage . . . . . . . . . . . . . . . . . . 25
A.1. Configuration Data . . . . . . . . . . . . . . . . . . . 25
A.2. State Data - Non-NMDA Version . . . . . . . . . . . . . . 28
A.3. State Data - NMDA Version . . . . . . . . . . . . . . . . 35
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 44
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 441. Introduction 🌸
Okay so this doc defines the second of two new modules made to support configuring and running network devices that can partition their resources, from a management view, a networking view, or both 🎀. Both of them use the YANG functionality that YANG Schema Mount [RFC8528] unlocks ✨.
The YANG data model in this document conforms to the Network Management Datastore Architecture defined in [RFC8342] 💅.
The first kind of resource partitioning is a logical split of a network device, where each slice is managed as basically its own independent network element that's "hosted" by the base device 🧚. These hosted elements are called logical network elements, or LNEs, and they're supported by the logical-network-element module from [RFC8530] 💜. That module identifies LNEs and links resources from the device to each one 🫶. LNEs show up in YANG as independent network devices, and each one gets accessed on its own 👑. Vendors call an LNE things like a logical system, logical router, virtual switch, chassis, or fabric 🌈.
The second kind, which is what this doc is about, supports what people usually call VPN Routing and Forwarding (VRF) instances and Virtual Switch Instances (VSI) 🦋; see [RFC4026] and [RFC4664] 🙈. Here, several control-plane and forwarding/bridging instances are provided by and managed through one single network device, whether physical or logical 💖. This kind is called a Network Instance (NI), and the network instance module below supports it 🔥. Configuring and operating each network instance always goes through the network device and the network instance module 💅.
The big difference between the LNE model and the NI model is that the NI model gives you a framework for VRF and VSI management 🎀. This doc expects separate models for VRF and VSI tech, meaning L3 and L2 VPN stuff 🌸. You can see an example of one in the emerging L3VPN model from [YANG-L3VPN] and in the examples below ✨.
1.1. Terminology 📖
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 💜.
Readers are expected to already know the terms and concepts of YANG [RFC7950] and YANG Schema Mount [RFC8528] 🫶.
This document uses the graphical representation of data models defined in [RFC8340] 🌈.
2. Overview 🧚
Okay so this doc looks at network devices that support protocols and functions defined within the IETF, like routers, firewalls, and hosts 👑. These devices can be physical or virtual, like a classic router with custom hardware, or one living inside a server-based virtual machine running a virtual network function (VNF) 💅. Each device can split its resources into logical network elements (LNEs), and each LNE is a managed logical device 🦋. Vendors call an LNE things like a logical system, logical router, virtual switch, chassis, or fabric 🌸. Each LNE can also support VRF and VSI functions, which get called network instances (NIs) from here on 💖. Figure 1 shows the whole picture 🎀.
,''''''''''''''''''''''''''''''''''''''''''''''`.
| Network Device (Physical or Virtual) |
| ..................... ..................... |
| : Logical Network : : Logical Network : |
| : Element : : Element : |
| :+-----+-----+-----+: :+-----+-----+-----+: |
| :| Net | Net | Net |: :| Net | Net | Net |: |
| :|Inst.|Inst.|Inst.|: :|Inst.|Inst.|Inst.|: |
| :+-----+-----+-----+: :+-----+-----+-----+: |
| : | | | | | | : : | | | | | | : |
| :..|.|...|.|...|.|..: :..|.|...|.|...|.|..: |
| | | | | | | | | | | | | |
`'''|'|'''|'|'''|'|'''''''''|'|'''|'|'''|'|'''''
| | | | | | | | | | | |
Interfaces Interfaces
Figure 1: Module Element RelationshipsA model for LNEs is described in [RFC8530], and the model for NIs is covered in Section 3 of this document 🧚.
The current interface management model [RFC8343] is affected by the definition of LNEs and NIs 🌈. This document and [RFC8530] define augmentations to the interface module to support LNEs and NIs 💅.
The network instance model supports configuring VRFs and VSIs 🦋. Each instance is backed by information about the device, like the route target used when advertising VRF routes through the mechanisms defined in [RFC4364] 💜, plus information about how the NI runs internally, like routing protocols [RFC8349] and OSPF [YANG-OSPF] 🫶. This document defines the network instance module that gives you a base for managing both kinds of information ✨.
NI information about the device, including which interfaces are assigned to which NIs, is defined as part of this document 🎀. The module also has a placeholder for NI-technology-specific information, both at the device level and for how the NI runs internally 🌸. Information about NI internal operation is supported through schema mount [RFC8528], by mounting the appropriate modules under the mount point 👑. Well-known mount points are defined for L3VPN, L2VPN, and L2+L3VPN NI types 🔥.
Part 1 of 7. More parts are coming, so stay tuned, bestie 💖🧚
3. Network Instances ✨
okay bestie, the network instance container 💖 is where VRFs and VSIs live! 🦋 VRFs and VSIs are the go-to for isolating routing and switching domains. Think virtual private networks, each with its own active protocols and its own routing/switching policies 💅. The model covers both core/provider and virtual instances. Core/provider instance info sits at the top level of the server, and virtual instance info lives under the root schema mount points 🌸.
module: ietf-network-instance
+--rw network-instances
+--rw network-instance* [name]
+--rw name string
+--rw enabled? boolean
+--rw description? string
+--rw (ni-type)?
+--rw (root-type)
+--:(vrf-root)
| +--mp vrf-root
+--:(vsi-root)
| +--mp vsi-root
+--:(vv-root)
+--mp vv-root
augment /if:interfaces/if:interface:
+--rw bind-ni-name? -> /network-instances/network-instance/name
augment /if:interfaces/if:interface/ip:ipv4:
+--rw bind-ni-name? -> /network-instances/network-instance/name
augment /if:interfaces/if:interface/ip:ipv6:
+--rw bind-ni-name? -> /network-instances/network-instance/name
notifications:
+---n bind-ni-name-failed
+--ro name -> /if:interfaces/interface/name
+--ro interface
| +--ro bind-ni-name?
| -> /if:interfaces/interface/ni:bind-ni-name
+--ro ipv4
| +--ro bind-ni-name?
| -> /if:interfaces/interface/ip:ipv4/ni:bind-ni-name
+--ro ipv6
| +--ro bind-ni-name?
| -> /if:interfaces/interface/ip:ipv6/ni:bind-ni-name
+--ro error-info? stringA network instance is identified by a name string 🎀. This string works both as an index within the network instance module and as the way to link resources to a network instance, as you can see in the interface augmentation above. The ni-type and root-type choice statements are what let us support different types of L2 and L3 VPN technologies 🧚. The bind-ni-name-failed notification is used in certain failure cases 😭.
3.1. NI Types and Mount Points
The network instance module is built so that you can define information models for specific types of VRFs and VSIs using augmentations 🌈. For example, the info needed for L2VPN (like VPLS and EVPN) is likely to be super different. Example models under development that could be restructured to take advantage of NIs include models for L3VPNs [YANG-L3VPN] and L2VPNs [YANG-L2VPN] 💜.
Documents that define new YANG data models for specific types of network instances should augment the network instance module 🫶. The basic structure for those augmentations includes a case statement with containers for configuration and state data and, when needed, a type-specific mount point. Generally, NI types are not expected to need their own type-specific mount points. They should instead reuse one of the well-known mount points, which we'll get into in the next section ✨. Here's an example type-specific augmentation:
augment "/ni:network-instances/ni:network-instance/ni:ni-type" {
case l3vpn {
container l3vpn {
...
}
container l3vpn-state {
...
}
}
}3.1.1. Well-Known Mount Points
YANG Schema Mount [RFC8528] identifies mount points by name within a module 🦋. This lets us define mount points whose schema can be shared across NI types. As we said above, NI types mostly differ in the configuration info needed in the core/top-level instance to support the NI, not in the info represented within an NI. So it makes sense to share mount points across certain NI types 💅.
The expectation is that there are actually very few different schemas that need to be defined to support NIs for an implementation 🌸. Specifically, the following three forms of NI schema are expected to be needed, and each one can be defined with a well-known mount point that future modules defining NI types can reuse 👑.
The three well-known mount points are:
vrf-root: intended for use with L3VPN-type NI types.vsi-root: intended for use with L2VPN-type NI types.vv-root: intended for use with NI types that simultaneously support L2VPN bridging and L3VPN routing capabilities.
Future model definitions should use the mount points above whenever possible 🍓. If a well-known mount point isn't appropriate, a model may define a type-specific mount point via augmentation 🙈.
3.1.2. NI Type Example
Here's an example of an L3VPN VRF using a hypothetical augmentation to the network instance schema defined in [YANG-L3VPN]. More detailed examples can be found in Appendix A 🎀.
module: ietf-network-instance
+--rw network-instances
+--rw network-instance* [name]
+--rw name string
+--rw enabled? boolean
+--rw description? string
+--rw (ni-type)?
| +--:(l3vpn)
| +--rw l3vpn:l3vpn
| | ... // config data
| +--ro l3vpn:l3vpn-state
| | ... // state data
+--rw (root-type)
+--:(vrf-root)
+--mp vrf-root
+--rw rt:routing/
| +--rw router-id? yang:dotted-quad
| +--rw control-plane-protocols
| +--rw control-plane-protocol* [type name]
| +--rw ospf:ospf
| +--rw area* [area-id]
| +--rw interfaces
| +--rw interface* [name]
| +--rw name if:interface-ref
| +--rw cost? uint16
+--ro if:interfaces@
| ...This shows YANG Routing Management [RFC8349] and YANG OSPF [YANG-OSPF] as mounted modules 🧚. The mounted modules can reference interface info through a parent-reference to the containers defined in [RFC8343] 🌈.
3.2. NIs and Interfaces
Interfaces are a crucial part of any network device's configuration and operational state 💖. They usually include a mix of raw physical interfaces, link-layer interfaces, addressing config, and logical interfaces that may not be tied to any physical interface. Several system services and Layer 2 and Layer 3 protocols may also attach config or operational state data to different types of interfaces (these relationships aren't shown, for simplicity). The interface management model is defined by [RFC8343] 🦋.
As shown below, the network instance module augments the existing interface management model by adding a name that's used on interface or sub-interface types to identify an associated network instance ✨. This name is also added for IPv4 and IPv6 types, as defined in [RFC8344] 💜.
Here's an example of envisioned usage. The interfaces container includes a number of commonly used components as examples 🫶:
module: ietf-interfaces
+--rw interfaces
| +--rw interface* [name]
| +--rw name string
| +--rw ip:ipv4!
| | +--rw ip:enabled? boolean
| | +--rw ip:forwarding? boolean
| | +--rw ip:mtu? uint16
| | +--rw ip:address* [ip]
| | | +--rw ip:ip inet:ipv4-address-no-zone
| | | +--rw (ip:subnet)
| | | +--:(ip:prefix-length)
| | | | +--rw ip:prefix-length? uint8
| | | +--:(ip:netmask)
| | | +--rw ip:netmask? yang:dotted-quad
| | +--rw ip:neighbor* [ip]
| | | +--rw ip:ip inet:ipv4-address-no-zone
| | | +--rw ip:link-layer-address yang:phys-address
| | +--rw ni:bind-network-instance-name? string
| +--rw ni:bind-network-instance-name? stringThe "ietf-interfaces" module [RFC8343] is structured to include all interfaces in one flat list, without regard to virtual instances (like VRFs) supported on the device 🌸. The bind-network-instance-name leaf is what links an interface to its associated NI (like a VRF or VSI) 👑. Heads up, though: as currently defined, if you want to assign an interface to both an LNE and an NI, the interface gets assigned to the LNE first, using the mechanisms defined in [RFC8530]. Then, inside that LNE's interface module, the LNE's representation of that interface gets assigned to an NI 🙈.
3.3. Network Instance Management ✨
okay so bestie, this is where we figure out how NI info actually gets organized and who's allowed to touch what 💅 Modules that might represent network instance info are gonna live under the "root" mount point specific to the ni-type 🌸 and to figure out which modules are accessible, the "shared-schema" method from the "ietf-yang-schema-mount" module [RFC8528] MUST be used 🔥 A future version of this doc could relax that requirement, so don't get too attached to it 🥺 Mounted modules SHOULD be defined with access, through the right schema mount parent-references [RFC8528], to device resources like interfaces 🦋 An implementation MAY choose to restrict parent-referenced info so it only relates to one specific instance 💜 For example, it might only allow references to interfaces whose "bind-network-instance-name" is identical to the instance's "name" 🎀
Okay now, all modules that represent control-plane and data-plane info MAY be present at the "root" mount point and accessible through paths modified per [RFC8528] ✨ The list of available modules is expected to be implementation dependent, and so is the method an implementation uses to support NIs 🧚 It's giving "every server does its own thing" energy, iykyk 💀
Here's an example for the NI from Section 3.1.2, to show how the data organization could be defined 🍓
"ietf-yang-schema-mount:schema-mounts": {
"mount-point": [
{
"module": "ietf-network-instance",
"label": "vrf-root",
"shared-schema": {
"parent-reference": [
"/*[namespace-uri() = 'urn:ietf:...:ietf-interfaces']"
]
}
}
]
}So module data identified through ietf-yang-schema-mount gets instantiated under the mount point listed under "mount-point" 🫶 These modules can reference info for nodes in top-level modules listed under "parent-reference" 👑 Parent-referenced info is only available to clients through its top-level paths, NOT under the associated mount point, so don't go looking for it there 🙈
To let a client understand those instance restrictions on parent-referenced info, an implementation MAY show them in the "parent-reference" leaf-list 🌈 For example:
"namespace": [
{
"prefix": "if",
"uri": "urn:ietf:params:xml:ns:yang:ietf-interfaces"
},
{
"prefix": "ni",
"uri": "urn:ietf:params:xml:ns:yang:ietf-network-instance"
}
],
"mount-point": [
{
"module": "ietf-network-instance",
"label": "vrf-root",
"shared-schema": {
"parent-reference": [
"/if:interfaces/if:interface
[ni:bind-network-instance-name = current()/../ni:name]",
"/if:interfaces/if:interface/ip:ipv4
[ni:bind-network-instance-name = current()/../ni:name]",
"/if:interfaces/if:interface/ip:ipv6
[ni:bind-network-instance-name = current()/../ni:name]"
]
}
}
],The same kinds of "parent-reference" restrictions for non-NMDA implementations can be represented based on [RFC8343] and [RFC8344] like this 🦋
"namespace": [
{
"prefix": "if",
"uri": "urn:ietf:params:xml:ns:yang:ietf-interfaces"
},
{
"prefix": "ni",
"uri": "urn:ietf:params:xml:ns:yang:ietf-network-instance"
}
],
"mount-point": [
{
"module": "ietf-network-instance",
"label": "vrf-root",
"shared-schema": {
"parent-reference": [
"/if:interfaces/if:interface
[ni:bind-network-instance-name = current()/../ni:name]",
"/if:interfaces-state/if:interface
[if:name = /if:interfaces/if:interface
[ni:bind-ni-name = current()/../ni:name]/if:name]",
"/if:interfaces/if:interface/ip:ipv4
[ni:bind-network-instance-name = current()/../ni:name]",
"/if:interfaces-state/if:interface/ip:ipv4
[if:name = /if:interfaces/if:interface/ip:ipv4
[ni:bind-ni-name = current()/../ni:name]/if:name]",
"/if:interfaces/if:interface/ip:ipv6
[ni:bind-network-instance-name = current()/../ni:name]",
"/if:interfaces-state/if:interface/ip:ipv6
[if:name = /if:interfaces/if:interface/ip:ipv6
[ni:bind-ni-name = current()/../ni:name]/if:name]"
]
}
}
],3.4. Network Instance Instantiation 🌸
Clients can control NIs with the existing list operations 💖 When a list entry gets created, a new instance is instantiated ✨ The models mounted under an NI root are expected to depend on the server implementation 🎀 And when a list entry is deleted, the existing network instance gets destroyed 💀 For more info, check out Section 7.8.6 of [RFC7950] 📚
Once an NI exists, host network device resources can be associated with it 🦋 As we mentioned before, this doc augments ietf-interfaces with the bind-ni-name leaf so interfaces can be linked up 🔗 When a bind-ni-name is set to a valid NI name, an implementation MUST take whatever internal steps are needed to assign the interface to the NI, OR provide an error message (defined below) saying why the assignment failed 🚨 The assignment can fail while processing the set operation OR after asynchronous processing ⭐ If it's the latter, error notification is supported through a notification 🔔
4. Security Considerations 🔐
Okay this part is SERIOUS bestie, so pay attention 😭 The YANG modules in this doc define a schema for data meant to be accessed via network management protocols like NETCONF [RFC6241] or RESTCONF [RFC8040] 💜 The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242] 🔒 The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446] 🔒
The Network Configuration Access Control Model (NACM) [RFC8341] gives you the tools to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available protocol operations and content 🛡️
There are two different sets of security considerations for this doc 🧐 The first is about info inside mounted modules 🌈 The security considerations for mounted modules are not substantively changed by whether the info is accessed within an NI, so for example, when you look at the modules defined in [RFC8349], the security considerations in that doc apply equally whether those modules are accessed at a server's root or under an NI instance's root node 💅
The second area is the info in the NI module itself 👑 NI info represents network configuration and route distribution policy info, so its security is important 😤 But it's fundamentally no different from any other interface or routing config info already covered in [RFC8343] and [RFC8349] 🫶
The vulnerable "config true" parameters and subtrees are these ones 🚨
/network-instances/network-instance: This list specifies the network instances and the related control plane protocols configured on a device 🌐
/if:interfaces/if:interface/*/bind-network-instance-name: This leaf indicates the NI instance that an interface is assigned to 🦋
Unauthorized access to any of these lists can seriously mess with the routing subsystem of both the local device AND the network 😱 This may lead to network malfunctions, packets getting delivered to inappropriate destinations, and other problems 💀💀
5. IANA Considerations 📋
This doc registers a URI in the "IETF XML Registry" [RFC3688] 🎀
URI: urn:ietf:params:xml:ns:yang:ietf-network-instance
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.This doc also registers a YANG module in the "YANG Module Names" registry [RFC6020] 🌸
name: ietf-network-instance
namespace: urn:ietf:params:xml:ns:yang:ietf-network-instance
prefix: ni
reference: RFC 85296. Network Instance Model ✨
okay so this is where the actual YANG module lives 🎀 it's the full blueprint for network instances (aka VRFs and VSIs 🦋), with the imports, augments, and that bind-ni-name notification all in one place. the whole module is below, copied exactly 💅
<CODE BEGINS> file "ietf-network-instance@2019-01-21.yang"
module ietf-network-instance {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-network-instance";
prefix ni;
// import some basic types
import ietf-interfaces {
prefix if;
reference
"RFC 8343: A YANG Data Model for Interface Management";
}
import ietf-ip {
prefix ip;
reference
"RFC 8344: A YANG Data Model for IP Management";
}
import ietf-yang-schema-mount {
prefix yangmnt;
reference
"RFC 8528: YANG Schema Mount";
}
organization
"IETF Routing Area (rtgwg) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/rtgwg>
WG List: <mailto:rtgwg@ietf.org>
Author: Lou Berger
<mailto:lberger@labn.net>
Author: Christian Hopps
<mailto:chopps@chopps.org>
Author: Acee Lindem
<mailto:acee@cisco.com>
Author: Dean Bogdanovic
<mailto:ivandean@gmail.com>";
description
"This module is used to support multiple network instances
within a single physical or virtual device. Network
instances are commonly known as VRFs (VPN Routing and
Forwarding) and VSIs (Virtual Switching Instances).
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
are to be interpreted as described in BCP 14 (RFC 2119)
(RFC 8174) when, and only when, they appear in all capitals,
as shown here.
Copyright (c) 2019 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD
License set forth in Section 4.c of the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 8529; see
the RFC itself for full legal notices.";
revision 2019-01-21 {
description
"Initial revision.";
reference
"RFC 8529";
}
// top-level device definition statements
container network-instances {
description
"Network instances, each of which consists of
VRFs and/or VSIs.";
reference
"RFC 8349: A YANG Data Model for Routing Management";
list network-instance {
key "name";
description
"List of network instances.";
leaf name {
type string;
mandatory true;
description
"device-scoped identifier for the network
instance.";
}
leaf enabled {
type boolean;
default "true";
description
"Flag indicating whether or not the network
instance is enabled.";
}
leaf description {
type string;
description
"Description of the network instance
and its intended purpose.";
}
choice ni-type {
description
"This node serves as an anchor point for different types
of network instances. Each 'case' is expected to
differ in terms of the information needed in the
parent/core to support the NI and may differ in their
mounted-schema definition. When the mounted schema is
not expected to be the same for a specific type of NI,
a mount point should be defined.";
}
choice root-type {
mandatory true;
description
"Well-known mount points.";
container vrf-root {
description
"Container for mount point.";
yangmnt:mount-point "vrf-root" {
description
"Root for L3VPN-type models. This will typically
not be an inline-type mount point.";
}
}
container vsi-root {
description
"Container for mount point.";
yangmnt:mount-point "vsi-root" {
description
"Root for L2VPN-type models. This will typically
not be an inline-type mount point.";
}
}
container vv-root {
description
"Container for mount point.";
yangmnt:mount-point "vv-root" {
description
"Root models that support both L2VPN-type bridging
and L3VPN-type routing. This will typically
not be an inline-type mount point.";
}
}
}
}
}
// augment statements
augment "/if:interfaces/if:interface" {
description
"Add a node for the identification of the network
instance associated with the information configured
on a interface.
Note that a standard error will be returned if the
identified leafref isn't present. If an interface cannot
be assigned for any other reason, the operation SHALL fail
with an error-tag of 'operation-failed' and an
error-app-tag of 'ni-assignment-failed'. A meaningful
error-info that indicates the source of the assignment
failure SHOULD also be provided.";
leaf bind-ni-name {
type leafref {
path "/network-instances/network-instance/name";
}
description
"Network instance to which an interface is bound.";
}
}
augment "/if:interfaces/if:interface/ip:ipv4" {
description
"Add a node for the identification of the network
instance associated with the information configured
on an IPv4 interface.
Note that a standard error will be returned if the
identified leafref isn't present. If an interface cannot
be assigned for any other reason, the operation SHALL fail
with an error-tag of 'operation-failed' and an
error-app-tag of 'ni-assignment-failed'. A meaningful
error-info that indicates the source of the assignment
failure SHOULD also be provided.";
leaf bind-ni-name {
type leafref {
path "/network-instances/network-instance/name";
}
description
"Network instance to which IPv4 interface is bound.";
}
}
augment "/if:interfaces/if:interface/ip:ipv6" {
description
"Add a node for the identification of the network
instance associated with the information configured
on an IPv6 interface.
Note that a standard error will be returned if the
identified leafref isn't present. If an interface cannot
be assigned for any other reason, the operation SHALL fail
with an error-tag of 'operation-failed' and an
error-app-tag of 'ni-assignment-failed'. A meaningful
error-info that indicates the source of the assignment
failure SHOULD also be provided.";
leaf bind-ni-name {
type leafref {
path "/network-instances/network-instance/name";
}
description
"Network instance to which IPv6 interface is bound.";
}
}
// notification statements
notification bind-ni-name-failed {
description
"Indicates an error in the association of an interface to an
NI. Only generated after success is initially returned when
bind-ni-name is set.
Note: Some errors may need to be reported for multiple
associations, e.g., a single error may need to be reported
for an IPv4 and an IPv6 bind-ni-name.
At least one container with a bind-ni-name leaf MUST be
included in this notification.";
leaf name {
type leafref {
path "/if:interfaces/if:interface/if:name";
}
mandatory true;
description
"Contains the interface name associated with the
failure.";
}
container interface {
description
"Generic interface type.";
leaf bind-ni-name {
type leafref {
path "/if:interfaces/if:interface"
+ "/ni:bind-ni-name";
}
description
"Contains the bind-ni-name associated with the
failure.";
}
}
container ipv4 {
description
"IPv4 interface type.";
leaf bind-ni-name {
type leafref {
path "/if:interfaces/if:interface/ip:ipv4/ni:bind-ni-name";
}
description
"Contains the bind-ni-name associated with the
failure.";
}
}
container ipv6 {
description
"IPv6 interface type.";
leaf bind-ni-name {
type leafref {
path "/if:interfaces/if:interface/ip:ipv6"
+ "/ni:bind-ni-name";
}
description
"Contains the bind-ni-name associated with the
failure.";
}
}
leaf error-info {
type string;
description
"Optionally, indicates the source of the assignment
failure.";
}
}
}
<CODE ENDS>7. References 📚
the reference list didn't make it into this part of the text, so it'll show up in the next part 🫶
7.1. Normative References ✨
okay bestie, here are the normative references 🫶 these are the docs this spec leans on, so you'll see a whole squad of familiar RFCs in here.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/info/rfc8340>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>.
[RFC8343] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, <https://www.rfc-editor.org/info/rfc8343>.
[RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", RFC 8344, DOI 10.17487/RFC8344, March 2018, <https://www.rfc-editor.org/info/rfc8344>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
[RFC8528] Bjorklund, M. and L. Lhotka, "YANG Schema Mount", RFC 8528, DOI 10.17487/RFC8528, March 2019, <https://www.rfc-editor.org/info/rfc8528>.
7.2. Informative References 🌸
these ones are the extra-context crew 💅 good for going deeper, not the core squad.
[RFC4026] Andersson, L. and T. Madsen, "Provider Provisioned Virtual Private Network (VPN) Terminology", RFC 4026, DOI 10.17487/RFC4026, March 2005, <https://www.rfc-editor.org/info/rfc4026>.
[RFC4364] Rosen, E. and Y. Rekhter, "BGP/MPLS IP Virtual Private Networks (VPNs)", RFC 4364, DOI 10.17487/RFC4364, February 2006, <https://www.rfc-editor.org/info/rfc4364>.
[RFC4664] Andersson, L., Ed. and E. Rosen, Ed., "Framework for Layer 2 Virtual Private Networks (L2VPNs)", RFC 4664, DOI 10.17487/RFC4664, September 2006, <https://www.rfc-editor.org/info/rfc4664>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>.
[RFC8349] Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for Routing Management (NMDA Version)", RFC 8349, DOI 10.17487/RFC8349, March 2018, <https://www.rfc-editor.org/info/rfc8349>.
[RFC8530] Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. Liu, "YANG Model for Logical Network Elements", RFC 8530, DOI 10.17487/RFC8530, March 2019.
[YANG-L2VPN] Shah, H., Brissette, P., Chen, I., Hussain, I., Wen, B., and K. Tiruveedhula, "YANG Data Model for MPLS-based L2VPN", Work in Progress, draft-ietf-bess-l2vpn-yang-09, October 2018.
[YANG-L3VPN] Jain, D., Patel, K., Brissette, P., Li, Z., Zhuang, S., Liu, X., Haas, J., Esale, S., and B. Wen, "Yang Data Model for BGP/MPLS L3 VPNs", Work in Progress, draft-ietf-bess-l3vpn-yang-04, October 2018.
[YANG-NETWORK] Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, "Network Device YANG Logical Organization", Work in Progress, draft-ietf-rtgwg-device-model-02, March 2017.
[YANG-OSPF] Yeung, D., Qu, Y., Zhang, Z., Chen, I., and A. Lindem, "YANG Data Model for OSPF Protocol", Work in Progress, draft-ietf-ospf-yang-21, January 2019.
Appendix A. Example NI Usage 🎀
okay this is the fun part 🧚 the examples! the following subsections show some real-life ways NIs get used.
A.1. Configuration Data 💖
here's an example where two customer-specific network instances get configured 👑
{
"ietf-network-instance:network-instances": {
"network-instance": [
{
"name": "vrf-red",
"vrf-root": {
"ietf-routing:routing": {
"router-id": "192.0.2.1",
"control-plane-protocols": {
"control-plane-protocol": [
{
"type": "ietf-routing:ospf",
"name": "1",
"ietf-ospf:ospf": {
"af": "ipv4",
"areas": {
"area": [
{
"area-id": "203.0.113.1",
"interfaces": {
"interface": [
{
"name": "eth1",
"cost": 10
}
]
}
}
]
}
}
}
]
}
}
}
},
{
"name": "vrf-blue",
"vrf-root": {
"ietf-routing:routing": {
"router-id": "192.0.2.2",
"control-plane-protocols": {
"control-plane-protocol": [
{
"type": "ietf-routing:ospf",
"name": "1",
"ietf-ospf:ospf": {
"af": "ipv4",
"areas": {
"area": [
{
"area-id": "203.0.113.1",
"interfaces": {
"interface": [
{
"name": "eth2",
"cost": 10
}
]
}
}
]
}
}
}
]
}
}
}
}
]
},
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"ietf-ip:ipv4": {
"address": [
{
"ip": "192.0.2.10",
"prefix-length": 24
}
]
},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2001:db8:0:2::10",
"prefix-length": 64
}
]
}
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"ietf-ip:ipv4": {
"address": [
{
"ip": "192.0.2.11",
"prefix-length": 24
}
]
},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2001:db8:0:2::11",
"prefix-length": 64
}
]
},
"ietf-network-instance:bind-network-instance-name": "vrf-red"
},
{
"name": "eth2",
"type": "iana-if-type:ethernetCsmacd",
"ietf-ip:ipv4": {
"address": [
{
"ip": "192.0.2.11",
"prefix-length": 24
}
]
},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2001:db8:0:2::11",
"prefix-length": 64
}
]
},
"ietf-network-instance:bind-network-instance-name":
"vrf-blue"
}
]
},
"ietf-system:system": {
"authentication": {
"user": [
{
"name": "john",
"password": "$0$password"
}
]
}
}
}A.2. State Data - Non-NMDA Version 🦋
okay so this one shows the state data for the config example above 🔥 It's based on [RFC8343], [RFC8344], and [RFC8349].
A.3. State Data - NMDA Version ✨
okay so this one is the NMDA version of the state data 🦋 it's the same config example from before, but now it's built on [RFC8343], [RFC8344], and [RFC8349]. the big difference is that the YANG library info lives under ietf-yang-library:yang-library and the routing stuff is under ietf-routing:routing instead of the old non-NMDA names. it's giving clean datastore vibes 💅
{
"ietf-network-instance:network-instances": {
"network-instance": [
{
"name": "vrf-red",
"vrf-root": {
"ietf-yang-library:yang-library": {
"content-id": "41e2ab5dc325f6d86f743e8da3de323f1a61a801",
"module-set": [
{
"name": "ni-modules",
"module": [
{
"name": "ietf-yang-library",
"revision": "2019-01-04",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-yang-library"
},
{
"name": "ietf-ospf",
"revision": "2019-01-24",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-ospf"
},
{
"name": "ietf-routing",
"revision": "2018-03-13",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-routing"
}
],
"import-only-module": [
{
"name": "ietf-inet-types",
"revision": "2013-07-15",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-inet-types"
},
{
"name": "ietf-yang-types",
"revision": "2013-07-15",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-yang-types"
},
{
"name": "ietf-datastores",
"revision": "2018-02-14",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-datastores"
}
]
}
],
"schema": [
{
"name": "ni-schema",
"module-set": [ "ni-modules" ]
}
],
"datastore": [
{
"name": "ietf-datastores:running",
"schema": "ni-schema"
},
{
"name": "ietf-datastores:operational",
"schema": "ni-schema"
}
]
},
"ietf-routing:routing": {
"router-id": "192.0.2.1",
"control-plane-protocols": {
"control-plane-protocol": [
{
"type": "ietf-routing:ospf",
"name": "1",
"ietf-ospf:ospf": {
"af": "ipv4",
"areas": {
"area": [
{
"area-id": "203.0.113.1",
"interfaces": {
"interface": [
{
"name": "eth1",
"cost": 10
}
]
} }
]
}
}
}
]
}
}
}
},
{
"name": "vrf-blue",
"vrf-root": {
"ietf-yang-library:yang-library": {
"checksum": "41e2ab5dc325f6d86f743e8da3de323f1a61a801",
"module-set": [
{
"name": "ni-modules",
"module": [
{
"name": "ietf-yang-library",
"revision": "2019-01-04",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-yang-library",
"conformance-type": "implement"
},
{
"name": "ietf-ospf",
"revision": "2019-01-24",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-ospf",
"conformance-type": "implement"
},
{
"name": "ietf-routing",
"revision": "2018-03-13",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-routing",
"conformance-type": "implement"
}
],
"import-only-module": [
{
"name": "ietf-inet-types",
"revision": "2013-07-15",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-inet-types"
},
{
"name": "ietf-yang-types",
"revision": "2013-07-15",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-yang-types"
},
{
"name": "ietf-datastores",
"revision": "2018-02-14",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-datastores"
}
]
}
],
"schema": [
{
"name": "ni-schema",
"module-set": [ "ni-modules" ]
}
],
"datastore": [
{
"name": "ietf-datastores:running",
"schema": "ni-schema"
},
{
"name": "ietf-datastores:operational",
"schema": "ni-schema"
}
]
},
"ietf-routing:routing": {
"router-id": "192.0.2.2",
"control-plane-protocols": {
"control-plane-protocol": [
{
"type": "ietf-routing:ospf",
"name": "1",
"ietf-ospf:ospf": {
"af": "ipv4",
"areas": {
"area": [
{
"area-id": "203.0.113.1",
"interfaces": {
"interface": [
{
"name": "eth2",
"cost": 10
}
]
}
}
]
}
}
}
]
}
}
}
}
]
},
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"oper-status": "up",
"phys-address": "00:01:02:A1:B1:C0",
"statistics": {
"discontinuity-time": "2017-06-26T12:34:56-05:00"
},
"ietf-ip:ipv4": {
"address": [
{
"ip": "192.0.2.10",
"prefix-length": 24
}
]
},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2001:db8:0:2::10",
"prefix-length": 64
}
]
}
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"oper-status": "up",
"phys-address": "00:01:02:A1:B1:C1",
"statistics": {
"discontinuity-time": "2017-06-26T12:34:56-05:00"
},
"ietf-ip:ipv4": {
"address": [
{
"ip": "192.0.2.11",
"prefix-length": 24
}
]
},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2001:db8:0:2::11",
"prefix-length": 64
}
]
}
},
{
"name": "eth2",
"type": "iana-if-type:ethernetCsmacd",
"oper-status": "up",
"phys-address": "00:01:02:A1:B1:C2",
"statistics": {
"discontinuity-time": "2017-06-26T12:34:56-05:00"
},
"ietf-ip:ipv4": {
"address": [
{
"ip": "192.0.2.11",
"prefix-length": 24
}
]
},
"ietf-ip:ipv6": {
"address": [
{
"ip": "2001:db8:0:2::11",
"prefix-length": 64
}
]
}
}
]
},
"ietf-system:system-state": {
"platform": {
"os-name": "NetworkOS"
}
},
"ietf-yang-library:yang-library": {
"content-id": "75a43df9bd56b92aacc156a2958fbe12312fb285",
"module-set": [
{
"name": "host-modules",
"module": [
{
"name": "ietf-interfaces",
"revision": "2018-02-20",
"feature": [
"arbitrary-names",
"pre-provisioning"
],
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-interfaces"
},
{
"name": "ietf-ip",
"revision": "2018-01-09",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-ip"
},
{
"name": "ietf-network-instance",
"revision": "2018-02-03",
"feature": [
"bind-network-instance-name"
],
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-network-instance"
},
{
"name": "ietf-ospf",
"revision": "2019-01-24",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-ospf"
},
{
"name": "ietf-routing",
"revision": "2018-03-13",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-routing"
},
{
"name": "ietf-system",
"revision": "2014-08-06",
"namespace": "urn:ietf:params:xml:ns:yang:ietf-system"
},
{
"name": "ietf-yang-library",
"revision": "2019-01-04",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-yang-library"
},
{
"name": "ietf-yang-schema-mount",
"revision": "2019-01-14",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount"
}
],
"import-only-module": [
{
"name": "iana-if-type",
"revision": "2018-07-03",
"namespace": "urn:ietf:params:xml:ns:yang:iana-if-type"
},
{
"name": "ietf-inet-types",
"revision": "2013-07-15",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-inet-types"
},
{
"name": "ietf-yang-types",
"revision": "2013-07-15",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-yang-types"
},
{
"name": "ietf-datastores",
"revision": "2018-02-14",
"namespace":
"urn:ietf:params:xml:ns:yang:ietf-datastores"
}
]
}
],
"schema": [
{
"name": "host-schema",
"module-set": [ "host-modules" ]
}
],
"datastore": [
{
"name": "ietf-datastores:running",
"schema": "host-schema"
},
{
"name": "ietf-datastores:operational",
"schema": "host-schema"
}
]
},
"ietf-yang-schema-mount:schema-mounts": {
"mount-point": [
{
"module": "ietf-network-instance",
"label": "vrf-root",
"shared-schema": {
"parent-reference": [
"/*[namespace-uri() = 'urn:ietf:...:ietf-interfaces']"
]
}
}
]
}
}Acknowledgments 🙏✨
Okay, big shoutout to the Routing Area Yang Architecture design team, the squad who got this whole thing going 💖: Acee Lindem, Anees Shaikh, Christian Hopps, Dean Bogdanovic, Lou Berger, Qin Wu, Rob Shakir, Stephane Litkowski, and Yan Gang. 🫶 Martin Bjorklund and John Scudder gave really useful review comments, and we are so grateful 😭.
This document was inspired by, and comes straight out of, "Network Device YANG Logical Organization" [YANG-NETWORK]. Main character origin story, honestly 🎀.
Thanks to Alia Atlas, Liang Xia, Benoit Claise, and Adam Roach for the Area Director and IETF last-call comments. You all are literally iconic 👑.
Authors' Addresses 💌
- Lou Berger 🌸
- LabN Consulting, L.L.C.
- Email: lberger@labn.net
- Christian Hopps 🦋
- LabN Consulting, L.L.C.
- Email: chopps@chopps.org
- Acee Lindem 💜
- Cisco Systems
- 301 Midenhall Way
- Cary, NC 27513
- United States of America
- Email: acee@cisco.com
- Dean Bogdanovic 🍓
- Volta Networks
- Email: ivandean@gmail.com
- Xufeng Liu 🧚
- Volta Networks
- Email: xufeng.liu.ietf@gmail.com
That's the whole RFC, bestie, we made it 🌈💅
📦 where this page comes from
- ietf: rfc8529 2019-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms