Internet-Draft Energy-API October 2025
Rodriguez-Natal, et al. Expires 23 April 2026 [Page]
Workgroup:
GREEN
Internet-Draft:
draft-petra-green-api-02
Published:
Intended Status:
Informational
Expires:
Authors:
A. Rodriguez-Natal
Cisco
L. M. Contreras
Telefonica
M. Palmero
Independent Consultant
J. Lindblad
All For Eco
A. Gallego Sanchez
T-SYSTEMS

Path Energy Traffic Ratio API (PETRA)

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 23 April 2026.

Table of Contents

1. Introduction

Energy management is becoming one of the major societal goals for the next decade, and networks are one of the major consumers of energy nowadays. Energy management 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.

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. The API is agnostic to the actual hops and underlaying infrastructure that enables a path, which might change transparently to the API. This document only describes the API, the computation of the energy information to return is out of the scope of this document. While the current version of this document assumes source and destination as IP addresses, future version of this document might consider other options as well.

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.

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.
  • Carbon Intensity: How much carbon emissions are generated as a consequence of the energy consumed.
  • ...

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.

Similarly, this API could be (recursively) used to provide energy information according to the definition of Service Models in an SDN context as described in [RFC8309]. In that case, using Figure 3 in [RFC8309] as reference (below), PETRA could be used between the Controller(s) and the Network Orchestrator(s), between the Network Orchestrator(s) and the Service Orchestrator, and between the Service Orchestrator and the Customer(s).

                                                 Customer
                            ------------------   Service  ----------
                           |                  |  Model   |          |
PETRA as                   |     Service      |<-------->| Customer |
Customer Service           |   Orchestrator   |    (a)   |          |
related API                |                  |           ----------
                            ------------------
                               .          .
##########################    .            .        (b)   -----------
                             . (b)          .      ......|Application|
                            .                .     :     |  BSS/OSS  |
PETRA as                   .                  .    :      -----------
Service related API       .  Service Delivery  .   :
                         .       Model          .  :
                 ------------------    ------------------
                |                  |  |                  |
#############   |     Network      |  |     Network      |
                |   Orchestrator   |  |   Orchestrator   |
                |                  |  |                  |
                .------------------    ------------------.
PETRA as       .         :                       :        .
Network API   .          : Network Configuration :         .
            .            :        Model          :          .
      ------------     ------------     ------------    ------------
     |            |   |            |   |            |  |            |
###  | Controller |   | Controller |   | Controller |  | Controller |
     |            |   |            |   |            |  |            |
      ------------     ------------     ------------    ------------
         :              .       .                 :            :
         :             .         .      Device    :            :
         :            .           . Configuration :            :
         :            .           .     Model     :            :
     ---------     ---------   ---------     ---------      ---------
    | Network |   | Network | | Network |   | Network |    | Network |
    | Element |   | Element | | Element |   | Element |    | Element |
     ---------     ---------   ---------     ---------      ---------

While considering recursive usage, the aspect of double-counting shall also be taken into consideration. Double counting refers to the fact of counting more than once the same energy consumed. Organizations using PETRA in a recursive manner need to take appropriate measures to ensure no double-counting occurs across recursive calls to the API.

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
              +--:(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) 2025 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 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'
        }
      }
    }
*/

  revision 2025-05-12 {
    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";
    }
  }

  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 {
          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

In order to mitigate security risks, the PETRA API should implement the necessary mechanisms for authentication, secure data transfer and privacy preservation. On the other hand, in order to prevent denial of service attacks, new subsequent similar requests could be silently ignored during periods of time, or even requests from the same client could be filtered to prevent system (i.e., controller or orchestrator) affection.

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 document has been supported by the Smart Networks and Services Joint Undertaking (SNS JU) under the European Union's Horizon Europe research and innovation projects 6Green (Grant Agreement no. 101096925) and Exigence (Grant Agreement no. 101139120). The contribution of A. Gallego Sánchez to this document has been partially supported by the Smart Networks and Services Joint Undertaking (SNS JU) under the European Union's Horizon Europe research and innovation project Sustain6G (Grant Agreement no. 101191936).

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]:

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

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

[I-D.belmq-green-framework]
Claise, B., Contreras, L. M., Lindblad, J., Palmero, M. P., Stephan, E., and Q. Wu, "Framework for Energy Efficiency Management", Work in Progress, Internet-Draft, draft-belmq-green-framework-05, , <https://datatracker.ietf.org/doc/html/draft-belmq-green-framework-05>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3688]
Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, , <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, , <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, , <https://www.rfc-editor.org/info/rfc6241>.
[RFC6242]
Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, , <https://www.rfc-editor.org/info/rfc6242>.
[RFC6991]
Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, , <https://www.rfc-editor.org/info/rfc6991>.
[RFC8040]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, , <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, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8309]
Wu, Q., Liu, W., and A. Farrel, "Service Models Explained", RFC 8309, DOI 10.17487/RFC8309, , <https://www.rfc-editor.org/info/rfc8309>.
[RFC8340]
Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, , <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 energy 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.

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 energy 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 energy-efficient operation of the network.

In addition to energy considerations in SD-WAN deployments, PETRA can also be leveraged for broader energy-aware service routing. In this context, network controllers and service orchestrators, such as SD-WAN controllers, transport SDN controllers, 5G slice orchestrators, or multi-domain service orchestrators, can use PETRA metrics not only to balance latency, throughput, or load, but also to optimize path selection according to energy-efficiency objectives. For example, paths with the lowest energy-consumption could be preferred, enabling service differentiation where energy-efficient paths are explicitly prioritized. This extends the SD-WAN use case into a more general paradigm where routing decisions are jointly driven by network performance and energy impact.

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.

A.3. SLA Negotiation for Energy-Efficient Services

Another use case for PETRA could the negotiation of Service Level Agreements (SLAs) between operators and enterprise customers. By exposing PETRA-derived metrics such as energy consumption, renewable energy percentage, providers can offer differentiated SLAs that explicitly include environmental targets. This enables customers to select network services not only based on performance guarantees (e.g. latency), but also on their environmental footprint (or a combination of both). For example requesting that at least 60% of traffic be carried over renewable-powered infrastructure. Such SLAs empower customers to align their digital services with corporate energy-efficient and sustainability goals and reporting requirements, while operators can use PETRA as the trusted source of verifiable energy data.

Appendix B. Requirements for Energy Efficiency Management

The document Framework for Energy Efficiency Management [I-D.belmq-green-framework] describes a reference model for energy management. The model includes an 'API Service Interface', labeled as interface (g) in the document, which "enables access for service consumption, enabling data retrieval, control, and integration through API".

In that context, PETRA is one example of such 'API Service Interface'. In the particular case of PETRA, the API might be used to consume from the Network controller, the Domain controller, or both. Appendix A describes a few use-cases that could make use of PETRA as an 'API Service Interface' within the Framework for Energy Efficiency Management [I-D.belmq-green-framework].

Contributors


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


Alejandro Muniz

Madrid
Spain


Roland Schott
Deutsche Telekom
Deutsche-Telekom-Allee 9
64295 Darmstadt
Germany
Email: Roland.Schott@telekom.de

Authors' Addresses

Alberto Rodriguez-Natal
Cisco
Barcelona
Spain
Luis M. Contreras
Telefonica
Madrid
Spain
Marisol Palmero
Independent Consultant
Spain
Jan Lindblad
All For Eco
Adrian Gallego Sanchez
T-SYSTEMS
Madrid
Spain