Network Policy YANG Data Model
draft-wang-netmod-yang-policy-dm-00

Abstract

This document describes a common core YANG data model for network policies. The common core model can be augmented by additional YANG modules defining data models for policy related protocols and functions to support various different network applications (such as Constraint based Routing, Network QoS, Traffic engineering, network management etc). The core policy data model provides common building blocks for such extensions - policy information bases, policy related protocols.

Status of This Memo

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 http://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 July 30, 2015.

Copyright Notice

Copyright (c) 2015 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
• 2. Definitions and Acronyms
• 2.1. Tree Diagrams
• 3. Design of Network Policy Modules
• 3.1. The Policy-set
• 3.1.1. policy-role
• 3.2. The Policy-group
• 3.3. Policy-rule
• 4. IETF Network Policy data hierarchy
• 5. Usage Examples
• 5.1. Routing Policy
• 5.2. QoS Policy
• 6. IETF Network Policy YANG Module
• 7. Security Considerations
• 8. IANA Considerations
• 9. References
• 9.1. Normative References
• 9.2. Informative References
• Authors' Addresses

1. Introduction

The policy-controlled network modeled the network as a state machine, and use corresponding policy which may aggregate a set of policy rules to control relevant devices at any given time RFC[3060].

The Policies can either be used in a stand-alone policy rule or aggregated into policy groups functions RFC[3060]. And in order to perform more elaborate functions, RFC[3460] defines a policy set to aggregate the policy rule and policy group. And a set of conditions associated with a policy rule specifies when the policy rule is applicable. If such set of condition evaluates to TRUE, then corresponding a set of actions will be executed.

This document describes a common core YANG data model for network policies. The common core model can be augmented by additional YANG modules defining data models for policy related protocols and functions to support various different network applications (such as Constraint Based Routing, Network QoS, Traffic Engineering, MPLS management etc). The core policy data model provides common building blocks for such extensions - policy information bases, policy related protocols.

2. Definitions and Acronyms

ACL:

Access Control List

BNP:

basic network policy

QoS:

Quality of Service

YANG:

A data definition language for NETCONF

2.1. Tree Diagrams

A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows:

<status> <flags> <name> <opts> <type>

<status> is one of:
     +  for current
     x  for deprecated
     o  for obsolete


<flags> is one of:

       rw for Read/Write
       ro for ReadOnly
       -x for rpcs (remote procedure calls)
       -n for notifications


<name> is the name of the node

Each node is printed as:

<opts> is one of:

     ?  for an optional leaf or choice
     !  for a presence container
     *  for a leaf-list or list
     [<keys>] for a list's keys

<type> is the name of the type for leafs and leaf-lists

If the node is augmented into the tree from another module, its name is printed as <prefix>:<name>.

3. Design of Network Policy Modules

Policies can either be used in a stand-alone fashion which are called policy rules or aggregated into policy groups to perform more elaborate functions [RFC3060]. And in accordance with [RFC3460], policy set is inserted into the inheritance hierarchy above both policy group and policy rule. In this document, we define common core network policy yang module, and specific policies can inherit and augment from it.

This section describes common core network policy yang model structure and each separate elements:

Policy Set

It is a set of Policies which is inserted into the inheritance hierarchy above both Policy-group and Policy-Rule.

Policy Group

A policy group is used to provide a hierarchical policy definition that provides the model context or scope for each policy rule. The policy group is identified by a policy group name, and contains a set of policy rules. One Policy group can be nested within other policy group.

Policy Rule

A Policy Rule is represented by the semantics "If Condition then Action". A Policy Rule may have a priority and a precedence assigned to it. One Policy rule can be nested within other policy rules.

The following figure shows the structure of ietf-policy yang model:

module: ietf-policy
           rw policy-set!
           |  ....
           +--rw policy-group* [group-name]
           |  ....
           +--rw policy-rule*  [rule-name]
           |  ....

3.1. The Policy-set

A policy-set contain a policy-role leaf, a policy-decision-strategy leaf, a list of policy-groups and a list of policy-rules. A policy set is referred to a set of policies that can be applied to multiple same role device in the network.

The following figure shows the snippet of policy-set list:

     module: ietf-policy
            +--rw policy-set!
            |  +--rw role         role-type
            |  +--rw policy-decision-strategy  enumeration
            |  +--rw policy-group* [policy-group-name]
            |  ......
            |  +--rw policy-rule*[rules-name]
            ......

Snippet of data hierarchy related to policy-set

• The policy-decision-strategy leaf is used to specify the decision strategy for the policies. There are two matching strategy: "First-Matching" and "All-Matching." "The First- Matching strategy is used to cause the evaluation of the rules in a set such that the only actions enforced on a given examination of the Policy Set are those for the first rule that has its conditions evaluate to TRUE. The All-Matching strategy is used to cause the evaluation of all rules in a set; for all of the rules whose conditions evaluate to TRUE, the actions are enforced. " [RFC3460]
• The policy-role is an administratively specified characteristic of a managed element. As a selector for policies, it determines the applicability of the policy to a particular managed element.

3.1.1. policy-role

In RFC[4011], the policy role is described as "A role is an administratively specified characteristic of a managed element. As a selector for policies, it determines the applicability of the policy to a particular managed element. "

And some examples of policy role type has already defined in RFC[4011], such as political, financial, legal, geographical, and architectural characteristics. And in this document, the policy-role is defined as an abstract property, Specific policies can specify corresponding roles. For example, in MPLS management, one LSP can be assigned with various roles including "primary","secondary","backup","tunnel". The secondary LSP can be used to load primary LSP traffic so that network resource utilization can be banlanced. When the primary LSP fails, the backup LSP can be activiated so that network high availability can be achieved. Tunneled LSP can be used by other LSPs to provide routing service or support traffic enginneering.

3.2. The Policy-group

Policy group is a generalized aggregation list. And this list can contain a set of policy rules that belong to the same group (e.g., having the same role for various policy rules). And a policy-group list can also contains other policy-group, but are not allowed when policy-groups contain both policy-groups and policy-rules RFC[3060].

The following figure shows the snippet of policy-rule list:

module: ietf-policy
         +--rw policy-set!
            |….
            +--rw policy-group* [group-name]
               +--rw group-name                string
               +--rw group-type        bnp-group-type
               +--rw role?             role-type
               +--rw oper-data!
               |  +--ro targets*         string
               +--rw policy-rule* [rule-name]
                     ....

Snippet of data hierarchy related to policy-group

• The group-name is the identification of the policy-group. Different policy-group list is distinguished via the leaf group- name.
• The role in policy-group is an optional leaf. The role leaf have already implicit inherited policy-set role, but sometimes we need to defined a new role for a policy-group. For example, in policy-set we defined the role is "Ethernet", and in some policy-rule it may want to define another role characteristic such as "fast".
• The oper-info container contains a target leaf list. These parameters can be used to present a set of targets which the policy is applied. And the oper-date container also can be augment by some specific policy to contain relevant topology information.

3.3. Policy-rule

Policies can either be used in a stand-alone policy rule or aggregated into policy groups functions RFC[3060]. In this document we define two separated policy-rule list:

1. The hierarchy of the policy-rule is under the policy-group list.
2. The hierarchy of the policy-rule is the same as the policy-group list.

A Policy rule contains a policy-condition container and a policy-action container. And a policy-condition contains a variable container, a match container and a value container.

The following figure shows the snippet of policy-set:

module: ietf-policy   
         +--rw policy-set!
            ……
            +--rw policy-group* [group-name]
            |  +--rw group-name                string
            |  .....
            +--rw policy-rule*       [rule-name]
               +--rw rule-name       string
               +--rw rule-type       bnp-rule-type
               +--rw role?           role-type
               +--rw priority          uint32
               +--rw sequenced-actions  enumeration
               +--rw execution-strategy  enumeration
               +--rw conditions!
               |  +--rw variable!
               |  +--rw match!
               |  +--rw value!
               |  +--rw policy-time-period! 
               |     +--rw start?      yang:date-and-time
               |     +--rw end?       yang:date-and-time
               |     +--rw duration?    uint32
               +--rw action!
                  +--rw (policy-action)?
                    +--:(default-action)
                      +--rw action-null  empty

Snippet of data hierarchy related to policy-rule

• The rule-name is the identification of the policy-rule. Different policy-rule is distinguished via the leaf rule-name.
• The priority leaf indicate the priority of the policy rule. And it will be used when a single client is sending operations to accomplish multiple tasks.
• The sequenced-actions leaf is an enumeration type which can indicate the action ordering.
• The execution-strategy leaf defines the execution strategy to be used upon the sequenced actions is this policy-rule.
• The condition container include a variable container, a match container, a value container and a policy-time-period container.
• The variable container is a generalized aggregation container which can be used to contain a set of condition variable. Note that the variable may implicit in the model, and specific policies (i.e. routing policy, Traffic Engineering, QoS policy etc.) can augment this container.

augment /ietf-policy:policy-set/ietf-policy:policy-rule+
/ietf-policy:conditions/ietf-policy:variable 
+--rw qos-variable!
   +--rw qos-rsvp-variable!

• The match container is a generalized aggregation container which can be used to contain a set of condition match parameters. Note that the match may implicit in the model, and specific policies (i.e. routing policy, Traffic Engineering related policy, QoS policy etc.) can augment this container.
• The value container is a generalized aggregation container which can be used to contain a set of condition value. Note that the value may implicit in the model, and specific policies (i.e. routing policy, Traffic Engineering related policy, QoS policy etc.) can augment this container.
• The policy-time-period container include a start time leaf, an end time leaf, and a duration optional leaf.
• The actions container include policy-action choice, and in this basic policy yang model policy-action choice include a default empty case, and it can be augmented by specific policy(i.e. routing policy, Traffic Engineering related policy, QoS policy etc.).

augment /ietf-policy:policy-set/ietf-policy:policy-rule+
/ietf-policy:action/ietf-policy:policy-action:
+--:(qos-policy-action)
   +--rw qos-action!
      +--rw qos-simple-action!
      +--rw qos-discard-action!
      +--rw qos-admission-action!
      +--rw qos-phb-action!

4. IETF Network Policy data hierarchy

The following figure provide the structure of basic network policy yang

module: ietf-policy
      +--rw policy-set!
        |  +--rw role         role-type
        |  +--rw policy-decision-strategy  enumeration
        +--rw policy-rule*       [rule-name]
        |  +--rw rule-name       string
        |  +--rw rule-type       bnp-rule-type
        |  +--rw role?           role-type
        |  +--rw priority          uint32
        |  +--rw sequenced-actions  enumeration
        |  +--rw execution-strategy  enumeration
        |  +--rw conditions!
        |  |  +--rw variable!
        |  |  +--rw match!
        |  |  +--rw value!
        |  |  +--rw policy-time-period! 
        |  |     +--rw start?      yang:date-and-time
        |  |     +--rw end?       yang:date-and-time
        |  |     +--rw duration?    uint32
        |  +--rw action!
        |    +--rw (policy-action)?
        |      +--:(default-action)
        |        +--rw action-null  empty
        +--rw policy-group* [group-name]
          +--rw group-name                string
          +--rw group-type        bnp-group-type
          +--rw role?             role-type
          +--rw oper-data!
          |  +--ro targets*         string
          +--rw policy-rule*       [rule-name]
            +--rw rule-name       string
            +--rw rule-type       bnp-rule-type
            +--rw role?           role-type
            +--rw priority          uint32
            +--rw sequenced-actions  enumeration
            +--rw execution-strategy  enumeration
            +--rw conditions!
            |  +--rw variable!
            |  +--rw match!
            |  +--rw value!
            |  +--rw policy-time-period! 
            |    +--rw start?      yang:date-and-time
            |    +--rw end?       yang:date-and-time
            |    +--rw duration?    uint32
            +--rw action!
               +--rw (policy-action)?
                  +--:(default-action)
                     +--rw action-null  empty

data hierarchy of Ietf Network Policy

5. Usage Examples

5.1. Routing Policy

The following figure provide an example of use in routing policy:

augment /ietf-policy:policy-set/ietf-policy:policy-rule/ietf-policy:conditions
+/ietf-policy:variable:
+--rw routing-variable!
   +--rw prefix!
   |  +--rw address uint32
   |  +--rw masklength uint32
   |  +--rw masklengthrange uint32
   +--rw neighbor!
      +--rw address uint32   

augment /ietf-policy:policy-set/ietf-policy:policy-rule/ietf-policy:conditions
+/ietf-policy:match:
+--rw routing-match!
   +--rw match-prefix!
   +--rw match-neighbor! 

augment /ietf-policy:policy-set/ietf-policy:policy-rule/ietf-policy:action:
+--:(routing-policy-action)
   +--rw routing-action!
      +--rw accept uint32
      +--rw reject uint32

o A condition contains a variable and a value and use a match operator, to connect variable with value. And a simple condition models an elementary Boolean expression of the form "variable MATCH value" RFC[3460].

o The prefix container containan address leaf, a masklength leaf and a mask lengthrange leaf. The address leaf is used to indicate the address variable, the masklength leaf is used to indicate the length of mask, and the masklengthrange leaf is used to indicate the range for the masklength.

o The neighbor container contain an address leaf. The address leaf is used to indicate the address of neighbor.

o The match container contain a match-prefix container and a match-neighbor container. If the prefix/neighbor variable and match-prefix/mathc-prefix match success it may corresponding to a policy value. And both match-prefix and match-neighbor are abstract container that serves as the base container for all implicit match operator.

o The routing-action container contains an access leaf and a reject leaf.

5.2. QoS Policy

The following figure provide an example of use in QoS policy:

augment /ietf-policy:policy-set/ietf-policy:policy-rule/ietf-policy:conditions
+/ietf-policy:variable:
+--rw qos-variable!
   +--rw qos-rsvp-variable!

augment /ietf-policy:policy-set/ietf-policy:policy-rule/ietf-policy:conditions
+/ietf-policy:match:
+--rw qos-match!

augment /ietf-policy:policy-set/ietf-policy:policy-rule/ietf-policy:conditions
+/ietf-policy:value:
+--rw qos-value!
   +--rw qos-dn-value!
   +--rw qos-attribute-value!

augment /ietf-policy:policy-set/ietf-policy:policy-rule/ietf-policy:action:
+--:(qos-policy-action)
   +--rw qos-action!
      +--rw qos-simple-action!
      +--rw qos-discard-action!
      +--rw qos-admission-action!
      +--rw qos-phb-action!

o The qos-variable container contains a qos-rsvp-variable container. And the qos-rsvp-variable is an abstract container that serves as the base container for all implicit variables that have to do with RSVP conditioning RFC[3644].

o Sometimes the match operator is implicated, the formal notation of the SimplePolicyCondition, together with its associations, models only a pair, (<variable>, <value>) RFC[3460]. And in this example we explicit defined an abstract qos-match container that serves as the base container for all implicit match operator that have to do with qos conditinon.

o The qos-value container contains a qos-dn-value container and a qos-attribute-value container. The qos-dn-value container is used to represent a set of Distinguished Name values. A Distinguished Name can be used as a key to retrieve an object from a directory service. And the qos-attribute-value container is used to represent a set of property values for the "Value" term in a condition RFC[3644].

o The qos-policy-action case contains a qos-action container. And the qos-action container contains a qos-simple-action container, a qos-discard-action container, a qos-admission-action container and a qos-phb-action container.

o The qos-simple-action container contains the elementary action. And the qos-discard-action is used to specify that packets should be discarded. The qos-admission-action container can be used to perform admission decisions based on a comparison of a meter measuring the temporal behavior of a set of flow with a traffic profile. And the qos-phb-action is used to define the per-hop behavior that is to be assigned to behavior aggregates RFC[3644].

6. IETF Network Policy YANG Module

<CODE BEGINS> file "ietf-policy.yang"
module ietf-policy{
     yang-version 1;

     namespace "urn:TBD:params:xml:ns:yang:ietf-policy";
     prefix plc;

     import ietf-yang-types { prefix yang;}

     organization "IETF I2RS Working Group";
     contact
       "wangzitao@huawei.com";
     description
       "This module defines common core-network-policy yang data model";

     typedef bnp-group-type {
   type string;
       description "basic network group type";
     }
    typedef bnp-rule-type {
    type string;
       description "basic network policy rule type";
     }
    typedef role-type {
    type string;
       description "basic network policy role type";
     }


grouping ietf-oper-info{
container oper-info{
description
"The oper-info container contains a target leaf list. 
These parameters can be used to present a set of targets 
which the policy is applied. And the oper-date container 
also can be augment by some specific policy to contain 
relevant topology information.";
leaf-list targets{
type string;
description "This leaf list can be used to present 
a set of targets which the policy is applied.";}
}
}

grouping bnp-role{
leaf role{
description
"A role is an administratively specified characteristic of a managed element. 
As a selector for policies, it determines the applicability of the policy to 
a particular managed element.";
type role-type;
}
}
grouping ietf-policy-rule{
list policy-rule{
description
"defines a list of policy rules.";
key "rule-name";
leaf rule-name{
      type string;
      description
      "The entry-index is the identification of the policy-rule-entry list";
  }
leaf rule-type{
description
"The rule-type is used to indicate the type of the policy rule.";
type bnp-rule-type;
}
uses bnp-role;
leaf priority{
description
"The priority leaf indicate the priority of the policy rule.
And it will be used when a single client is sending operations
to accomplish multiple tasks.";
type uint32;
}

leaf sequenced-actions{
description
"This leaf gives a policy administrator a way of specifying 
the ordering of the policy actions.";
type enumeration{
enum mandatory{
description
"Do the actions in the indicated order, or don't do them at all.";}
enum recommended{
description
"Do the actions in the indicated order if you can, 
but if you can't do them in this order, do them in another order if you can.";}
enum dontCare{
description
"I don't care about the order.";}
}
}

leaf  execution-strategy{
description
"This leaf defines the execution strategy to be used 
upon the sequenced actions is this policy-rule.";
type enumeration{
enum DoUntilSuccess {
description
"execute actions according to predefined order, 
until successful execution of a single action.";}
enum DoAll{
description
"execute ALL actions which are part of the modeled set, 
according to their predefined order. Continue doing this, 
even if one or more of the actions fails.";}
enum DoUntilFailure{
description
"execute actions according to predefined order, 
until the first failure in execution of a single sub-action.";}
}
}

container conditions{
description
"define the policy conditions";
container variable{
description
"The variable container is a generalized aggregation container 
which can be used to contain a set of condition variable. 
Note that the variable may implicit in the model, 
and specific policies (i.e. routing policy, ACL, OoS policy etc.) 
can augment this container.";
}
container match{
description
"The match container is a generalized aggregation container 
which can be used to contain a set of condition match parameters. 
Note that the match may implicit in the model, 
and specific policies (i.e. routing policy, ACL, OoS policy etc.) 
can augment this container.";
}
container value{
description
"The value container is a generalized aggregation container 
which can be used to contain a set of condition value. 
Note that the value may implicit in the model, 
and specific policies (i.e. routing policy, ACL, OoS policy etc.) 
can augment this container.";
}
container policy-time-period{
leaf start{
description
"define the start time.";
type yang:date-and-time;}
leaf end{
description
"define the end time.";
type yang:date-and-time;}
leaf duration{
description
"define the duration time.";
type uint32;}
}
}
container action{
choice policy-action{
case default-action{
leaf action-null{
description
"the default action is empty, and it can be augmented by specific policies.";
type empty;
}
}
}
}
}
}

grouping ietf-policy-group{
list policy-group{
key "group-name";
leaf group-name{
description
"The group-name is the identification of the policy-group.";
type string;
}
leaf group-type{
description
"The group-type is used to indicate the type of the policy group.";
type bnp-group-type;
}
uses bnp-role;
uses ietf-oper-info;
uses ietf-policy-rule;
}
}

container policy-set{
uses bnp-role;
leaf policy-decision-strategy {
description
"The match-strategy leaf is used to specify
the matching strategy for the policies of the policy rule.
There are two matching strategy: First-Matching and All-Matching.";
type enumeration{
enum First-Matching {
description "The First-Matching strategy is used to cause
the evaluation of the rules in a set such that the only actions
enforced on a given examination of the Policy Set are those for
the first rule that has its conditions evaluate to TRUE.";}
enum All-Matching {
description " The All-Matching strategy is used to cause the
evaluation of all rules in a set; for all of the rules whose
conditions evaluate to TRUE, the actions are enforced.";}
}
}
uses ietf-policy-group;
uses ietf-policy-rule;
}
}
<CODE ENDS>

7. Security Considerations

TBD.

8. IANA Considerations

TBD.

9. References

9.1. Normative References

9.2. Informative References

Authors' Addresses