Path Energy Traffic Ratio API (PETRA)
draft-petra-green-api-01
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
|---|---|---|---|
| Authors | Alberto Rodriguez-Natal , Luis M. Contreras , Alejandro Muniz , Marisol Palmero , Fernando Munoz , Jan Lindblad | ||
| Last updated | 2025-07-07 (Latest revision 2024-10-21) | ||
| Replaces | draft-petra-path-energy-api | ||
| RFC stream | (None) | ||
| Formats | |||
| 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-01
GREEN A. Rodriguez-Natal
Internet-Draft Cisco
Intended status: Informational L. M. Contreras
Expires: 8 January 2026 A. Muniz
Telefonica
M. Palmero
F. Munoz
Cisco
J. Lindblad
All For Eco
7 July 2025
Path Energy Traffic Ratio API (PETRA)
draft-petra-green-api-01
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 8 January 2026.
Copyright Notice
Copyright (c) 2025 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
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 1]
Internet-Draft Energy-API July 2025
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 . . . . . . . . . . . . . . . . . . . 8
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 8
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
8.1. Normative References . . . . . . . . . . . . . . . . . . 9
8.2. Informative References . . . . . . . . . . . . . . . . . 10
Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 10
A.1. SD-WAN . . . . . . . . . . . . . . . . . . . . . . . . . 10
A.2. Multilayer Energy Management . . . . . . . . . . . . . . 11
Appendix B. Requirements for Energy Efficiency Management . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
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 8 January 2026 [Page 2]
Internet-Draft Energy-API July 2025
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.
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 8 January 2026 [Page 3]
Internet-Draft Energy-API July 2025
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, 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).
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
| +--ro carbon-intensity? uint32
+--:(invalid-address)
+--ro invalid-address
4.2. Module Definition
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 4]
Internet-Draft Energy-API July 2025
<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 '{
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 5]
Internet-Draft Energy-API July 2025
'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'
}
}
}
*/
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";
}
leaf carbon-intensity {
type uint32;
units gCO2e/kWh;
description
"Grams of CO2 per kWh";
}
}
container energy {
description
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 6]
Internet-Draft Energy-API July 2025
"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>
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 7]
Internet-Draft Energy-API July 2025
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 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).
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
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 8]
Internet-Draft Energy-API July 2025
--------------------------------------------------------------------
8. References
8.1. Normative References
[I-D.belmq-green-framework]
Claise, B., Contreras, L. M., Lindblad, J., Palmero, M.,
Stephan, E., and Q. Wu, "Framework for Energy Efficiency
Management", Work in Progress, Internet-Draft, draft-
belmq-green-framework-04, 7 July 2025,
<https://datatracker.ietf.org/doc/html/draft-belmq-green-
framework-04>.
[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>.
[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>.
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 9]
Internet-Draft Energy-API July 2025
[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>.
[RFC8309] Wu, Q., Liu, W., and A. Farrel, "Service Models
Explained", RFC 8309, DOI 10.17487/RFC8309, January 2018,
<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, 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.
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.
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 10]
Internet-Draft Energy-API July 2025
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.
Appendix B. Requirements for Energy Efficiency Management
The document Framework for Energy Efficiency Management
[I-D.belmq-green-framework] describes a framework that comprises a
controller element. In that document, the tasks of the controller
are defined as "collection, compute and aggregate". In the context
of that framework, the controller could also expose PETRA to offer
path-related energy information. The figure below updates the one
present in [I-D.belmq-green-framework] to add an additional interface
(interface 'g') to the controller to represent the Path Traffic Ratio
API.
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 11]
Internet-Draft Energy-API July 2025
+--------------------------------------------------------------------+
| |
| (3) Network Domain Level |
| |
+--------------------------------------------------------------------+
(a) (b) (c)
Inventory Monitor +- DataSheets/DataBase
Of identity Energy | and/or via API
and Capability Efficiency | Metadata and other
^ ^ | device/component/network
| | | related information: (g)
| | | PETRA
| | | .Power/Energy related metrics API
| | | .information ^
| | | .origin of Energy Mix |
| | | .carbon aware based on location |
| | | |
| | v |
+--------------------------------------------------------------------+ |
| | |
| (2) controller (collection, compute and aggregate?) +-+
| |
+--------------------------------------------------------------------+
^ ^ ^ |
(d) | (e) | (f) | |
Inventory | Monitor power | Control | |
Capability | Proportion | (Energy saving | |
| Energy efficiency| Functionality | |
| ratio, power | Localized mgmt/ | |
| consumption, | network wide mgmt) | |
| etc) | | |
| | | v
+--------------------------------------------------------------------+
| |
| (1) Device/Component |
| |
| +---------+ +-----------+ +----------------+ +----------------+ |
| | (I) | | (II) | | (III) | | (IV) | |
| | | | | | Legacy | | 'Attached'(PoE | |
| | Device | | Component | | Device | | end Point) | |
| | | | | | | | | |
| +---------+ +-----------+ +----------------+ +----------------+ |
+--------------------------------------------------------------------+
Authors' Addresses
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 12]
Internet-Draft Energy-API July 2025
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
Marisol Palmero
Spain
Email: marisol.ietf@gmail.com
Fernando Munoz
Cisco
Madrid
Spain
Email: fmunozma@cisco.com
Jan Lindblad
All For Eco
Email: jan.lindblad+ietf@for.eco
Rodriguez-Natal, et al. Expires 8 January 2026 [Page 13]