CDN-Loop header

The CDN-Loop header filter participates in the cross-CDN loop detection protocol specified by RFC 8586. The CDN-Loop header filter performs two actions. First, the filter checks to see how many times a particular CDN identifier has appeared in the CDN-Loop header. Next, if the check passes, the filter then appends the CDN identifier to the CDN-Loop header and passes the request to the next upstream filter. If the check fails, the filter stops processing on the request and returns an error response.

RFC 8586 is particular in how the CDN-Loop header should be modified. As such:

The filter will coalesce multiple CDN-Loop headers into a single, comma-separated header.


The filter is configured with the name envoy.filters.http.cdn_loop.

The filter config has two fields.

  • The cdn_id field sets the identifier that the filter will look for within and append to the CDN-Loop header. RFC 8586 calls this field the “cdn-id”; “cdn-id” can either be a pseudonym or a hostname the CDN provider has control of. The cdn_id field must not be empty.

  • The max_allowed_occurrences field controls how many times cdn_id can appear in the CDN-Loop header on downstream requests (before the filter appends cdn_id to the header). If the cdn_id appears more than max_allowed_occurrences times in the header, the filter will reject the downstream’s request. Most users should configure max_allowed_occurrences to be 0 (the default).

Response Code Details


HTTP Status



400 (Bad Request)

The CDN-Loop header in the downstream is invalid or unparseable.


502 (Bad Gateway)

The cdn_id value appears more than max_allowed_occurrences in the CDN-Loop header, indicating a loop between CDNs.