RFC 6095
Extending YANG with Language Abstractions
Pages: 75
Experimental
Experimental
Part 1 of 4 – Pages 1 to 14
Internet Engineering Task Force (IETF) B. Linowski Request for Comments: 6095 TCS/Nokia Siemens Networks Category: Experimental M. Ersue ISSN: 2070-1721 Nokia Siemens Networks S. Kuryla 360 Treasury Systems March 2011 Extending YANG with Language AbstractionsAbstract
YANG -- the Network Configuration Protocol (NETCONF) Data Modeling Language -- supports modeling of a tree of data elements that represent the configuration and runtime status of a particular network element managed via NETCONF. This memo suggests enhancing YANG with supplementary modeling features and language abstractions with the aim to improve the model extensibility and reuse. Status of This Memo This document is not an Internet Standards Track specification; it is published for examination, experimental implementation, and evaluation. This document defines an Experimental Protocol for the Internet community. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are a candidate for any level of Internet Standard; see Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc6095.
Copyright Notice Copyright (c) 2011 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 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Modeling Improvements with Language Abstractions . . . . . 5 1.4. Design Approach . . . . . . . . . . . . . . . . . . . . . 6 1.5. Modeling Resource Models with YANG . . . . . . . . . . . . 6 1.5.1. Example of a Physical Network Resource Model . . . . . 6 1.5.2. Modeling Entity MIB Entries as Physical Resources . . 12 2. Complex Types . . . . . . . . . . . . . . . . . . . . . . . . 15 2.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 15 2.2. complex-type Extension Statement . . . . . . . . . . . . . 15 2.3. instance Extension Statement . . . . . . . . . . . . . . . 17 2.4. instance-list Extension Statement . . . . . . . . . . . . 18 2.5. extends Extension Statement . . . . . . . . . . . . . . . 19 2.6. abstract Extension Statement . . . . . . . . . . . . . . . 19 2.7. XML Encoding Rules . . . . . . . . . . . . . . . . . . . . 20 2.8. Type Encoding Rules . . . . . . . . . . . . . . . . . . . 20 2.9. Extension and Feature Definition Module . . . . . . . . . 21 2.10. Example Model for Complex Types . . . . . . . . . . . . . 24 2.11. NETCONF Payload Example . . . . . . . . . . . . . . . . . 25 2.12. Update Rules for Modules Using Complex Types . . . . . . . 26 2.13. Using Complex Types . . . . . . . . . . . . . . . . . . . 26 2.13.1. Overriding Complex Type Data Nodes . . . . . . . . . . 26 2.13.2. Augmenting Complex Types . . . . . . . . . . . . . . . 27 2.13.3. Controlling the Use of Complex Types . . . . . . . . . 28 3. Typed Instance Identifier . . . . . . . . . . . . . . . . . . 29 3.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 29 3.2. instance-type Extension Statement . . . . . . . . . . . . 29 3.3. Typed Instance Identifier Example . . . . . . . . . . . . 30 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 5. Security Considerations . . . . . . . . . . . . . . . . . . . 31
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 32 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 32 7.1. Normative References . . . . . . . . . . . . . . . . . . . 32 7.2. Informative References . . . . . . . . . . . . . . . . . . 32 Appendix A. YANG Modules for Physical Network Resource Model and Hardware Entities Model . . . . . . . . . . . . . 34 Appendix B. Example YANG Module for the IPFIX/PSAMP Model . . . . 40 B.1. Modeling Improvements for the IPFIX/PSAMP Model with Complex Types and Typed Instance Identifiers . . . . . . . 40 B.2. IPFIX/PSAMP Model with Complex Types and Typed Instance Identifiers . . . . . . . . . . . . . . . . . . . 411. Introduction
YANG -- the NETCONF Data Modeling Language [RFC6020] -- supports modeling of a tree of data elements that represent the configuration and runtime status of a particular network element managed via NETCONF. This document defines extensions for the modeling language YANG as new language statements, which introduce language abstractions to improve the model extensibility and reuse. The document reports from modeling experience in the telecommunication industry and gives model examples from an actual network management system to highlight the value of proposed language extensions, especially class inheritance and recursiveness. The language extensions defined in this document have been implemented with two open source tools. These tools have been used to validate the model examples through the document. If this experimental specification results in successful usage, it is possible that the language extensions defined herein could be updated to incorporate implementation and deployment experience, then pursued on the Standards Track, possibly as part of a future version of YANG.1.1. Key Words
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].1.2. Motivation
Following are non-exhaustive motivation examples highlighting usage scenarios for language abstractions. o Many systems today have a Management Information Base (MIB) that in effect is organized as a tree build of recursively nested container nodes. For example, the physical resources in the ENTITY-MIB conceptually form a containment tree. The index
entPhysicalContainedIn points to the containing entity in a flat
list. The ability to represent nested, recursive data structures
of arbitrary depth would enable the representation of the primary
containment hierarchy of physical entities as a node tree in the
server MIB and in the NETCONF payload.
o A manager scanning the network in order to update the state of an
inventory management system might be only interested in data
structures that represent a specific type of hardware. Such a
manager would then look for entities that are of this specific
type, including those that are an extension or specialization of
this type. To support this use case, it is helpful to bear the
corresponding type information within the data structures, which
describe the network element hardware.
o A system that is managing network elements is concerned, e.g.,
with managed objects of type "plug-in modules" that have a name, a
version, and an activation state. In this context, it is useful
to define the "plug-in module" as a concept that is supposed to be
further detailed and extended by additional concrete model
elements. In order to realize such a system, it is worthwhile to
model abstract entities, which enable reuse and ease concrete
refinements of that abstract entity in a second step.
o As particular network elements have specific types of components
that need to be managed (OS images, plug-in modules, equipment,
etc.), it should be possible to define concrete types, which
describe the managed object precisely. By using type-safe
extensions of basic concepts, a system in the manager role can
safely and explicitly determine that e.g., the "equipment" is
actually of type "network card".
o Currently, different SDOs are working on the harmonization of
their management information models. Often, a model mapping or
transformation between systems becomes necessary. The
harmonization of the models is done e.g., by mapping of the two
models on the object level or integrating an object hierarchy into
an existing information model. On the one hand, extending YANG
with language abstractions can simplify the adoption of IETF
resource models by other SDOs and facilitate the alignment with
other SDOs' resource models (e.g., TM Forum SID [SID_V8]). On the
other hand, the proposed YANG extensions can enable the
utilization of the YANG modeling language in other SDOs, which
usually model complex management systems in a top-down manner and
use high-level language features frequently.
This memo specifies additional modeling features for the YANG language in the area of structured model abstractions, typed references, as well as recursive data structures, and it discusses how these new features can improve the modeling capabilities of YANG. Section 1.5.1 contains a physical resource model that deals with some of the modeling challenges illustrated above. Section 1.5.2 gives an example that uses the base classes defined in the physical resource model and derives a model for physical entities defined in the Entity MIB.1.3. Modeling Improvements with Language Abstractions
As an enhancement to YANG 1.0, complex types and typed instance identifiers provide different technical improvements on the modeling level: o In case the model of a system that should be managed with NETCONF makes use of inheritance, complex types enable an almost one-to- one mapping between the classes in the original model and the YANG module. o Typed instance identifiers allow representing associations between the concepts in a type-safe way to prevent type errors caused by referring to data nodes of incompatible types. This avoids referring to a particular location in the MIB. Referring to a particular location in the MIB is not mandated by the domain model. o Complex types allow defining complete, self-contained type definitions. It is not necessary to explicitly add a key statement to lists, which use a grouping that defines the data nodes. o Complex types simplify concept refinement by extending a base complex type and make it superfluous to represent concept refinements with workarounds such as huge choice-statements with complex branches. o Abstract complex types ensure correct usage of abstract concepts by enforcing the refinement of a common set of properties before instantiation. o Complex types allow defining recursive structures. This enables representing complex structures of arbitrary depth by nesting instances of basic complex types that may contain themselves.
o Complex types avoid introducing metadata types (e.g., type code
enumerations) and metadata leafs (e.g., leafs containing a type
code) to indicate which concrete type of object is actually
represented by a generic container in the MIB. This also avoids
explicitly ruling out illegal use of subtype-specific properties
in generic containers.
o Complex type instances include the type information in the NETCONF
payload. This allows determining the actual type of an instance
during the NETCONF payload parsing and avoids the use in the model
of additional leafs, which provide the type information as
content.
o Complex types may be declared explicitly as optional features,
which is not possible when the actual type of an entity
represented by a generic container is indicated with a type code
enumeration.
Appendix B, "Example YANG Module for the IPFIX/PSAMP Model", lists
technical improvements for modeling with complex types and typed
instance identifiers and exemplifies the usage of the proposed YANG
extensions based on the IP Flow Information Export (IPFIX) / Packet
Sampling (PSAMP) configuration model in [IPFIXCONF].
1.4. Design Approach
The proposed additional features for YANG in this memo are designed
to reuse existing YANG statements whenever possible. Additional
semantics is expressed by an extension that is supposed to be used as
a substatement of an existing statement.
The proposed features don't change the semantics of models that is
valid with respect to the YANG specification [RFC6020].
1.5. Modeling Resource Models with YANG
1.5.1. Example of a Physical Network Resource Model
The diagram below depicts a portion of an information model for
manageable network resources used in an actual network management
system.
Note: The referenced model (UDM, Unified Data Model) is based on key
resource modeling concepts from [SID_V8] and is compliant with
selected parts of SID Resource Abstract Business Entities domain
[UDM].
The class diagram in Figure 1 and the corresponding YANG module excerpt focus on basic resource ("Resource" and the distinction between logical and physical resources) and hardware abstractions ("Hardware", "Equipment", and "EquipmentHolder"). Class attributes were omitted to achieve decent readability.
+--------+ |Resource| +--------+ /\ /\ -- -- | | | +---------------+ | |LogicalResource| | +---------------+ | | +--------+ | |Physical| +-----------+ '-|Resource|<|-+-|PhysicalLink| +---- ---+ | +------------+ | |0..* physicalLink | | equipment | | Holder | | 0..* | | +-------+ | |0..* hardware | | | +--------+ +---------------+ +---------+ | '-|Hardware|<|-+-|ManagedHardware|<|-+-|Equipment|<>--+ +--------+ | +---------------+ | | Holder |0..1 <> | | +---------+ 0..1| | | <> | | | |0..* equipment | | | | Holder | | | | | | | |0..* equipment | | | | | | | | equipment | | | | 0..* | | | | +-------+ | | | | | | | | | +---------+ | | | '-|Equipment|<>--+ | | +---------+0..1 | | compositeEquipment | | | | +-----------------+ | '-|PhysicalConnector|----+0..* source '----------+-----------------+ | Physical physicalConnector 0..* | | Connector | | +-----------+ 0..* targetPhysicalConnector Figure 1: Physical Network Resource Model
Since this model is an abstraction of network-element-specific MIB
topologies, modeling it with YANG creates some challenges. Some of
these challenges and how they can be addressed with complex types are
explained below:
o Modeling of abstract concepts: Classes like "Resource" represent
concepts that primarily serve as a base class for derived classes.
With complex types, such an abstract concept could be represented
by an abstract complex type (see "complex-type extension
statement" and "abstract extension statement").
o Class Inheritance: Information models for complex management
domains often use class inheritance to create specialized classes
like "PhysicalConnector" from a more generic base class (here,
"Hardware"), which itself might inherit from another base class
("PhysicalResource"), etc. Complex types allow creating enhanced
versions of an existing (abstract or concrete) base type via an
extension (see "extends extension statement").
o Recursive containment: In order to specify containment
hierarchies, models frequently contain different aggregation
associations, in which the target (contained element) is either
the containing class itself or a base class of the containing
class. In the model above, the recursive containment of
"EquipmentHolder" is an example of such a relationship (see the
description for the "complex-type EquipmentHolder" in the example
model "udmcore" below).
o Complex types support such a containment by using a complex type
(or one of its ancestor types) as the type of an instance or
instance list that is part of its definition (see "instance(-list)
extension statement").
o Reference relationships: A key requirement on large models for
network domains with many related managed objects is the ability
to define inter-class associations that represent essential
relationships between instances of such a class. For example, the
relationship between "PhysicalLink" and "Hardware" tells which
physical link is connecting which hardware resources. It is
important to notice that this kind of relationship does not
mandate any particular location of the two connected hardware
instances in any MIB module. Such containment-agnostic
relationships can be represented by a typed instance identifier
that embodies one direction of such an association (see Section 3,
"Typed Instance Identifier").
The YANG module excerpt below shows how the challenges listed above can be addressed by the Complex Types extension (module import prefix "ct:"). The complete YANG module for the physical resource model in Figure 1 can be found in Appendix A, "YANG Modules for Physical Network Resource Model and Hardware Entities Model". Note: The YANG extensions proposed in this document have been implemented as the open source tools "Pyang Extension for Complex Types" [Pyang-ct], [Pyang], and "Libsmi Extension for Complex Types" [Libsmi]. All model examples in the document have been validated with the tools Pyang-ct and Libsmi. <CODE BEGINS> module udmcore { namespace "http://example.com/udmcore"; prefix "udm"; import ietf-complex-types {prefix "ct"; } // Basic complex types... ct:complex-type PhysicalResource { ct:extends Resource; ct:abstract true; // ... leaf serialNumber { type string; description "'Manufacturer-allocated part number' as defined in SID, e.g., the part number of a fiber link cable."; } } ct:complex-type Hardware { ct:extends PhysicalResource; ct:abstract true; // ... leaf-list physicalLink { type instance-identifier {ct:instance-type PhysicalLink;} } ct:instance-list containedHardware { ct:instance-type Hardware; } ct:instance-list physicalConnector { ct:instance-type PhysicalConnector;
}
}
ct:complex-type PhysicalLink {
ct:extends PhysicalResource;
// ...
leaf-list hardware {
type instance-identifier {ct:instance-type Hardware;}
}
}
ct:complex-type ManagedHardware {
ct:extends Hardware;
ct:abstract true;
// ...
}
ct:complex-type PhysicalConnector {
ct:extends Hardware;
leaf location {type string;}
// ...
leaf-list sourcePhysicalConnector {
type instance-identifier {ct:instance-type PhysicalConnector;}
}
leaf-list targetPhysicalConnector {
type instance-identifier {ct:instance-type PhysicalConnector;}
}
}
ct:complex-type Equipment {
ct:extends ManagedHardware;
// ...
ct:instance-list equipment {
ct:instance-type Equipment;
}
}
ct:complex-type EquipmentHolder {
ct:extends ManagedHardware;
description "In the SID V8 definition, this is a class based on
the M.3100 specification. A base class that represents physical
objects that are both manageable as well as able to host,
hold, or contain other physical objects. Examples of physical
objects that can be represented by instances of this object
class are Racks, Chassis, Cards, and Slots.
A piece of equipment with the primary purpose of containing
other equipment.";
leaf vendorName {type string;}
// ...
ct:instance-list equipment {
ct:instance-type Equipment;
}
ct:instance-list equipmentHolder {
ct:instance-type EquipmentHolder;
}
}
// ...
}
<CODE ENDS>
1.5.2. Modeling Entity MIB Entries as Physical Resources
The physical resource module described above can now be used to model
physical entities as defined in the Entity MIB [RFC4133]. For each
physical entity class listed in the "PhysicalClass" enumeration, a
complex type is defined. Each of these complex types extends the
most specific complex type already available in the physical resource
module. For example, the type "HWModule" extends the complex type
"Equipment" as a hardware module. Physical entity properties that
should be included in a physical entity complex type are combined in
a grouping, which is then used in each complex type definition of an
entity.
This approach has following benefits:
o The definition of the complex types for hardware entities becomes
compact as many of the features can be reused from the basic
complex type definition.
o Physical entities are modeled in a consistent manner as predefined
concepts are extended.
o Entity-MIB-specific attributes as well as vendor-specific
attributes can be added without having to define separate
extension data nodes.
Module udmcore : Module hardware-entities : equipment : Holder : 0..* : +-------+ : | | : +---------------+ +---------+ | : |ManagedHardware|<|-+-|Equipment|<>--+ : +---------------+ | | Holder |0..1 : +-------+ | | |<|---------+--|Chassis| | +---------+ : | +-------+ | <> : | | |0..* equipment : | +---------+ | | Holder : '--|Container| | | : +---------+ | |0..* equipment : | | : | | equipment : | | 0..* : | | +-------+ : | | | | : | +---------+ | : '-|Equipment|<>--+ : +--------+ | |<|---------+--|HWModule| +---------+ : | +--------+ compositeEquipment : | : | +---------+ : |--|Backplane| : +---------+ Figure 2: Hardware Entities Model Below is an excerpt of the corresponding YANG module using complex types to model hardware entities. The complete YANG module for the Hardware Entities model in Figure 2 can be found in Appendix A, "YANG Modules for Physical Network Resource Model and Hardware Entities Model".
<CODE BEGINS>
module hardware-entities {
namespace "http://example.com/hardware-entities";
prefix "hwe";
import ietf-yang-types {prefix "yt";}
import ietf-complex-types {prefix "ct";}
import udmcore {prefix "uc";}
grouping PhysicalEntityProperties {
// ...
leaf mfgDate {type yang:date-and-time; }
leaf-list uris {type string; }
}
// Physical entities representing equipment
ct:complex-type HWModule {
ct:extends uc:Equipment;
description "Complex type representing module entries
(entPhysicalClass = module(9)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
// ...
// Physical entities representing equipment holders
ct:complex-type Chassis {
ct:extends uc:EquipmentHolder;
description "Complex type representing chassis entries
(entPhysicalClass = chassis(3)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
// ...
}
<CODE ENDS>
(next page on part 2)