Internet DRAFT - draft-liu-cdni-metadata-interface
draft-liu-cdni-metadata-interface
CDNI Working Group Xiaomei Liu
Internet Draft Lakshminarayanan Gunaseelan
Intended status: Standards Track Xiaoyan He
Expires: June 2012 Jincheng Li
Huawei
December 20, 2011
Content Distribution Network Interconnection (CDNI) Metadata Interface
draft-liu-cdni-metadata-interface-01.txt
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), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
This Internet-Draft will expire on June 20, 2009.
Copyright Notice
Copyright (c) 2011 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
(http://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
Liu & Guna Expires June 12, 2012 [Page 1]
Internet-Draft CDNI Metadata Interface December 2011
respect to this document. Code Components extracted from this
document must include Simplified BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Simplified BSD License.
Abstract
The Metadata Interface is one of the core interfaces defined by the
IETF Content Distribution Network Interconnection (CDNI) Working
Group. The primary function of the CDNI Metadata Interface is to
allow interconnected CDNs to communicate metadata in order to ensure
content delivery and content acquisition. This document defines the
metadata exchange protocol between an upstream CDN and a downstream
CDN for the content delivery. It also defines metadata objects
especially condition metadata object for CDNI.
Table of Contents
1. Introduction ................................................ 3
1.1. Terminology ............................................ 3
2. CDNI Metadata Data Model .................................... 4
3. Metadata Extensibility ...................................... 5
4. Metadata Exchange Framework .................................. 5
4.1. Pre-positioned CDNI metadata acquisition ................ 5
4.2. Metadata delivery mechanism ............................. 6
4.3. Metadata encoding ...................................... 7
5. Metadata Objects Description ................................. 7
5.1. Domain Metadata Group Definition ........................ 7
5.1.1. Content origin object .............................. 7
5.1.2. Cache miss behavior Object ......................... 8
5.1.3. Cache control Object ............................... 9
5.1.4. Cache TTL Object ................................... 9
5.1.5. Downstream Cache TTL Object ........................ 9
5.1.6. Cache key Object .................................. 10
5.1.7. Access control Object ............................. 10
5.1.8. User authorization Object ......................... 11
5.1.9. Asset valid time window Object .................... 11
5.1.10. Rate limit Object ................................ 11
5.2. Condition Metadata Group Definition .................... 12
5.2.1. Condition Object .................................. 12
5.2.2. Condition Metadata Object
......................... 14
5.2.3. Examples ......................................... 14
5.3. Error Handling ........................................ 16
6. Examples ................................................... 17
7. Security Considerations .................................... 20
8. IANA Considerations ........................................ 20
Liu & Guna Expires June 12, 2012 [Page 2]
Internet-Draft CDNI Metadata Interface December 2011
9. References ................................................. 20
9.1. Normative References................................... 20
9.2. Informative References ................................. 20
10. Acknowledgments ........................................... 21
1. Introduction
The key functions of the CDNI metadata are for the upstream CDN
(uCDN) to control the content distribution of the downstream CDN
(dCDN). These functions of the metadata can be further divided into
the following areas:
O Content origin: it identifies where the content is located for a
delivery service. The content origin specification must support
multiple content origins for a delivery service with different
redundancy schemes. When a content origin requires authentication,
the authentication metadata should also be included.
O Cache control policy: it controls the caching behavior of a
downstream CDN. This includes whether to cache or not cache
certain content, cache miss behavior (redirect or proxy through),
cache key modification, cache TTL and downstream cache TTL.
O Access control: it defines restriction for content delivery. This
includes content availability time window, geo-blocking and user
authorization.
O Delivery policy: it further controls the content delivery such as
the rate limit.
This document focuses on enabling of the CDNI Metadata interface,
which includes definition of the CDNI metadata exchanging protocol,
CDNI metadata objects, especially the condition metadata, which
provides great flexibility to refine the application scope of a
metadata.
1.1. Terminology
This document reuses the terminology defined in [I-D.draft-cdni
problem-statement].
This document also uses the following terms:
Delivery Domain: In CDN services, each delivery service is uniquely
identified by a delivery domain. This is the hostname/CNAME accessed
by end users for a delivery of content. This is usually the default
metadata application scope for content distribution metadata.
Liu & Guna Expires June 12, 2012 [Page 3]
Internet-Draft CDNI Metadata Interface December 2011
Domain Metadata: The metadata whose application scope is a delivery
domain, there is no any other additional condition to limit when or
where to apply this metadata.
Condition Metadata: The metadata which will only take effect when
certain conditions represented by a list of condition objects are
met. This kind of metadata has the precedence over the domain
metadata.
2. CDNI Metadata Data Model
The data model proposed in this document for CDNI is shown in the
following Figure 1. It includes a top level object Delivery Domain,
the metadata describing the Delivery Domain are further grouped into
domain metadata group and condition metadata group.
+-------------------+ 1
| Delivery Domain +-----------------+
+---------+---------+ |
|1 |
| |0...*
|1 |
+-----------+-----------+ +-------------+------------------------------+
| +-------------------+ | |+-------------------+ +-------------------+ |
| |DomainMetadataList | | || Conditions | |ConditionMetadataList|
| +---------+---------+ | |+---------+---------+ +---------+---------+ |
| |1 | | |1 |1 |
| | | | | | |
| |1...* | | |1...* |1...* |
| +---------+---------+ | |+---------+---------+ +---------+---------+ |
| | MetadataObject | | || ConditionObject | | MetadataObject | |
| +---------+---------+ | |+---------+---------+ +---------+---------+ |
|Domain Metadata Group | | Condition Metadata Group |
+-----------------------+ +--------------------------------------------+
Figure 1: CDNI Metadata Data Model
A Domain metadata group is a list of metadata objects with the
default metadata scope of a delivery domain. This draft proposes a
list of such objects in section 5.1.
A condition metadata group includes a list of rule match conditions,
and a corresponding list of metadata that takes effect if the
conditions are met. This is proposed to supports finer control of
the downstream CDN beyond the default metadata scope.
When multiple conditions are included in a condition metadata group,
these conditions are used in a AND relation. When the same metadata
is defined in both the domain metadata group and a condition
Liu & Guna Expires June 12, 2012 [Page 4]
Internet-Draft CDNI Metadata Interface December 2011
metadata group with matching conditions, the condition metadata
takes precedence over the default metadata.
In addition, multiple condition metadata groups can be used, in this
case all these condition metadata groups are evaluated in the order
received. If a metadata is defined in multiple condition metadata
groups, and last condition metadata group with matching conditions
takes effect.
Rule matching operation can be performed on the following
information:
URI in a content request
User agent header in a content request
Referrer header in a content request
Request arrival time
Requesting client's information, e.g. IP address
3. Metadata Extensibility
Metadata extensions to support proprietary data by the CDN providers
should be allowed in the CDNI metadata interface. This document
proposes that the name of such an extended metadata object should
start with "X-". A downstream CDN that does not support the extended
metadata should signal the unsupported metadata object in the
response as described in section 5.3 error handling of this document.
4. Metadata Exchange Framework
4.1. Pre-positioned CDNI metadata acquisition
In the CDNI framework, an upstream CDN directly contracts with
content providers for the delivery of content. A downstream CDN
delivers the content on behalf of the upstream CDN. An upstream CDN
may utilize multiple downstream CDNs for the delivery of content.
Taken this into account, the metadata for the delivery of a given
content can be different for different downstream CDNs. Therefore,
it is efficient for the content distribution metadata to be pushed
from the uCDN to the dCDN.
This document focuses on the pre-positioned CDNI metadata
acquisition as defined in requirement draft [5] in this first
version, i.e. metadata should be pushed from the upstream CDN to the
Liu & Guna Expires June 12, 2012 [Page 5]
Internet-Draft CDNI Metadata Interface December 2011
downstream CDN before the start of a delivery service, and will
consider the Dynamic CDNI metadata acquisition in a future version.
4.2. Metadata delivery mechanism
The HTTP web service model is used for the metadata exchange through
this document. The RESTful design is proposed for the management of
metadata service. With a RESTful model, HTTP is used as the
underline message transport protocol. Four HTTP methods are used for
the metadata exchange:
POST metadata creation
GET metadata read
PUT metadata update
DELETE metadata delete
In the RESTful design, a resource is identified by a URI. For the
CDNI metadata interface, each downstream CDN exposes a metadata
interface URL. For example, the metadata interface for the
downstream CDN is:
http(s)://CDNi.dCDN.com/metadata/resource
Each resource created will be identified by a resource identifier.
In the metadata interface, the resource identifier is the same as
the delivery domain FQDN. For example,
http://CDNi.dCDN.com/metadata/www.cp1.com
represents the URI that is used to access metadata for the delivery
service with a delivery domain name of www.cp1.com
To summarize, the metadata interface has the following mappings of
the RESTful web service design:
Client -- is the upstream CDN
Server -- is the downstream CDN
Resource -- delivery domain metadata
The downstream CDN provides a service access point to the upstream
CDN. The metadata resource is considered to be located at the
Liu & Guna Expires June 12, 2012 [Page 6]
Internet-Draft CDNI Metadata Interface December 2011
downstream CDN. The upstream CDN uses the metadata interface to
create/read/update/delete metadata resources identified by the URI.
4.3. Metadata encoding
Metadata encoding must support parameter value pair, listed values
as well as structure and hierarchical data types. JSON is proposed
for the metadata encoding for its flexibility in supporting the
above requirements.
In the JSON encoded message body, the domain metadata group is
encoded first and then the condition metadata group is encoded.
5. Metadata Objects Description
5.1. Domain Metadata Group Definition
The definition of the domain metadata group is as follows:
{
"domainMetaDataList": [
metadataObject1,
metadataObject2,
...
metadataObjectn]
}
where the metadataObject is of one of the metadata object types
defined later in section 5.1.1 to 5.1.10.
The following metadata objects are defined as the mandatory metadata
for the CDNI metadata interface. In order to support a list of
metadata objects with different object types, each metadata object
is identified by the metadataType field, which is the first field of
the metadata object.
5.1.1. Content origin object
Content origin object defines the content origin for a delivery
service.
{
"metaDataType": "contentOrigin",
"object": {
"origins": [
Liu & Guna Expires June 12, 2012 [Page 7]
Internet-Draft CDNI Metadata Interface December 2011
{
"location": "LOCATION",
"authentication": {
"type": "TYPE",
"username": "NAME",
"password": "PASSWORD"
}
},
],
"redundancy": "OPTION"
}
}
Where LOCATION is the FQDN of the origin server
The embedded authentication object defines the authentication
information for an origin server. If no authentication is required
by an origin server, the authentication object is null using JSON
notation. In the authentication object definition,
TYPE is "basic"|"digest" for HTTP basic and HTTP digest
authentication type
NAME is the string representation of username parameter of the
authentication object
PASSWORD is the string representation of password parameter of
the authentication type
Content origin supports a list of origin servers. The redundancy
scheme supported OPTIONs are:
"allActive" if all origins are actively used
"priority" for priority based failover with the origin listed
in decreasing priority
5.1.2. Cache miss behavior Object
This metadata defines the cache miss behavior of the CDN. The CDN can
redirect the request to a different location or pass throuth the
request to the content origin.
{
"metadataType": "cacheMissBehavior",
Liu & Guna Expires June 12, 2012 [Page 8]
Internet-Draft CDNI Metadata Interface December 2011
"object": {
"cacheMiss": "OPTION",
"URL": "value"
}
}
where OPTION is "redirect" | "passThru". The URL field is only
relevant if the option is redirect.
5.1.3. Cache control Object
This metadata defines if cache is turned on or off by the CDN
{
"metadataType":"cacheControl",
"object":{
"cache":"OPTION"
}
}
where OPTION is "on" | "off".
5.1.4. Cache TTL Object
This metadata controls how long content is stored in the CDN cache
before the content freshness is revalidated.
{
"metadataType": "cacheTTL",
"object": {
"TTL": "value"
}
}
where the value is a integer number of seconds.
5.1.5. Downstream Cache TTL Object
This metadata controls how the browser cache the content via cache
control header in an HTTP response from the CDN to the client
{
"metadataType": "downstreamCacheTTL",
Liu & Guna Expires June 12, 2012 [Page 9]
Internet-Draft CDNI Metadata Interface December 2011
"object": {
"TTL": "value"
}
}
where the value is a integer number of seconds.
5.1.6. Cache key Object
By default, CDN caches content based on the entire URI. Cache key
mask can be used to exclude portions of the URI for the generation
of cache key.
{
"metadataType": "cacheKey",
"object": {
"key": "value"
}
}
Where the value is a regex string. Here is an example:
http://dCDN.example.com/movie?cid=abcde&user=xxx&token=yyy
In this example, the "user" field of the query is removed from the
cache key. The regex replacement can be used as:
"s/(.*)user.*(token.*)/$1$2/"
5.1.7. Access control Object
This metadata defines whether to allow or deny a content request
{
"metadataType": "accessControl",
"object": ,
{
"action": "OPTION"
}
}
where OPTION is "allow" | "deny".
Liu & Guna Expires June 12, 2012 [Page 10]
Internet-Draft CDNI Metadata Interface December 2011
5.1.8. User authorization Object
This metadata defines the user authorization information a content
request.
{
"metadataType": "userAuthorization",
"object": {
"type": "TYPE",
"algorithm": "ALGORITHM",
"keyType": "KEYTYPE",
"key": "value"
}
}
where TYPE is "urlSigning" | "urlToken"
ALGORITHM is "MD5" | "SHA1".
KEYTYPE is "symmetric" | "asymmetric".
value is the public key if the keyType is "asymmetric".
5.1.9. Asset valid time window Object
This metadata defines the content distribution time window. The CDN
will only delivery the content if the request is within the asset
window.
{
"metadataType": "assetWindow",
"object": {
"start": "time",
"end": "time"
}
}
The time format is defined by HTTP 1.1. For example: Sun, 06 Nov
1994 08:49:37 GMT.
5.1.10. Rate limit Object
This metadata defines the CDN distribution aggregate bandwidth
limitation.
Liu & Guna Expires June 12, 2012 [Page 11]
Internet-Draft CDNI Metadata Interface December 2011
{
"metadataType": "rateLimit",
"object": {
"limit": "value"
}
}
Where value is in the unit of kbps.
5.2. Condition Metadata Group Definition
The condition metadata group encapsulation is as follows:
{
"conditions", [
conditionObject1,
conditionObject2,
...,
conditionObjectN ],
"ConditionMetadataList", [
metadataObject1,
metadataObject2,
...
metadataObjectn ]
}
Where the conditionObject is of one of the metadata condition object
type defined in section 5.2.1 and metadataObject is of one of the
metadata object type defined in section 5.1.1 to section 5.1.10.
Multiple condition metadata groups can exist in the metadata
interface and an example can be found in the example of section 6.
5.2.1. Condition Object
The condition object is designed to support generic rule setting and
scope limiting. It includes match field, match type and match value.
The match field is evaluated against the match value based on the
match type. The result is either a True or a False. Several
Liu & Guna Expires June 12, 2012 [Page 12]
Internet-Draft CDNI Metadata Interface December 2011
mandatory match fields, match types are defined in this version of
the spec with future extensibility.
The condition object is defined as
{
"condition": {
"matchField": "FIELDS",
"matchType": "MATCHTYPES",
"matchValue": {
"valueType": "VALUETYPE",
"value": [
valueObjects
]
}
}
}
where the FIELDS can be "URI" | "userAgent" | "client" |
"referrerURL"
where the MATCHTYPES can be "ifMatch" | "ifNoneMatch" | "ifRange".
for the "ifMatch" match type, the result is true if any of the value
in the value list is a match. for the "ifNoneMatch" match type, the
result is true if none of the value in the value list is a match for
the "ifRange" match type, the value list can only have two objects
that defines the range. The result is true if the field is in the
range defined by the value list.
where the VALUETYPE can be "regex" | "ip" | "region" | "number" |
"time".
For the "regex" value type, the value object is a string
representing regex
For the "ip" value type, the value object is a list of IP
object defined as:
{ "ipAddress": "value", "subnetMask": "value"}
where the value is the dotted notation of ip address
For the "region value type", the value object is the region
defined as:
Liu & Guna Expires June 12, 2012 [Page 13]
Internet-Draft CDNI Metadata Interface December 2011
{ "country": "string", "region", "string" }
the country code is defined in ISO-3166-1
the region code is defined in ISO-3166-2
For the "number" value type, the value object is numeric values
For the "time" value type, the value object is defined by the
HTTP1.1
5.2.2. Condition Metadata Object
The metadataObject is of one of the metadata object type defined in
section 5.1.1 to section 5.1.10.
5.2.3. Examples
Here are a few examples of the conditions:
Example 1: Set the cache TTL to 1 day for content whose URI has
*/movie/* in the path.
{
"Conditions": [
{
"condition": {
"matchField": "URI",
"matchType": "ifMatch",
"matchValue": {
"valueType": "regex",
"value": [
"/movie/"
]
}
}
}
],
"metadataList": [
{
Liu & Guna Expires June 12, 2012 [Page 14]
Internet-Draft CDNI Metadata Interface December 2011
"metadatatype": "cacheTTL",
"object": {
"TTL": "3600"
}
}
]
}
Example 2: Restrict the content delivery to only California, United
States:
{
"conditions": [
{
"condition": {
"matchField": "client",
"matchType": "ifNoneMatch",
"matchValue": {
"valueType": "region",
"value": [
{
"country": "US",
"region": "california"
}
]
}
}
}
],
"metadataList": [
{
"metadatatype": "accessControl",
"object": {
"action": "deny"
}
}
]
}
Liu & Guna Expires June 12, 2012 [Page 15]
Internet-Draft CDNI Metadata Interface December 2011
5.3. Error Handling
The metadata interface uses HTTP status to reflect the success or
failure of the operation. In addition, if there is an error in the
operation, detailed information is provided in the response body
with JSON encoding. In the failure condition, the detailed error
information only includes the first error encountered, such as the
JSON encoding of the problem matching condition or metadata. Note
that the unsupported extended metadata will be included also.
To simplify the design, there is no notion of partial success. Only
when all metadata operations are accepted will the success result be
returned.
The following HTTP status code is used:
POST operation:
201 Created (Success)
400 Bad request (Failure)
GET operation:
200 Success
404 Not found (resource not found)
PUT operation:
200 Success
400 Bad request (Failure)
404 Not found (resource not found)
DELETE operation:
200 Success
404 Not found (resource not found)
When the HTTP response code is 400 (Bad request), metadata interface
specific error code used in the JSON are:
1000 Unknown metadata type
Liu & Guna Expires June 12, 2012 [Page 16]
Internet-Draft CDNI Metadata Interface December 2011
1001 Invalid metadata value
1002 Unknown condition type
1003 Invalid condition value
Example error encodings in responses body are:
{ "error code": "1000", metadataObject}
where the metadataObject is the first metadata object that
has the error condition
{ "error code": "1003", conditionObject}
where condition is the first condition that has the error
6. Examples
This section provides an example of metadata interface messages.
This example creates one domain metadata group (origin, cacheTTL,
assetWindow, cacheMissBehavior,caheKey) and two condition metadata
groups for the delivery domain of www.cp1.com. In the first
condition metadata group, if the content URL path include movie, the
cacheTTL metadata is reset. In the second condition metadata group,
if the content URL path includes private, the cache is turned off
using cacheControl metadata.
POST /metadata/www.cp1.com HTTP/1.1
Host: CDNi.dCDN.com
Accept: application/jsonrequest
Content-Length: 500
Content-Type: application/jsonrequest
[
{
"domainMetadataList" [
{
"metaDataType": "contentOrigin",
"object": {
"origins": [
Liu & Guna Expires June 12, 2012 [Page 17]
Internet-Draft CDNI Metadata Interface December 2011
{
"location": "origin1.example.com",
"authentication": {
"type": "basic",
"username": "abc",
"password": "123"
}
},
{
"location": "origin2.example.com",
"authentication": null
}
],
"redundancy": "priority"
}
},
{
"metadataType": "cacheMissBehavior",
"object": {
"cacheMiss": "passThru",
"URL": ""
}
},
{
"metadataType": "assetWindow",
"object": {
"start": "Sun, 04 Dec 2011 08:00:00 GMT",
"end": "Sun, 04 Mar 2012 08:00:00 GMT"
}
},
{
"metadataType": "cacheTTL",
"object": {
"TTL": "3600"
}
},
{
"metadataType": "cacheKey",
"object": {
"key": "s/(.*)user.*(token.*)/$1$2/"
}
Liu & Guna Expires June 12, 2012 [Page 18]
Internet-Draft CDNI Metadata Interface December 2011
}
]
},
{
"Conditions": [
{
"condition": {
"matchField": "URI",
"matchType": "ifMatch",
"matchValue": {
"valueType": "regex",
"value": [
"/movie/"
]
}
}
}
],
"metadataList": [
{
"metadatatype": "cacheTTL",
"object": {
"TTL": "86400"
}
}
]
}
{
"Conditions": [
{
"condition": {
"matchField": "URI",
"matchType": "ifMatch",
"matchValue": {
"valueType": "regex",
"value": [
"/private/"
]
}
}
Liu & Guna Expires June 12, 2012 [Page 19]
Internet-Draft CDNI Metadata Interface December 2011
}
],
"metadataList": [
{
"metadatatype": "cacheControl",
"object":{
"cache":"off"
}
}
]
}
]
Here is the HTTP response:
HTTP/1.1 200 OK
7. Security Considerations
The security concerns on CDNI metadata interface may be addressed
via upstream CDN and downstream CDN exchanging metadata in a secured
fashion. This can be via VPN, transport security via SSL etc. The
authentication can be based on username/password or SSL certificate.
8. IANA Considerations
This memo includes no request to IANA.
9. References
9.1. Normative References
9.2. Informative References
[1] Davie and Peterson, "Framework for CDN Interconnection",
draft-davie-cdni-framework-01 (work in progress), July 2011.
[2] Niven-Jenkins, Faucheur and Bitar, "Content Distribution
Network Interconnection (CDNI) Problem Statement", draft-ietf-
cdni-problem-statement-01 (work in progress), September 2011.
[3] Caulfield and Leung, Ledraft-caulfield-cdni-metadata-core-00
"Content Distribution Network Interconnect (CDNI) Core
Metadata", October 2011.
Liu & Guna Expires June 12, 2012 [Page 20]
Internet-Draft CDNI Metadata Interface December 2011
[4] Stephen, Bertrand, Fieau and Pages, "metadata for CDNs
Interconnection" draft-stephan-cdni-usecases-metadata-00, "
October, 2011
[5] [I-D.draft-cdni-requirements]
"Content Distribution Network Interconnection (CDNI)
Requirements", Kent Leung, Yiu Lee, 9-Sep-11, <draft-ietf-
cdni-requirements-00.txt>.
[6] RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1, June 1999
10. Acknowledgments
This document was prepared using 2-Word-v2.0.template.dot.
Liu & Guna Expires June 12, 2012 [Page 21]
Internet-Draft CDNI Metadata Interface December 2011
Authors' Addresses
Xiaomei Liu
2330 Central Expressway
Santa Clara, CA 95050
USA
Phone: +1 408 330 5198
Email: xiaomei.sc.liu@huawei.com
Lakshminarayanan Gunaseelan
2330 Central Expressway
Santa Clara, CA 95050
USA
Phone: +1 408 330 4662
Email: guna@huawei.com
Xiaoyan He
Huawei
B2, Huawei Industrial Base, 518129
China
Email: hexiaoyan@huawei.com
Jincheng Li
Huawei
B2, Huawei Industrial Base, 518129
China
Email: lijincheng@huawei.com
Liu & Guna Expires June 12, 2012 [Page 22]
