CDNs and Hosts

Configuring CDNs and hosts

You're viewing a development version of router, the latest released version is 1.24.0

Page not available in that version

The current page CDNs and Hosts doesn't exist in version 1.24.0 of the documentation for this product.

We can take you to the closest parent section instead: /docs/acd/components/router/1.24.0/configuration/

In order to route requests, the ESB3024 CDN Director needs to be configured with hosts that can serve them. Hosts are grouped in host groups, where each group contains hosts that share some common settings. There are three types of host groups: host, redirecting and DNS:

host: Content is served directly. An example of a such a host is the ESB3004 SW Streamer.
redirecting: These hosts are themselves CDN selectors. The CDN Director expects a redirecting CDN to respond with a redirection URL which tells where the content can be found. A typical redirecting CDN is the ESB3008 Convoy Request Router.
DNS: These hosts are EDNS servers. The CDN Director sends DNS requests to these hosts and expects them to respond with an IP address where the content can be found.

Each host group contains a list of hosts. In addition to that, the host groups have different parameters depending on their type.

Host group names as routing targets

Routing rules and the routing entrypoint can target a host group by its name. When a host group name is used as a target, the CDN Director automatically distributes traffic across the hosts in that group. By default, requests are distributed randomly and uniformly. This can be overridden with the loadBalancer parameter (see Parameters shared by host and redirecting host groups).

Thus, instead of manually creating a random or consistentHashing rule block that lists each host individually, you can simply point a routing rule (or the entrypoint) at the host group name and let the CDN Director handle the load balancing.

Common host group parameters

These parameters are present in all host groups:

name: The name of the host group. This is used to reference the host group from other parts of the configuration. The name can also be used directly as a routing target in rules and as the routing entrypoint (see Host group names as routing targets).
type: The type of the host group as listed above.
headersToForward: A list of HTTP headers to forward from the client to the CDN. This is useful if the CDN needs to know about the original Host header or any custom headers added by the client or an upstream proxy. If the incoming request contains an X-Forwarded-For header, that header will be forwarded to the CDN even if it is not listed.
queryPassThrough: Controls which query parameters from the client request are forwarded to the backend and included in the redirection URL. It has two fields:
- policy: accept (default) or deny. accept forwards all query parameters except those listed in exceptions. deny blocks all query parameters except those listed in exceptions.
- exceptions: A list of query parameter names to exclude from the policy.
hosts: A list of hosts in this host group. The configuration of hosts is detailed in Hosts below.

Parameters shared by `host` and `redirecting` host groups

These parameters are only present in host and redirecting host groups:

httpPort: The port to use when sending HTTP requests to the hosts in this group.
httpsPort: The port to use when sending HTTPS requests to the hosts in this group.
loadBalancer: An optional object that overrides the default random load balancing strategy used when the host group name is targeted by a routing rule or the entrypoint. It has the following fields:
- type (required): The load balancing algorithm to use. Must be "random" or "consistentHashing".
- spreadFactor: The number of preferred hosts to distribute requests across when using consistentHashing. Integer between 1 and 64 (default: 1). Only meaningful when type is "consistentHashing".
- hashAlgorithm: The hashing algorithm to use for consistentHashing. "MD5" (default), "SDBM" or "Murmur". Only meaningful when type is "consistentHashing".
When loadBalancer is not set, the host group uses random load balancing by default. See Consistent Hashing for more details on the consistent hashing algorithm.

`host` group parameters

These parameters are only present in host host groups:

createStreamerSession: AgileTV streamers require a session to be allocated when redirecting to them. Setting this parameter to true tells the CDN Director to create such a session when redirecting to hosts in this group.
addUrlPrefix: Enables adding a URL prefix to requests that are redirected to hosts in this group. See URL Prefixes for more information.

`redirecting` group parameters

These parameters are only present in redirecting host groups:

allowAnyRedirectType: The CDN Director expects redirecting CDNs to redirect with response code 302. Setting this parameter to true allows the CDN Director to accept any 3xx response code as a redirection URL.

Hosts

The hosts parameter is the same in all host groups. It contains a list of hosts, each with the following parameters:

name: The name of the host. This is used to reference the host from other parts of the configuration.
hostname: The hostname of the host. This is where requests are sent. It can be an IPv4 address or a domain name.
ipv6_address: The IPv6 address of the host. This is used when the CDN Director needs to send requests to the host over IPv6. If this parameter is not set, the CDN Director will use the hostname parameter for both IPv4 and IPv6 requests.
healthChecks: A list of Lua functions to determine if the host is healthy and can be selected for routing. If any of the health check functions returns false, the host will be considered unhealthy and will not be selected for routing. All health check functions are detailed in the section Built-in Lua functions.

Configuration examples

Below are some examples on how different types of host groups with hosts can be configured.

$ confcli services.routing.hostGroups -w
Running wizard for resource 'hostGroups'

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

hostGroups : [
  hostGroup can be one of
    1: dns
    2: host
    3: redirecting
  Choose element index or name: host
  Adding a 'host' element
    hostGroup : {
      name (default: ): streamers
      type (default: host): ⏎
      httpPort (default: 80): ⏎
      httpsPort (default: 443): ⏎
      headersToForward <A list of HTTP headers to forward to the CDN. (default: [])>: [
        headersToForward (default: ): ⏎
        Add another 'headersToForward' element to array 'headersToForward'? [y/N]: ⏎
      ]
      queryPassThrough <Controls which query parameters from the client request are forwarded to the backend and included in the redirection URL. (default: OrderedDict())>: {
        policy (default: accept): ⏎
        exceptions <Query parameters excluded from the policy. When policy is 'accept', these are blocked. When policy is 'deny', these are forwarded. (default: [])>: [
          exceptions (default: ): ⏎
          Add another 'exceptions' element to array 'exceptions'? [y/N]: ⏎
        ]
      }
      createStreamerSession (default: False): True
      addUrlPrefix (default: False): ⏎
      loadBalancer <Overrides the default random strategy. (default: OrderedDict())>: {
        type (default: random): ⏎
        spreadFactor (default: 1): ⏎
        hashAlgorithm (default: MD5): ⏎
      }
      hosts : [
        host : {
          name (default: ): streamer1
          hostname (default: ): streamer1.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): health_check()
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: y
        host : {
          name (default: ): streamer2
          hostname (default: ): streamer2.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): ⏎
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: ⏎
      ]
    }
  Add another 'hostGroup' element to array 'hostGroups'? [y/N]: ⏎
]
Generated config:
{
  "hostGroups": [
    {
      "name": "streamers",
      "type": "host",
      "httpPort": 80,
      "httpsPort": 443,
      "headersToForward": [
        ""
      ],
      "queryPassThrough": {
        "policy": "accept",
        "exceptions": [
          ""
        ]
      },
      "createStreamerSession": true,
      "addUrlPrefix": false,
      "loadBalancer": {
        "type": "random",
        "spreadFactor": 1,
        "hashAlgorithm": "MD5"
      },
      "hosts": [
        {
          "name": "streamer1",
          "hostname": "streamer1.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "health_check()"
          ]
        },
        {
          "name": "streamer2",
          "hostname": "streamer2.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "always()"
          ]
        }
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y

$ confcli services.routing.hostGroups -w
Running wizard for resource 'hostGroups'

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

hostGroups : [
  hostGroup can be one of
    1: dns
    2: host
    3: redirecting
  Choose element index or name: redirecting
  Adding a 'redirecting' element
    hostGroup : {
      name (default: ): edgeware
      type (default: redirecting): ⏎
      httpPort (default: 80): ⏎
      httpsPort (default: 443): ⏎
      headersToForward <A list of HTTP headers to forward to the CDN. (default: [])>: [
        headersToForward (default: ): ⏎
        Add another 'headersToForward' element to array 'headersToForward'? [y/N]: ⏎
      ]
      queryPassThrough <Controls which query parameters from the client request are forwarded to the backend and included in the redirection URL. (default: OrderedDict())>: {
        policy (default: accept): ⏎
        exceptions <Query parameters excluded from the policy. When policy is 'accept', these are blocked. When policy is 'deny', these are forwarded. (default: [])>: [
          exceptions (default: ): ⏎
          Add another 'exceptions' element to array 'exceptions'? [y/N]: ⏎
        ]
      }
      allowAnyRedirectType (default: False): ⏎
      loadBalancer <Overrides the default random strategy. (default: OrderedDict())>: {
        type (default: random): ⏎
        spreadFactor (default: 1): ⏎
        hashAlgorithm (default: MD5): ⏎
      }
      hosts : [
        host : {
          name (default: ): rr1
          hostname (default: ): convoy-rr1.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): health_check()
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: y
        host : {
          name (default: ): rr2
          hostname (default: ): convoy-rr2.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): ⏎
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: ⏎
      ]
    }
  Add another 'hostGroup' element to array 'hostGroups'? [y/N]: ⏎
]
Generated config:
{
  "hostGroups": [
    {
      "name": "edgeware",
      "type": "redirecting",
      "httpPort": 80,
      "httpsPort": 443,
      "headersToForward": [
        ""
      ],
      "queryPassThrough": {
        "policy": "accept",
        "exceptions": [
          ""
        ]
      },
      "allowAnyRedirectType": false,
      "loadBalancer": {
        "type": "random",
        "spreadFactor": 1,
        "hashAlgorithm": "MD5"
      },
      "hosts": [
        {
          "name": "rr1",
          "hostname": "convoy-rr1.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "health_check()"
          ]
        },
        {
          "name": "rr2",
          "hostname": "convoy-rr2.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "always()"
          ]
        }
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y

$ confcli services.routing.hostGroups -w
Running wizard for resource 'hostGroups'

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

hostGroups : [
  hostGroup can be one of
    1: dns
    2: host
    3: redirecting
  Choose element index or name: host
  Adding a 'host' element
    hostGroup : {
      name (default: ): streamers
      type (default: host): ⏎
      httpPort (default: 80): ⏎
      httpsPort (default: 443): ⏎
      headersToForward <A list of HTTP headers to forward to the CDN. (default: [])>: [
        headersToForward (default: ): ⏎
        Add another 'headersToForward' element to array 'headersToForward'? [y/N]: ⏎
      ]
      queryPassThrough <Controls which query parameters from the client request are forwarded to the backend and included in the redirection URL. (default: OrderedDict())>: {
        policy (default: accept): ⏎
        exceptions <Query parameters excluded from the policy. When policy is 'accept', these are blocked. When policy is 'deny', these are forwarded. (default: [])>: [
          exceptions (default: ): ⏎
          Add another 'exceptions' element to array 'exceptions'? [y/N]: ⏎
        ]
      }
      createStreamerSession (default: False): ⏎
      addUrlPrefix (default: False): ⏎
      loadBalancer <Overrides the default random strategy. (default: OrderedDict())>: {
        type (default: random): consistentHashing
        spreadFactor (default: 1): 2
        hashAlgorithm (default: MD5): ⏎
      }
      hosts : [
        host : {
          name (default: ): streamer1
          hostname (default: ): streamer1.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): health_check()
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: y
        host : {
          name (default: ): streamer2
          hostname (default: ): streamer2.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): ⏎
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: ⏎
      ]
    }
  Add another 'hostGroup' element to array 'hostGroups'? [y/N]: ⏎
]
Generated config:
{
  "hostGroups": [
    {
      "name": "streamers",
      "type": "host",
      "httpPort": 80,
      "httpsPort": 443,
      "headersToForward": [
        ""
      ],
      "queryPassThrough": {
        "policy": "accept",
        "exceptions": [
          ""
        ]
      },
      "createStreamerSession": false,
      "addUrlPrefix": false,
      "loadBalancer": {
        "type": "consistentHashing",
        "spreadFactor": 2,
        "hashAlgorithm": "MD5"
      },
      "hosts": [
        {
          "name": "streamer1",
          "hostname": "streamer1.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "health_check()"
          ]
        },
        {
          "name": "streamer2",
          "hostname": "streamer2.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "always()"
          ]
        }
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y

$ confcli services.routing.hostGroups -w
Running wizard for resource 'hostGroups'

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

hostGroups : [
  hostGroup can be one of
    1: dns
    2: host
    3: redirecting
  Choose element index or name: dns
  Adding a 'dns' element
    hostGroup : {
      name (default: ): external-dns
      type (default: dns): ⏎
      headersToForward <A list of HTTP headers to forward to the CDN. (default: [])>: [
        headersToForward (default: ): ⏎
        Add another 'headersToForward' element to array 'headersToForward'? [y/N]: n
      ]
      queryPassThrough <Controls which query parameters from the client request are forwarded to the backend and included in the redirection URL. (default: OrderedDict())>: {
        policy (default: accept): ⏎
        exceptions <Query parameters excluded from the policy. When policy is 'accept', these are blocked. When policy is 'deny', these are forwarded. (default: [])>: [
          exceptions (default: ): ⏎
          Add another 'exceptions' element to array 'exceptions'? [y/N]: ⏎
        ]
      }
      loadBalancer <Overrides the default random strategy. (default: OrderedDict())>: {
        type (default: random): ⏎
        spreadFactor (default: 1): ⏎
        hashAlgorithm (default: MD5): ⏎
      }
      hosts : [
        host : {
          name (default: ): dns-host
          hostname (default: ): dns.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): ⏎
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: ⏎
      ]
    }
  Add another 'hostGroup' element to array 'hostGroups'? [y/N]: ⏎
]
Generated config:
{
  "hostGroups": [
    {
      "name": "external-dns",
      "type": "dns",
      "headersToForward": [
        ""
      ],
      "queryPassThrough": {
        "policy": "accept",
        "exceptions": [
          ""
        ]
      },
      "loadBalancer": {
        "type": "random",
        "spreadFactor": 1,
        "hashAlgorithm": "MD5"
      },
      "hosts": [
        {
          "name": "dns-host",
          "hostname": "dns.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "always()"
          ]
        }
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y