draft-goldstein-cdni-configuration-interface-metadata-extension.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<rfc category="std" docName="draft-goldstein-cdni-configuration-interface-metadata-extension-00" updates='8006,8008' ipr="trust200902">
    <front>
        <title abbrev="CDNI Configuration Interface Metadata Extension">
            CDNI Configuration Interface Metadata Extension
        </title>
        <author fullname="Glenn Goldstein" initials="G." surname="Goldstein">
            <organization>
                Lumen Technologies
            </organization>
            <address>
                <postal>
                    <street>
                    TBD: 5177 Brandin Ct.
                    </street>
                    <city>
                    Fremont
                    </city>
                    <region>
                    CA
                    </region>
                    <code>
                        94538
                    </code>
                    <country>
                        US
                    </country>
                </postal>
                <email>
                    TBD
                </email>
            </address>
        </author>
        <date />
        <abstract>
            <t>
                Open Caching architecture is a use case of Content Delivery Networks Interconnection (CDNI) in which the
                commercial Content Delivery Network (CDN) is the upstream CDN (uCDN) and the ISP caching layer serves as the
                downstream CDN (dCDN). This document ....
            </t>
        </abstract>
    </front>
    <middle>
        <section title="Introduction">
            <t>
                The Streaming Video Alliance <xref target="SVA" format="default" /> is a global association
                that works to solve streaming video challenges in an effort to improve end-user experience
                and adoption. The Open Caching Working Group <xref target="OCWG" format="default" /> of the
                Streaming Video Alliance <xref target="SVA" format="default" /> is focused on the delegation
                of video delivery requests from commerical CDNs to a caching layer at the ISP's network.
                Open Caching architecture is a specific use case of CDNI where the commercial CDN is the
                upstream CDN (uCDN) and the ISP caching layer is the downstream CDN (dCDN).
                
                The interchange of content delivery configuration metadata between the various entities
                in the delivery ecosystem is essential for efficient interoperability. The need for an
                industry-standard API and metadata model becomes increasingly important as content
                and service providers automate more of their operations, and as technologies, such as
                open caching, require coordination of content delivery configurations. In order to achives that, the 
                <xref target="OC-CI"> TBD: Open Caching Configuration Interface Specification </xref> defines 
                an interface contemplating a set of use cases. 
                This document defines and registers CDNI Metadata objects (as defined at section 4 of <xref target="RFC8006" />). 
            </t>
            <t>
                For consistency with other CDNI documents this document follows the
                CDNI convention of uCDN (upstream CDN) and dCDN (downstream CDN) to represent the commercial CDN and ISP caching
                layer respectively.
            </t>
            <t>
                This document registers the following CDNI Payload Types (section 7.1 of
                <xref target="RFC8006" />). Some also being used a capability objects (extending section 5 in <xref target="RFC8008" />)
                <list style="symbols">
                    <t>
                        TBD
                    </t>
                </list>
            </t>
            <section anchor="terminology" title="Terminology">
                <t>
                    The following terms are used throughout this document:
                    <list style="symbols">
                        <t>
                            CDN - Content Delivery Network
                        </t>
                    </list>
                </t>
                <t>
                    Additionally, this document reuses the terminology defined in
                    <xref target="RFC6707" />,
                    <xref target="RFC7336" />,
                    <xref target="RFC8006" />,
                    <xref target="RFC8007" />,
                    <xref target="RFC8008" />, and
                    <xref target="RFC8804" />.
                    Specifically, we use the following CDNI acronyms:
                    <list style="symbols">
                        <t>
                            uCDN, dCDN - Upstream CDN and Downstream CDN respectively (see
                            <xref target="RFC7336" />
                            )
                        </t>
                    </list>
                </t>
            </section>
            <section title="Requirements Language">
                <t>
                    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
                    <xref target="RFC2119" />
                    <xref target="RFC8174" />
                    when, and only when, they appear in all capitals, as shown here.
                </t>
            </section>
        </section>
        <section anchor="cdni-additional-metadata-payload-types" title="CDNI Additonal Metadata Payload Types">
            <t>
                Section 4 of <xref target="RFC8006" /> defines various Metadata Payload Types. 
                Below we define additional Metadata Payload Types Objects. 
            </t>
            <t>
                Note: In the following sections, the term "mandatory-to-specify" is
                used to convey which properties MUST be included when serializing a
                given capability object.  When mandatory-to-specify is defined as
                "Yes" for an individual property, it means that if the object
                containing that property is included in an FCI message, then the
                mandatory-to-specify property MUST also be included.
            </t>
            <section anchor="telemetry-payload-type" title="Telemetry Payload type">
                <t>
                    The Telemetry Payload type is used to define a list of telemetry sources made available by the dCDN 
                    to the uCDN.
                </t>
                <t><list style="empty">
                    <t>Property: sources<list style="empty">
                        <t>Description: Telemetry sources made available to the uCDN.</t>
                        <t>Type: A JSON array of Telemetry Source objects (see <xref target="telemetry-source-object"/>).</t>
                        <t>Mandatory-to-Specify: Yes.</t>
                    </list></t>
                </list></t>

                <section anchor="telemetry-source-object" title="Telemetry Source Object">
                    <t>
                        The Telemetry Source Object is build of an associated type, a list of exposed metrics, and type-specific configuration data.
                    </t>

                    <t><list style="empty">
                        <t>Property: id<list style="empty">
                            <t>Description: A unique identifier.</t>
                            <t>Type: String.</t>
                            <t>Mandatory-to-Specify: Yes.</t>
                        </list></t>

                        <t>Property: type<list style="empty">
                            <t>Description: A valid telemetry source type. See <xref target="telemetry-source-type"/>.</t>
                            <t>Type: String.</t>
                            <t>Mandatory-to-Specify: Yes.</t>
                        </list></t>

                        <t>Property: metrics<list style="empty">
                            <t>Description: The metrics exposed by this source.</t>
                            <t>Type: A JSON array of Telemetry Source Metric objects (see <xref target="telemetry-source-metric-object"/>).</t>
                            <t>Mandatory-to-Specify: Yes.</t>
                        </list></t>

                        <t>Property: configuration<list style="empty">
                            <t>Description: Type specific configuration data.</t>
                            <t>Type: TBD.</t>
                            <t>Mandatory-to-Specify: No.</t>
                        </list></t> 
                    </list></t>
                    <section anchor="telemetry-source-type" title="Telemetry Source Types">
                        <t>
                            Below are listed the valid telemetry source types.
                            TBD: How do we extend this list? Do we need a registry? 
                        </t>
                        <texttable>
                            <ttcol align="left">
                                Source Type
                            </ttcol>
                            <ttcol align="left">
                                Description
                            </ttcol>                            
                            <c>generic</c><c>TBD</c>
                        </texttable>
                    </section>
                    <section anchor="telemetry-source-metric-object" title="Telemetry Source Metric Object">
                        <t>
                            The Telemetry Source Metric Object describe the metric to be exposed.
                        </t>
                        <t><list style="empty">
                            <t>Property: name<list style="empty">
                                <t>Description: An identifier unique within this telemetry source.</t>
                                <t>Type: String.</t>
                                <t>Mandatory-to-Specify: Yes.</t>
                            </list></t>

                            <t>Property: time-granularity<list style="empty">
                                <t>Description:  Represents the time frame that the data represents in seconds.  I.e. is this a data set over 5 minutes, one hour, etc..</t>
                                <t>Type: Float (or Integer - TBD).</t>
                                <t>Mandatory-to-Specify: No.</t>
                            </list></t>

                            <t>Property: data-percentile<list style="empty">
                                <t>Description: The percentile calculation the data represents, i.e. 50 percentile would equate to the average over the time-granularity.</t>
                                <t>Type: Float (or Integer - TBD).</t>
                                <t>Mandatory-to-Specify: No.</t>
                            </list></t>

                            <t>Property: latency<list style="empty">
                                <t>Description: Time in second that the data is behind of real time.</t>
                                <t>Type: Float (or Integer - TBD).</t>
                                <t>Mandatory-to-Specify: No.</t>
                            </list></t> 
                        </list></t>
                    </section>
                </section>
                <section anchor="telemetry-payload-type-serialization" title="Telemetry Payload type Serialization">
                    <t>
                        TBD
                    </t>
                    <figure>
                        <artwork>
<![CDATA[
"capabilities": [
  {
    "capability-type": "FCI.Telemetry",
    "capability-value": {
      "sources": [
        {
          "id": "capacity_metrics_region1",
          "type": "generic",
          "metrics": [
            {
              "name": "egress_5m",
              "time-granularity": 300,
              "data-percentile": 50,
              "latency": 1500
            },
            {
              "name": "requests_5m",
            }
          ]
        }
      ]
    },
    "footprints": [
      <footprint objects>
    ]
  }
]
]]>
                        </artwork>
                    </figure>
                </section>
            </section>
        </section>
        <section anchor="cdni-additional-capability-objects" title="CDNI Additonal Capability Objects">
            <t>
                Section 5 of <xref target="RFC8008" /> describes the FCI Capability Advertisement Object, which
                includes a CDNI Capability Object as well as the capability object type (a CDNI Payload Type). 
                The section also defines the Capability Objects per such type. Below we define additional Capability Objects. 
            </t>
            <t>
                Note: In the following sections, the term "mandatory-to-specify" is
                used to convey which properties MUST be included when serializing a
                given capability object.  When mandatory-to-specify is defined as
                "Yes" for an individual property, it means that if the object
                containing that property is included in an FCI message, then the
                mandatory-to-specify property MUST also be included.
            </t>
            <section anchor="capacity-limits-capability-object" title="CapacityLimits Capability Object">
                <t>
                    The Capacity Limits Capability Object represents the limits to be advertised based on a particular Telemetry element..
                </t>
                <t><list style="empty">
                    <t>Property: total-limits-host<list style="empty">
                        <t>Description:The "Distinguished CDN-Domain" used for adjustment of the total limits.</t>
                        <t>Type: String.</t>
                        <t>Mandatory-to-Specify: No. Required only if MI.RequestedCapacityLimits is supported.</t>
                    </list></t>

                    <t>Property: total-limits<list style="empty">
                        <t>Description: The top level limits for the footprint.</t>
                        <t>Type: A JSON array of Capacity Limit objects (see <xref target="capacity-limit-object"/>).</t>
                        <t>Mandatory-to-Specify: Yes.</t>
                    </list></t>

                    <t>Property: host-limits<list style="empty">
                        <t>Description: Limits for particular CDN Domains.</t>
                        <t>Type: A JSON array of Capcity Limit objects (see <xref target="capacity-limit-object"/>).</t>
                        <t>Mandatory-to-Specify: No.</t>
                    </list></t>
                </list></t>

                <section anchor="capacity-limit-object" title="Capacity Limit Object">
                    <t>
                        The Capacity Limit Object is built of TBD.
                    </t>
                    <t><list style="empty">
                        <t>Property: limit-type<list style="empty">
                            <t>Description: The units of maximum-hard and maximum-soft.</t>
                            <t>Type: String. One of the values listed in <xref target="capacity-limit-type"/>.</t>
                            <t>Mandatory-to-Specify: Yes.</t>
                        </list></t>

                        <t>Property: maximum-hard<list style="empty">
                            <t>Description: The maximum unit of capacity that is available for use.</t>
                            <t>Type: Float (or Integer - TBD).</t>
                            <t>Mandatory-to-Specify: Yes.</t>
                        </list></t>

                        <t>Property: maximum-soft<list style="empty">
                            <t>Description: A soft limit at which an upstream should consider deducing traffic to prevent hitting the hard limit.</t>
                            <t>Type: Float (or Integer - TBD).</t>
                            <t>Mandatory-to-Specify: No.</t>
                        </list></t>

                        <t>Property: telemetry-source<list style="empty">
                            <t>Description: Mapping of each a particular limit to a specific metric with relevant real-time data provided by a telemetry source.</t>
                            <t>Type: Capcity Limit Telemetry Source object (see <xref target="capacity-limit-telemetry-source-object"/>).</t>
                            <t>Mandatory-to-Specify: No.</t>
                        </list></t> 

                        <t>Property: host<list style="empty">
                            <t>Description: The CDN Domain to which the limit applies.</t>
                            <t>Type: String.</t>
                            <t>Mandatory-to-Specify: Only when is part of the host-limits list.</t>
                        </list></t>
                    </list></t>
                    <section anchor="capacity-limit-type" title="Capacity Limit Types">
                        <t>
                            Below are listed the valid capacity limit types.
                            TBD: How do we extend this list? Do we need a registry? Maybe omit this list and make it subject ot bootstrapping?
                        </t>
                        <texttable>
                            <ttcol align="left">
                                Limit Type
                            </ttcol>
                            <ttcol align="left">
                                Units
                            </ttcol>                            
                            <c>egress</c><c>Bits per second</c>
                            <c>requests</c><c>Requests per second</c>
                            <c>storage-size</c><c>Total bytes</c>
                            <c>storage-objects</c><c>Count</c>
                            <c>sessions</c><c>Count</c>
                            <c>cache-size</c><c>Total bytes</c>
                        </texttable>
                    </section>
                    <section anchor="capacity-limit-telemetry-source-object" title="Capacity Limit Telemetry Source  Object">
                        <t>
                            The Capacity Limit Telemetry Source Object refers to a specific metric within a Telementry Source.
                        </t>
                        <t><list style="empty">
                            <t>Property: id<list style="empty">
                                <t>Description: Reference to the "id" of a telemetry source defined by a Telemetry Capability object.</t>
                                <t>Type: String.</t>
                                <t>Mandatory-to-Specify: Yes.</t>
                            </list></t>

                            <t>Property: metric<list style="empty">
                                <t>Description:  Reference to the "name" property of a metric as defined for the referenced telemetry source.</t>
                                <t>Type: String.</t>
                                <t>Mandatory-to-Specify: Yes.</t>
                            </list></t>
                        </list></t>
                    </section>
                </section>
                <section anchor="capacity-limit-object-serialization" title="Capacity Limit Object Serialization">
                    <t>
                        The following shows an example of ... TBD.
                    </t>
                    <figure>
                        <artwork>
<![CDATA[
"capabilities": [
  {
    "capability-type": "FCI.CapacityLimits"
    "capability-value": {
      "total-limits-host": "op-b.op-a.com",
      "total-limits": [
        {
          "limit-type": "egress",
          "maximum-hard": 50000000000,
          "maximum-soft": 25000000000,
          "telemetry-source": {
            "id": "capacity_metrics_region1",
            "metric": "egress_5m"
          }
        }
      ],
      "host-limits": [
        {
          "host": "serviceA.cdn.example.com",
          "limits": [
            "limit-type": "egress",
            "maximum-hard": 20000000000,
            "maximum-soft": 10000000000,
            "telemetry-source": {
              "id": "capacity_metrics_region1",
              "metric": "egress_service2_5m"
            }
          ]
        },
        {
          "host": "serviceB.cdn.example.com",
          "limits": [
            "limit-type": "egress",
            "maximum-hard": 30000000000,
            "maximum-soft": 15000000000,
            "telemetry-source": {
              "id": "capacity_metrics_region1",
              "metric": "egress_service2_5m"
            }
          ]
        }
      ]
    },
    "footprints": [
      <footprint objects>
    ]
  }
]
]]>
                        </artwork>
                    </figure>
                </section>
            </section>
        </section>
        <section anchor="IANA" title="IANA Considerations">
            <section anchor="IANA.cdni.payload.types" title="CDNI Payload Types">
                <t>
                    As described in section 7.1 of
                    <xref target="RFC8006" />
                    , the "CDNI Payload Types" subregistry
                    was created within the "Content Delivery Network Interconnection (CDNI) Parameters" registry (TBD verify name or omit extra info). The created
                    namespace defines the valid Payload Types, and is already populated with the types
                    described in Section 7.1 of <xref target="RFC8006" /> as well as the types described in section 6.1
                    of <xref target="RFC8008" />.
                </t>
                <t>
                    This document requests the registration of the two additional payload types:
                </t>
                <texttable>
                    <ttcol align="left">
                        Payload Type
                    </ttcol>
                    <ttcol align="left">
                        Specification
                    </ttcol>
                    <c>MI.Telemetry</c><c>RFCthis</c>
                    <c>FCI.CapacityLimits</c><c>RFCthis</c>
                </texttable>
                <t>
                    [RFC Editor: Please replace RFCthis with the published RFC
                    number for this document.]
                </t>
                <section anchor="IANA.cdni.mi.telemetry.payload.type" title="CDNI MI Telemetry Payload Type">
                    <t><list style="empty">
                        <t>Purpose: The purpose of this Payload Type is TBD 
                        (maybe: to list the supported telemetry sources and the metrics made available by each source).</t>
                        <t>Interface: FCI.</t>
                        <t>Encoding: See section <xref target="telemetry-payload-type"/>.</t>
                    </list></t>
                </section>
                <section anchor="IANA.cdni.fci.capacity.limits.payload.type" title="CDNI FCI Capacity Limits Payload Type">
                    <t><list style="empty">
                        <t>Purpose: The purpose of this Payload Type is TBD 
                        (maybe: defines Capacity Limits based on a set of defined limit types and a mapping from 
                        those limits to corresponding telemetry sources for supporting real-time metrics).</t>
                        <t>Interface: FCI.</t>
                        <t>Encoding: See section <xref target="capacity-limits-capability-object"/>.</t>
                    </list></t>
                </section>
            </section>
        </section>
        <section anchor="Security" title="Security Considerations">
            <t>
                This specification is in accordance with the CDNI Request Routing:
                Footprint and Capabilities Semantics. As such, it is subject to the security and privacy considerations as
                defined in Section 8 of
                <xref target="RFC8006" />
                and in Section 7 of
                <xref target="RFC8008" />
                respectively.
            </t>
            <t> MORE - TBD </t>
        </section>
        <section anchor="Acknowledgements" title="Acknowledgements">
            <t>
                The authors would like to express their gratitude to TBD for TBD (their guidance / contribution / reviews ...)
            </t>
        </section>
    </middle>
    <back>
        <references title="Normative References">
            <?rfc include="reference.RFC.2119"?>
            <?rfc include="reference.RFC.8006"?>
            <?rfc include="reference.RFC.8007"?>
            <?rfc include="reference.RFC.8008"?>
            <?rfc include="reference.RFC.8174"?>
            <?rfc include="reference.RFC.8804"?>
        </references>

        <references title="Informative References">
            <?rfc include="reference.RFC.6707"?>
            <?rfc include="reference.RFC.7336"?>
            <reference anchor="SVA" target="https://www.streamingvideoalliance.org">
                <front>
                    <title>
                        Streaming Video Alliance Home Page
                    </title>
                    <author />
                    <date />
                </front>
            </reference>
            <reference anchor="OCWG" target="https://www.streamingvideoalliance.org/technical-groups/open-caching/">
                <front>
                    <title>
                        Open Caching Home Page
                    </title>
                    <author />
                    <date />
                </front>
            </reference>
            <reference anchor="OC-CI" target="https://www.streamingvideoalliance.org/books/open-cache-request-routing-functional-specification/">
                <front>
                    <title>
                        Open Caching - Configuration Interface Functional Specification (TBD: write it and fix the reference)
                    </title>
                    <author initials="O." surname="Finkelman" fullname="Ori Finkelman" role="editor">
                        <organization>
                            Qwilt
                        </organization>
                    </author>
                    <author initials="J." surname="Hofmann" fullname="Jason Hofmann">
                        <organization>
                            Limelight Networks
                        </organization>
                    </author>
                    <author initials="E." surname="Klein" fullname="Eric Klein">
                        <organization>
                            Disney Streaming Services
                        </organization>
                    </author>
                    <author initials="S." surname="Mishra" fullname="Sanjay Mishra">
                        <organization>
                            Verizon
                        </organization>
                    </author>
                    <author initials="K." surname="Ma" fullname="Kevin J. Ma">
                        <organization>
                            Disney Streaming Services
                        </organization>
                    </author>
                    <author initials="D." surname="Sahar" fullname="Dan Sahar">
                        <organization>
                            Qwilt
                        </organization>
                    </author>
                    <author initials="B." surname="Zurat" fullname="Bill Zurat">
                        <organization>
                            Disney Streaming Services
                        </organization>
                    </author>
                    <date day="4" month="October" year="2019" />
                </front>
                <seriesInfo name="Version" value="1.1" />
            </reference>
        </references>
    </back>
</rfc>