PANRG A. Rodriguez-Natal Internet-Draft Cisco Intended status: Informational L. M. Contreras Expires: 9 January 2025 A. Muniz Telefonica M. Palmero F. Munoz J. Lindblad Cisco 8 July 2024 Path Energy Traffic Ratio API (PETRA) draft-petra-path-energy-api-02 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 9 January 2025. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. Rodriguez-Natal, et al. Expires 9 January 2025 [Page 1] Internet-Draft Energy-API July 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 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 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 9 January 2025 [Page 2] Internet-Draft Energy-API July 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 9 January 2025 [Page 3] Internet-Draft Energy-API July 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 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 9 January 2025 [Page 4] Internet-Draft Energy-API July 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 9 January 2025 [Page 5] Internet-Draft Energy-API July 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 9 January 2025 [Page 6] Internet-Draft Energy-API July 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"; } } } } } } 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 9 January 2025 [Page 7] Internet-Draft Energy-API July 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, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [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, . Rodriguez-Natal, et al. Expires 9 January 2025 [Page 8] Internet-Draft Energy-API July 2024 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, . [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, . [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . 8.2. Informative References 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 9 January 2025 [Page 9] Internet-Draft Energy-API July 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 9 January 2025 [Page 10]