| NETMOD Working Group | M. Wang |
| Internet-Draft | Q. Wu |
| Intended status: Standards Track | Huawei |
| Expires: September 2, 2019 | C. Xie |
| China Telecom | |
| March 1, 2019 |
A YANG Data model for Policy based Event Management
draft-wwx-netmod-event-yang-01
[RFC8328] defines a policy-based management framework that allow definition of a data model to be used to represent high-level, possibly network-wide policies. This document defines an YANG data model for the policy based event management [RFC7950]. The policy based Event YANG provides the ability for the network management function (within a controller, an orchestrator, or a network element) to control the configuration and monitor state change on the network element and take simple and instant action when a trigger condition on the system state is met.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 2, 2019.
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) 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.
[RFC8328] defines a policy-based management framework that allow definition of a data model to be used to represent high-level, possibly network-wide policies. This document defines an policy based Event Management YANG data model [RFC7950]. The policy based Event management YANG provides the ability for the network management function (within a controller, an orchestrator, or a network element) to monitor state changes on the network element and take simple and instant action when a trigger condition on the system state is met.
The data model in this document is designed to be compliant with the Network Management Datastore Architecture (NMDA) [RFC8342].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. In this document, these words will appear with that interpretation only when in ALL CAPS. Lower case uses of these words are not to be interpreted as carrying [RFC2119] significance.
This document uses the following terms:
Tree diagrams used in this document follow the notation defined in [RFC8340].
This section describes some of the design objectives for the policy based Event management Data Model:
YANG-push mechanism provides a subscription service for updates from a datastore. And it supports two types of subscriptions which are distinguished by how updates are triggered: periodic and on-change.
The On-change Push allow receivers to receive updates whenever changes to target managed objects occur. This document specifies a mechanism that provides three trigger conditions:
And the YANG Push mechanism more focus on the remote mirroring and monitoring of configuration and operational state. For example, for on change method, the subscriber will receive a notification if the changes occurs. The model defined in this document provides a method which allow automatic adjusting the value of the corresponding managed object when some event is triggered. It establishes connection between network service monitoring and network service provision and can use output generated by network service monitoring as input of network service provision and thereby provide automated network management. The details of the usage example is described in Appendix A.
If the device implements the EVENT-MIB [RFC2981], each entry in the "/events/event/trigger" list is mapped to MteTriggerEntry,MteTriggerExistenceEntry,MteTriggerBooleanEntry,MteTriggerThresholdEntry,MteObjectsEntry,MteEventEntry,MteEventSetEntry. respectively.
The following table lists the YANG data nodes with corresponding objects in the EVENT-MIB [RFC2981].
+------------------------------|---------------------------------+ | | | | YANG data node in | EVENT-MIB Objects | | ietf-event.yang | (RFC2981) | | | | +----------------------------------------------------------------+ | | | | min-data-object | mteResourceSampleMinimum | | | | | max-data-object | mteResourceSampleInstanceMaximum| | | | | traget | mteObjectsName | | | | | event-name | mteEventName | | | | | event-description | mteEventComment | | | | | value | mteEventSetValue | | | | | events/event/trigger/name | mteTriggerName | | | | | trigger-description | mteTriggerComment | | | | | frequency | mteTriggerFrequency | | | | | comparison | mteTriggerBooleanComparison | | | | | value | mteTriggerBooleanValue | | | | | rising-event | mteTriggerThresholdRising | | | | | falling-event | mteTriggerThresholdFalling | | | | | delta-rising-event | mteTriggerThresholdDeltaRising | | | | | threshold/startup | mteTriggerThresholdStartup | | | | | existence/enable | mteTriggerExistenceStartup | | | | | boolean/enable | mteTriggerBooleanStartup | | | | -------------------------------|---------------------------------|
The YANG data model for the Event management has been split into two modules:
groupings:
trigger-grouping
+---- (test)?
+--:(existences)
| +---- existences
| +---- target* target
+--:(boolean)
| +---- boolean
| +---- comparison? enumeration
| +---- value? match-value
| +---- target* target
+--:(threshold)
+---- threshold
+---- rising-value? match-value
+---- rising-target* target
+---- falling-value? match-value
+---- falling-target* target
+---- delta-rising-value? match-value
+---- delta-rising-target* target
+---- delta-falling-value? match-value
+---- delta-falling-target* target
+---- startup? enumeration
module: ietf-event
+--rw events
+--rw min-data-object? uint32
+--rw max-data-object? uint32
+--rw event* [event-name type]
+--rw event-name string
+--rw type identityref
+--rw event-description? string
+--rw target* trig:target
+--rw clear? boolean
+--rw related-event* [event-name type]
| +--rw event-name string
| +--rw type identityref
+--rw trigger* [name]
| +--rw name string
| +--rw type? enumeration
| +--rw trigger-description? string
| +--rw frequency
| | +--rw type? identityref
| | +--rw periodic
| | | +--rw interval uint32
| | | +--rw start? yang:date-and-time
| | | +--rw end? yang:date-and-time
| | +--rw scheduling
| | +--rw month* string
| | +--rw day-of-month* uint8
| | +--rw day-of-week* uint8
| | +--rw hour* uint8
| | +--rw minute* uint8
| | +--rw second* uint8
| | +--rw start? yang:date-and-time
| | +--rw end? yang:date-and-time
| +--rw (test)?
| +--:(existences)
| | +--rw existences
| | +--rw target* -> /events/event/target
| +--:(boolean)
| | +--rw boolean
| | +--rw comparison? enumeration
| | +--rw value? match-value
| | +--rw target* target
| +--:(threshold)
| +--rw threshold
| +--rw rising-value? match-value
| +--rw rising-target* target
| +--rw falling-value? match-value
| +--rw falling-target* target
| +--rw delta-rising-value? match-value
| +--rw delta-rising-target* target
| +--rw delta-falling-value? match-value
| +--rw delta-falling-target* target
| +--rw startup? enumeration
+--rw action* [action-name]
+--rw action-name string
+---n event-notification
| +---- event-name? -> /events/event/event-name
| +---- type? -> /events/event/type
| +---- target* trig:target
+---x set
| +---w input
| +---w target* trig:target
| +---w value? <anydata>
+--rw trigger-event* -> ../../event-name
The following tree diagrams [RFC8340] provide an overview of the data model for "ietf-event-trigger" module and the "ietf-event" module.
+-------------------------------+
| Event |
| +-------+ |
| |Target | |
| +---|---+ | +-------------------------------+
| | | | Event |
| +----V---+ +--------+ | | +-------+ |
| |Trigger |------->| Action |-------->|Target | |
| +--------+ +--------+ | | +---|---+ |
+-------------------------------+ | | |
| +----|---+ +--------+ |
| |Trigger |------- | Action | |
| +--------+ +--------+ |
+-------------------------------+
The relation between Event, Trigger, Target and Action is described as follows:
One event may trigger another event,i.e., the action output in the first event can be input to target in the second event, but if it does not trigger another event, the relation between action and target should be ignored.
<CODE BEGINS> file "ietf-event-trigger@2018-12-18.yang"
module ietf-event-trigger {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-event-trigger";
prefix trig;
import ietf-yang-types {
prefix yang;
}
organization
"IETF xxx Working Group";
contact
"Zitao Wang: wangzitao@huawei.com
Qin Wu: bill.wu@huawei.com";
description
"This module defines a reusable grouping for event trigger.";
revision 2018-12-18 {
description
"Initial revision.";
reference "foo";
}
typedef match-value {
type union {
type yang:xpath1.0;
type yang:object-identifier;
type string;
}
description
"This type is used to match resources of type 'target'.
Since the type 'target' is a union of different types,
the 'match-value' type is also a union of corresponding
types.";
}
typedef target {
type union {
type instance-identifier;
type yang:object-identifier;
type yang:uuid;
type string;
}
description
"If the target is modelled in YANG, this type will
be an instance-identifier.
If the target is an SNMP object, the type will be an
object-identifier.
If the target is anything else, for example a distinguished
name or a CIM path, this type will be a string.
If the target is identified by a UUID use the uuid
type.
If the server supports several models, the presedence should
be in the order as given in the union definition.";
}
grouping trigger-grouping {
description
"A grouping that provides event trigger.";
choice test {
description
"Choice test";
container existences {
leaf-list target {
type target;
description
"List for target objects";
}
description
"Container for existence";
}
container boolean {
leaf comparison {
type enumeration {
enum "unequal" {
description
"Indicates that the comparision type is unequal to.";
}
enum "equal" {
description
"Indicates that the comparision type is equal to.";
}
enum "less" {
description
"Indicates that the comparision type is less than.";
}
enum "less-or-equal" {
description
"Indicates that the comparision type is less than
or equal to.";
}
enum "greater" {
description
"Indicates that the comparision type is greater than.";
}
enum "greater-or-equal" {
description
"Indicates that the comparision type is greater than
or equal to.";
}
}
description
"Comparison type.";
}
leaf value {
type match-value;
description
"Compartion value which is static threshold value.";
}
leaf target {
type target;
description
"List for target management objects.";
}
description
"Container for boolean test.";
}
container threshold {
leaf rising-value {
type match-value;
description
"Sets the rising threshold to the specified value,
when the current sampled value is greater than or equal to
this threshold, and the value at the last sampling interval
was less than this threshold, the event is triggered. ";
}
leaf-list rising-target {
type target;
description
"List for target objects.";
}
leaf falling-value {
type match-value;
description
"Sets the falling threshold to the specified value.";
}
leaf-list falling-target {
type target;
description
"List for target objects.";
}
leaf delta-rising-value {
type match-value;
description
"Sets the delta rising threshold to the specified value.";
}
leaf-list delta-rising-target {
type target;
description
"List for target objects.";
}
leaf delta-falling-value {
type match-value;
description
"Sets the delta falling threshold to the specified value.";
}
leaf-list delta-falling-target {
type target;
description
"List for target objects.";
}
leaf startup {
type enumeration {
enum "rising" {
description
"If the first sample after this
managed object becomes active is greater than or equal
to 'rising-value' and the 'startup' is equal to
'rising' then one threshold rising event is
triggered for that managed object.";
}
enum "falling" {
description
"If the first sample after this managed object becomes
active is less than or equal to 'falling-value' and
the 'startup' is equal to 'falling' then one
threshold falling event is triggered for that managed
object.";
}
enum "rising-or-falling" {
description
"That event may be triggered when the
'startup' is equal to 'rising-or-falling'.
'rising-or-falling' indicate the state value of the
managed object may less than or greater than the
specified thrshold value.";
}
}
description
"Startup setting.";
}
description
"Container for the threshold trigger condition.
Note that the threshold here may change over time
or the state value changes in either ascend order
or descend order.";
}
}
}
}
<CODE ENDS>
<CODE BEGINS> file "ietf-event@2018-09-18.yang"
module ietf-event {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-event";
prefix evt;
import ietf-yang-types {
prefix yang;
}
import ietf-event-trigger {
prefix trig;
}
organization
"IETF xxx Working Group";
contact
"Zitao Wang: wangzitao@huawei.com
Qin Wu: bill.wu@huawei.com";
description
"This module defines a model for the service topology.";
revision 2018-12-18 {
description
"Initial revision.";
reference "foo";
}
identity event-type {
description
"Base identity for event type";
}
identity frequency {
description
"Base identity for frequency";
}
identity periodic {
base frequency;
description
"Identity for periodic trigger";
}
identity scheduling {
base frequency;
description
"Identity for scheduling trigger";
}
typedef match-value {
type union {
type yang:xpath1.0;
type yang:object-identifier;
type string;
}
description
"This type is used to match resources of type 'target'.
Since the type 'target' is a union of different types,
the 'match-value' type is also a union of corresponding
types.";
}
typedef target {
type union {
type instance-identifier;
type yang:object-identifier;
type yang:uuid;
type string;
}
description
"If the target is modelled in YANG, this type will
be an instance-identifier.
If the target is an SNMP object, the type will be an
object-identifier.
If the target is anything else, for example a distinguished
name or a CIM path, this type will be a string.
If the target is identified by a UUID use the uuid
type.
If the server supports several models, the presedence should
be in the order as given in the union definition.";
}
grouping start-end-grouping {
description
"A grouping that provides start and end times for
Event objects.";
leaf start {
type yang:date-and-time;
description
"The date and time when the Event object
starts to create triggers.";
}
leaf end {
type yang:date-and-time;
description
"The date and time when the Event object
stops to create triggers.
It is generally a good idea to always configure
an end time and to refresh the end time as needed
to ensure that agents that lose connectivity to
their Controller do not continue executing Schedules
forever.";
}
}
container events {
leaf min-data-object {
type uint32;
description
"Sets the minimum number for a set of data collected
or selected during the service monitoring.";
}
leaf max-data-object {
type uint32;
description
"Sets the maximum number for a set of data collected or selected
during the service monitoring.";
}
list event {
key "event-name type";
leaf event-name {
type string;
description
"Event name";
}
leaf type {
type identityref {
base event-type;
}
description
"Type of event";
}
leaf event-description {
type string;
description
"Event description";
}
leaf-list target {
type target;
description
"targeted objects";
}
leaf clear {
type boolean;
default "false";
description
"A flag indicate whether the event be closed";
}
list related-event {
key "event-name type";
leaf event-name {
type string;
description
"Event name";
}
leaf type {
type identityref {
base event-type;
}
description
"Type of event";
}
description
"List for related events";
}
uses trig:trigger-grouping;
list action {
key "action-name";
leaf action-name {
type string;
description
"Action name";
}
notification event-notification {
leaf event-name {
type leafref {
path "/events/event/event-name";
}
description
"Report the event name";
}
leaf type {
type leafref {
path "/events/event/type";
}
description
"Report the event type";
}
leaf-list target {
type target;
description
"Report the target objects";
}
description
"This notification is used to report that an operator
acted upon an Event.";
}
action set {
input {
leaf-list target {
type target;
description
"Report the target objects";
}
anydata value {
description
"Inline set content.";
}
}
}
leaf-list trigger-event {
type leafref {
path "../../event-name";
}
description
"This action trigger another event";
}
description
"List for Actions";
}
description
"List for Events";
}
description
"YANG data module for defining event triggers and
actions for network management purposes";
}
}
<CODE ENDS>
The YANG modules defined in this document MAY be accessed via the RESTCONF protocol [RFC8040] or NETCONF protocol ([RFC6241]). The lowest RESTCONF or NETCONF layer requires that the transport-layer protocol provides both data integrity and confidentiality, see Section 2 in [RFC8040] and [RFC6241]. 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 [RFC5246].
The NETCONF access control model [RFC6536] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content.
There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., config true, which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes and their sensitivity/vulnerability:
This document registers a URI in the IETF XML registry [RFC3688]. Following the format in [RFC3688], the following registration is requested to be made:
--------------------------------------------------------------------- URI: urn:ietf:params:xml:ns:yang:ietf-event Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. ---------------------------------------------------------------------
This document registers a YANG module in the YANG Module Names registry [RFC6020].
--------------------------------------------------------------------- Name: ietf-event Namespace: urn:ietf:params:xml:ns:yang:ietf-event Prefix: evt Reference: RFC xxxx ---------------------------------------------------------------------
For example, some service requires to monitoring the "in-errors" state of the interface, and if the value of "in-errors" exceeds the threshold, the event should reset the interface's enabled value to false:
<events>
<event>
<event-name>interface-state-exception</event-name>
<type>interface-exception</type>
<target>/if:interfaces/if:interface[if:name='eth1']</target>
<target>/if:interfaces/if:interface[if:name='eth2']</target>
<target>/if:interfaces/if:interface[if:name='eth3']</target>
<trigger>
<name>evaluate-in-errors</name>
<trigger-description>evaluate the number of
the packets that contained errors
</trigger-description>
<frequency>10m</frequency>
<type>threshold</type>
<test>
<threshold>
<startup>rising</startup>
<rising-value>100</rising-value>
<rising-target>/if:interfaces/if:interface[if:name='eth1']
/if:statistic/if:in-errors</rising-target>
<rising-target>/if:interfaces/if:interface[if:name='eth2']
/if:statistic/if:in-errors</trising-arget>
</threshold>
</test>
</trigger>
<action>
<name>interface-exception</name>
<event-notification>
<event-name>interface-state-exception</event-name>
<type>interface-exception</type>
<target>/if:interfaces/if:interface[if:name='eth1']</target>
</event-notification>
<set>
<target>/if:interfaces/if:interface[if:name='eth1']</target>
<interger-value>
<interfaces>
<interface>
<name>eth1</name>
<enable>false</enable>
</interface>
</interfaces>
</interger-value>
</set>
<action>
</event>
</events>
v00 - v01