Skip to main content

Path Energy Traffic Ratio API (PETRA)
draft-petra-green-api-00

Document Type Active Internet-Draft (individual)
Authors Alberto Rodriguez-Natal , Luis M. Contreras , Alejandro Muniz , Marisol Palmero , Fernando Munoz , Jan Lindblad
Last updated 2024-10-21
RFC stream (None)
Intended RFC status (None)
Formats
Yang Validation 0 errors, 0 warnings
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-petra-green-api-00
GREEN                                                 A. Rodriguez-Natal
Internet-Draft                                                     Cisco
Intended status: Informational                           L. M. Contreras
Expires: 24 April 2025                                          A. Muniz
                                                              Telefonica
                                                              M. Palmero
                                                                F. Munoz
                                                             J. Lindblad
                                                                   Cisco
                                                         21 October 2024

                 Path Energy Traffic Ratio API (PETRA)
                        draft-petra-green-api-00

Abstract

   This document describes an API to query a network regarding its
   Energy Traffic Ratio for a given path.

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 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 24 April 2025.

Copyright Notice

   Copyright (c) 2024 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 1]
Internet-Draft                 Energy-API                   October 2024

   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 Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology and Requirements Notation . . . . . . . . . . . .   3
   3.  Path Energy Traffic Ratio API (PETRA) . . . . . . . . . . . .   3
     3.1.  Energy Information  . . . . . . . . . . . . . . . . . . .   3
     3.2.  Recursive Usage . . . . . . . . . . . . . . . . . . . . .   3
   4.  YANG Module . . . . . . . . . . . . . . . . . . . . . . . . .   4
     4.1.  Module Structure  . . . . . . . . . . . . . . . . . . . .   4
     4.2.  Module Definition . . . . . . . . . . . . . . . . . . . .   4
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   6.  Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .   7
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
     8.2.  Informative References  . . . . . . . . . . . . . . . . .   9
   Appendix A.  Use Cases  . . . . . . . . . . . . . . . . . . . . .   9
     A.1.  SD-WAN  . . . . . . . . . . . . . . . . . . . . . . . . .   9
     A.2.  Multilayer Energy Management  . . . . . . . . . . . . . .  10
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  10

1.  Introduction

   Sustainability is becoming one of the major societal goals for the
   next decade, and networks are one of the major consumers of energy
   nowadays.  Sustainability of network services is thus one of the
   forefronts of innovation and action from network service
   stakeholders, involving manufacturers, operators and customers.  In
   this line, there is a shared goal of achieving better energy
   awareness.

   As with any other network metric, the energy traffic ratio could be
   collected from the underlying network infrastructure.  However, there
   is not a common or single definition of energy metrics towards
   network consumers so that can be uniformly reported, particularly in
   heterogeneous network scenarios.  This document introduces an API to
   query networks about Energy Traffic Ratio.

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 2]
Internet-Draft                 Energy-API                   October 2024

2.  Terminology and Requirements Notation

   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.

3.  Path Energy Traffic Ratio API (PETRA)

   This documents describes an API to query a network about the Energy
   Traffic Ratio for a given path.  It takes as input the source and
   destination of a path along with the traffic throughput between and
   returns energy information related to the traffic on the path.  This
   is energy computed by the infrastructure that is dynamically part of
   the traffic path.  This document only describes the API, the
   computation of the energy information to return is out of the scope
   of this document.

3.1.  Energy Information

   This API allows to return a number of energy attributes associated
   with the path and the traffic.  Currently the parameters that could
   be returned as energy information as part of the query are:

   *  Watts per Gigabit: How many Watts are consumed per Gigabit of
      traffic traversing the path.

   *  Carbon Intensity: How much carbon emissions are generated as a
      consequence of the energy consumed.

   Some other parameters that could be considered as well as part of the
   energy information include:

   *  Renewable Percentage: How much of the energy consumed comes from
      renewable energy sources.

   *  ...

3.2.  Recursive Usage

   The API is envisioned in such a way that could be used recursively.
   That means, subpaths could report their energy consumption using
   PETRA and such energy consumption could be aggregated and reported
   for the overall path also using PETRA.

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 3]
Internet-Draft                 Energy-API                   October 2024

4.  YANG Module

   This is a posible definition of PETRA as a module following the YANG
   specification [RFC6020].

4.1.  Module Structure

   This section uses the graphical representation of data models defined
   in [RFC8340].

   module: ietf-petra
     +--rw energy
        +---x query
           +---w input
           |  +---w src-ip        ietf-inet-types:ip-address
           |  +---w dst-ip        ietf-inet-types:ip-address
           |  +---w throughput    uint32
           +--ro output
              +--ro (result)?
                 +--:(success)
                 |  +--ro success
                 |     +--ro watts-per-gigabit?   decimal64
                 |     +--ro carbon-intensity?    uint32
                 +--:(invalid-address)
                    +--ro invalid-address

4.2.  Module Definition

   <CODE BEGINS> file "ietf-petra@2024-07-05.yang"
   module ietf-petra {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-petra";
     prefix ietf-petra;

     import ietf-inet-types {
       prefix ietf-inet-types;
     }

     organization
       "";
     contact
       "";
     description
       "Initial YANG rendition of the PETRA Energy API, v1.0.1

       Copyright (c) 2024 IETF Trust and the persons identified as

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 4]
Internet-Draft                 Energy-API                   October 2024

       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 Revised 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 XXXX
       (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
       for full legal notices.

       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.
       ";

   /*
       If you have an implementation of this YANG module, you could
       access it like something this over RESTCONF:

       $ curl --location --request POST \
         'https://localhost:8008/restconf/operations/energy/query' \
         --header 'Content-Type: application/yang-data+json' \
         --user 'admin:admin' \
         --data-raw '{
             'input' : {
                 'src-ip': '10.10.10.10',
                 'dst-ip': '10.20.20.20',
                 'throughput': '40'
             }
           }'

       And if all goes well, you might receive (besides all the
       HTTP headers) a reply body with something like this:

       {
         'output': {
           'success': {
             'watts-per-gigabit': '191.855',
             'carbon-intensity': '108'
           }
         }
       }

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 5]
Internet-Draft                 Energy-API                   October 2024

   */

     revision 2024-07-05 {
       description
         "Initial YANG rendition of the PETRA Energy API, v1.0.1";
       reference
         "RFC XXXX: ...";
     }

     grouping energy-metrics-g {
       description
         "Grouping for query result metrics.";
       leaf watts-per-gigabit {
         type decimal64 {
           fraction-digits 3;
         }
         units W/Gb;
         description
           "Watts consumed per Gigabit transmitted";
       }
       leaf carbon-intensity {
         type uint32;
         units gCO2e/kWh;
         description
           "Grams of CO2 per kWh";
       }
     }

     container energy {
       description
         "PETRA API top level container.";
       action query {
         description
           "Query the network for energy consupmtion";
         input {
           leaf src-ip {
             type ietf-inet-types:ip-address;
             mandatory true;
             description
               "Source IP address";
           }
           leaf dst-ip {
             type ietf-inet-types:ip-address;
             mandatory true;
             description
               "Destination IP address";
           }
           leaf throughput {

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 6]
Internet-Draft                 Energy-API                   October 2024

             type uint32;
             units Gb/s;
             mandatory true;
             description
               "Throughput between source and destination
               (in gigabits per second)";
           }
         }
         output {
           choice result {
             description
               "Choice of which kind of result the query gave.";
             container success {
               description
                 "Successful operation";
               uses energy-metrics-g;
             }
             container invalid-address {
               description
                 "Invalid source/destination IP address supplied";
             }
           }
         }
       }
     }
   }
   <CODE ENDS>

5.  Security Considerations

   TBD

6.  Acknowledgments

   Kudos to Elis Lulja for his help with the OpenAPI specification in
   early versions of this draft.  Thanks to Fernando Sanz Garcia and
   Lori Jakab for their help and support on this work.  The contribution
   of Telefonica to this work has been supported by the HORIZON-JU-
   SNS2022 Research and Innovation Action project 6Green (Grant
   Agreement no.  101096925).

7.  IANA Considerations

   The IANA is requested to as assign a new namespace URI from the IETF
   XML registry.

   This document registers the following namesace URIs in the IETF XML
   registry [RFC3688]:

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 7]
Internet-Draft                 Energy-API                   October 2024

   --------------------------------------------------------------------

   URI: urn:ietf:params:xml:ns:yang:ietf-petra

   Registrant Contact: The IESG.

   XML: N/A, the requested URI is an XML namespace.

   --------------------------------------------------------------------

   This document registers the following YANG modules in the "YANG
   Module Names" registry [RFC6020]:

   --------------------------------------------------------------------

   Name: ietf-petra

   Namespace: urn:ietf:params:xml:ns:yang:ietf-petra

   Prefix: petra

   Reference: RFC XXX

   --------------------------------------------------------------------

8.  References

8.1.  Normative References

   [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>.

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 8]
Internet-Draft                 Energy-API                   October 2024

   [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>.

   [RFC6991]  Schoenwaelder, J., Ed., "Common YANG Data Types",
              RFC 6991, DOI 10.17487/RFC6991, July 2013,
              <https://www.rfc-editor.org/info/rfc6991>.

   [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>.

8.2.  Informative References

Appendix A.  Use Cases

   This section describes some use-cases where this specification might
   be useful.

A.1.  SD-WAN

   Software-Defined Wide-Area Networks (SD-WAN) have become a common way
   for enterprises to provide cost-effective connectivity across their
   different geographically distributed sites.  Typically, SD-WAN
   deployments operate as an overlay network that is established on top
   of an existing underlay connectivity network.  One aspect to consider
   is that in many SD-WAN production deployments the operator of the
   overlay network and the operator of the underlay network are
   different organizations.

   This poses an additional challenge when trying to derive
   sustainability metrics.  Even if the underlay network is instrumented
   to collect energy data, this data is opaque to the operator of the
   overlay network which has no access to underlay information.  While
   operators of underlay networks offer certain general network metrics
   to overlay operators, no interface has been defined to allow the
   overlay operator to query the underlay network for energy
   information.

Rodriguez-Natal, et al.   Expires 24 April 2025                 [Page 9]
Internet-Draft                 Energy-API                   October 2024

   In this context, the PETRA specification presented in this document
   enables the operator of the SD-WAN network to coordinate with the
   underlay operator to capture sustainability data.  This in turns
   opens further use-cases, from observability and reporting to
   potentially overlay policies based on underlay energy data, further
   enabling an overall more sustainable operation of the network.

A.2.  Multilayer Energy Management

   The concept of multilayer L3-L1 collection involves integrating data
   from different network layers to provide a comprehensive view of
   network operations.  The use case of multilayer involves collecting
   and correlating data from Layer 3 (network layer) down to Layer 1
   (physical layer).  This multilayer approach allows for better network
   performance, optimization, and troubleshooting by providing end-to-
   end visibility.

   Leveraging PETRA API for multilayer L3-L1 collection use case
   enhances energy management by providing comprehensive visibility,
   enabling optimization, and supporting proactive management.  This
   makes PETRA a useful tool for more accurate, efficient and effective
   energy management in modern networks.

Authors' Addresses

   Alberto Rodriguez-Natal
   Cisco
   Barcelona
   Spain
   Email: natal@cisco.com

   Luis M. Contreras
   Telefonica
   Madrid
   Spain
   Email: luismiguel.contrerasmurillo@telefonica.com

   Alejandro Muniz
   Telefonica
   Madrid
   Spain
   Email: alejandro.muniz@telefonica.com

Rodriguez-Natal, et al.   Expires 24 April 2025                [Page 10]
Internet-Draft                 Energy-API                   October 2024

   Marisol Palmero
   Cisco
   Madrid
   Spain
   Email: mpalmero@cisco.com

   Fernando Munoz
   Cisco
   Madrid
   Spain
   Email: fmunozma@cisco.com

   Jan Lindblad
   Cisco
   Stockholm
   Sweden
   Email: jlindbla@cisco.com

Rodriguez-Natal, et al.   Expires 24 April 2025                [Page 11]