Cache Groups

A Cache Group is - ostensibly - exactly what it sounds like it is: a group of cache servers. More specifically, every server in a Traffic Control CDN must be in a Cache Group (even if they are not actually cache servers). Typically a Cache Group is representative of the available cache servers within a specific geographical location. Despite that cache servers have their own Physical Locations, when cache servers are chosen to serve content to a client based on geographic location the geographic location actually used for comparisons is that for the Cache Group that contains it, not the geographic location of the cache server itself.

The most typical Types of Cache Groups are EDGE_LOC which contain Edge-tier cache servers and MID_LOC which contain Mid-tier cache servers. The latter are each designated as a Parent of one or more of the former to fill out the two-tiered caching hierarchy of an ATC CDN.

Consider the example CDN in Fig. 1. Here some country/province/region has been divided into quarters: Northeast, Southeast, Northwest, and Southwest. The arrows in the diagram indicate the flow of requests. If a client in the Northwest, for example, were to make a request to the Delivery Service, it would first be directed to some cache server in the “Northwest” Edge-tier Cache Group. Should the requested content not be in cache, the Edge-tier server will select a parent from the “West” Cache Group and pass the request up, caching the result for future use. All Mid-tier Cache Groups (usually) answer to a single Origin that provides canonical content. If requested content is not in the Mid-tier cache, then the request will be passed up to the Origin and the result cached.

An illustration of Cache Group hierarchy

Fig. 1 An example CDN that shows the hierarchy between four Edge-tier Cache Groups, two Mid-tier Cache Groups, and one Origin

Regions, Divisions, and Locations

In addition to being in a Cache Group, all servers have to have a Physical Location, which defines their geographic latitude and longitude. Each Physical Location is part of a Region, and each Region is part of a Division. For example, Denver could be the name of a Physical Location in the Mile High Region and that Region could be part of the West Division. The hierarchy between these terms is illustrated graphically in Topography Hierarchy.

A graphic illustrating the hierarchy exhibited by topological groupings

Fig. 2 Topography Hierarchy

To create these structures in Traffic Portal, first make at least one Division under Topology ‣ Divisions. Next enter the desired Region(s) in Topology ‣ Regions, referencing the earlier-entered Division(s). Finally, enter the desired Physical Location(s) in Topology ‣ Phys Locations, referencing the earlier-entered Region(s).

A Cache Group is a logical grouping of cache servers, that don’t have to be in the same Physical Location (in fact, usually a Cache Group is spread across minimally two Physical Locations for redundancy purposes), but share geographical coordinates for content routing purposes. There is no strict requirement that cache servers in a Cache Group share a Physical Location, Region, or Division. This may be confusing at first as there are a few places in code, interfaces, or even documentation where Cache Groups are referred to as “Cache Locations” or even erroneously as “Physical Locations”.

Properties

Cache Groups are modeled several times over, in the Traffic Ops database, in Traffic Portal forms and tables, and several times for various Traffic Ops API versions in the new Go Traffic Ops codebase. Go-specific data structures can be found at github.com/apache/trafficcontrol/lib/go-tc.CacheGroupNullable. Rather than application-specific definitions, what follows is an attempt at consolidating all of the different properties and names of properties of Cache Group objects throughout the ATC suite. The names of these fields are typically chosen as the most human-readable and/or most commonly-used names for the fields, and when reading please note that in many cases these names will appear camelCased or snake_cased to be machine-readable. Any aliases of these fields that are not merely case transformations of the indicated, canonical names will be noted in a table of aliases.

See also

The API reference for Cache Group-related endpoints such as cachegroups contains definitions of the Cache Group object(s) returned and/or accepted by those endpoints.

ASNs

A Cache group can have zero or more ASNs assigned to it, which is used to classify traffic that passes through a CDN. These are typically not represented on a Cache Group object itself, but rather as a separate object indicating the relationship, e.g. in the requests and responses of the asns endpoint.

See also

The Autonomous System Wikipedia page for an explanation of what an ASN actually is.

Coordinate

Tip

Normally, one need not interact with this. In most contexts, this property of a Cache Group is not even exposed, but instead the Cache Group’s Latitude and Longitude are exposed and should be directly manipulated.

The Coordinate of a Cache Group defines the geographic coordinates of a Cache Group that is used for routing clients based on geographic location. It is also used to determine the “closest” Cache Group to another for the purposes of Fallback to Closest.

Typically, this is expressed as an integral, unique identifier for the “Coordinate” object bound to the Cache Group that defines its geographic location, but occasionally it may appear as the name of that “Coordinate” object.

Note

When a new Cache Group is created, it is not necessary to first create a “Coordinate” object where it may reside. Instead, “Coordinates” are created automatically to reflect the Latitude and Longitude given to the newly created Cache Group. The name of the generated “Coordinate” will conform to the pattern from_cachegroup_Name where Name is the Cache Group’s Name. Because of this, creating new Cache Groups will fail if a “Coordinate” with a name matching that pattern already exists.

Fallbacks

Fallbacks are a group of zero or more Cache Groups to be considered for routing when a Cache Group becomes unavailable due to high load or excessive maintenance. These are normally represented by an array of each Cache Group’s ID, but may occasionally appear as the Name or Short Name of each Cache Group.

This set is consulted before Fallback to Closest is taken into consideration.

See also

Health Protocol

Table 1 Aliases

Name

Use(s)

Type(s)

Failover Cache Groups

Traffic Portal forms - but not tables

List or array of Names as strings

backupLocations

In CDN Snapshots

A sub-object called “list” which is a list or array of Cache Group Names as strings

BackupCacheGroups

Traffic Router source code

A List of strings that are the Names of Cache Groups

Fallback to Closest

This is a boolean field which, when true (True, TRUE etc.) causes routing to “fall back” on the nearest Cache Group - geographically - when this Cache Group becomes unavailable due to high load and/or excessive maintenance.

When this is a “true” value, the closest Cache Group will be chosen if and only if any set of Fallbacks configured on the Cache Group has already been exhausted and no available Cache Groups were found..

See also

Health Protocol

Table 2 Aliases

Name

Use(s)

Type(s)

Fallback to Geo Failover

Traffic Portal forms

Unchanged (bool, Boolean etc.)

ID

All Cache Groups have an integral, unique identifier that is mainly used to reference it in the Traffic Ops API.

Despite that a Cache Group’s Name must be unique, this is the identifier most commonly used to represent a unique Cache Group in most contexts throughout ATC. One notable exception is in CDN Snapshots and in routing configuration used by Traffic Router.

Latitude

The Cache Group’s geomagnetic latitude for use in routing and for the purposes of Fallback to Closest.

Table 3 Aliases

Name

Use(s)

Type(s)

Geo Magnetic Latitude

Traffic Portal forms

Unchanged (number, float etc.)

Localization Methods

The Localization Methods of a Cache Group define the methods by which Traffic Router is allowed to route clients to cache servers within this Cache Group. This is a collection of the allowed methods, and the values in the collection are restricted to the following.

  • “Coverage Zone File” (alias CZ in source code, database entries, and Traffic Ops API requests/responses) allows Traffic Router to direct clients to this Cache Group if they were assigned a geographic location by looking up their IP address in the Coverage Zone File.

  • “Deep Coverage Zone File” (alias DEEP_CZ in source code, database entries, and Traffic Ops API requests/responses) was intended to allow Traffic Router to direct clients to this Cache Group if they were assigned a geographic location by looking up their IP addresses in the Deep Coverage Zone File. However, it has no effect at all. This option therefore will not appear in Traffic Portal forms.

    Warning

    In order to make use of “deep caching” for a Delivery Service, all that is required is that Delivery Service has Deep Caching enabled. If that is done and a cache server appears in the Deep Coverage Zone File then clients can and will be routed using that method. There is no way to disable this behavior on a Cache Group (or otherwise) basis, and the precensce or absence of DEEP_CZ in a Cache Group’s Localization Methods has no meaning.

  • “Geo-IP Database” (alias GEO in source code, database entries, and Traffic Ops API requests/responses) allows Traffic Router direct clients to this Cache Group if the client’s IP was looked up in a provided IP address-to-geographic location mapping database to provide their geographic location.

If none of these localization methods are in the set of allowed methods on a Cache Group, it is assumed that clients should be allowed to be routed to that Cache Group regardless of the method used to determine their geographic location.

This property only has meaning for Cache Groups containing Edge-tier cache servers. Which is to say (one would hope) that it only has meaning for EDGE_LOC Cache Groups.

Table 4 Aliases

Name

Use(s)

Type(s)

Enabled Localization Methods

Traffic Portal forms, Traffic Router source code

Unchanged (Set<String>, Array<string> etc.)

Longitude

The Cache Group’s geomagnetic longitude for use in routing and for the purposes of Fallback to Closest.

Table 5 Aliases

Name

Use(s)

Type(s)

Geo Magnetic Longitude

Traffic Portal forms

Unchanged (number, float etc.)

Name

A unique, human-friendly name for the Cache Group, with no special character restrictions or length limit.

Though this property must be unique for all Cache Groups, ID is more commonly used as a unique identifier for a Cache Group in most contexts.

Table 6 Aliases

Name

Use(s)

Type(s)

locationID

CDN Snapshots

Unchanged (str, String etc.)

Parent

A Cache Group can have a parent Cache Group which has different meanings based on the Cache Group’s Type.

  • An EDGE_LOC Cache Group’s parent must be a MID_LOC Cache Group. When configuration files are generated for Edge-tier cache servers, their parents (different from a Cache Group parent) will be selected from the Mid-tier cache servers contained within the Cache Group that is the parent of their containing Cache Group.

  • A MID_LOC Cache Group’s parent must be an ORG_LOC Cache Group. However, if any given MID_LOC either doesn’t have a parent, or does and it’s an ORG_LOC, then all ORG_LOC Cache Groups - even across CDNs - will be considered the parents of that MID_LOC Cache Group. This parent relationship only has any meaning in the context of “multi-site-origins”, as they are unnecessary in other scenarios.

  • For all other Cache Group Types, parent relationships have no meaningful semantics.

Danger

There is no safeguard in the data model or Traffic Ops API that ensures these relationships hold. If they are violated, the resulting CDN behavior is undefined - and almost certainly undesirable.

Parents are typically represented by their ID, but may occasionally appear as their Name.

See also

The Apache Traffic Server documentation for the “parent.config” configuration file. ATC parentage relationships boil down to the parent field of that configuration file, which sets the parents of cache servers.

Table 7 Aliases

Name

Use(s)

Type(s)

Parent Cache Group

Traffic Portal forms and tables

Unchanged (str, String etc.)

ParentCacheGroupID

Traffic Ops database, Traffic Ops Go code, Traffic Ops API requests and responses

Positive integer (int, bigint etc.)

ParentCacheGroupName

Traffic Ops database, Traffic Ops Go code, Traffic Ops API requests and responses

Unchanged (str, String etc.)

Parameters

For unknown reasons, it’s possible to assign Parameters to Cache Groups. This has no attached semantics respected by ATC, and exists today only for compatibility purposes.

These are nearly always represented as a collection of Parameter IDs but occasionally they can be expressed as full Parameter objects.

Table 8 Aliases

Name

Use(s)

Type(s)

cachegroupParameters

Certain Traffic Ops API responses, sometimes in internal Go code

Usually a tuple of associative information like a Cache Group ID and a Parameter ID

Secondary Parent

A secondary parent of a Cache Group is used for fall-back purposes on a cache server-to-cache server basis after routing has already occurred (in contrast with Fallbacks and Fallback to Closest which operate at the routing step on a Cache Group-to-Cache Group basis).

For an explanation of what it means for one Cache Group to be the Parent of another, refer to the Parent section.

See also

The Apache Traffic Server documentation for the “parent.config” configuration file. ATC secondary parentage relationships boil down to the secondary_parent field of that configuration file, which sets the “secondary parents” of cache servers.

Table 9 Aliases

Name

Use(s)

Type(s)

Secondary Parent Cache Group

Traffic Portal forms and tables

Unchanged (str, String etc.)

SecondaryParentCacheGroupID

Traffic Ops database, Traffic Ops Go code, Traffic Ops API requests and responses

Positive integer (int, bigint etc.)

SecondaryParentCacheGroupName

Traffic Ops database, Traffic Ops Go code, Traffic Ops API requests and responses

Unchanged (str, String etc.)

Servers

The primary purpose of a Cache Group is to contain servers. In most scenarios it is implied or assumed that the servers are cache servers, but this is not required and in fact it is not by any means uncommon for the contained servers to be of some other arbitrary Type.

A Cache Group can have zero or more assigned servers, and each server can belong to at most one Cache Group.

Short Name

This is typically an abbreviation of the Cache Group’s Name. The main difference is that it isn’t required to be unique.

Type

A Cache Group’s Type determines what kind of servers it contains. Note that there’s no real restriction on the kinds of servers that a Cache Group can contain, and this Type serves as more of a guide in certain contexts. The Types available by default are described in this section.

Tip

Because Types are mutable, the actual Types that can describe Cache Groups cannot be completely or precisely defined. However, there are no good reasons of which this author can think to modify or delete the default Types herein described, and honestly the good reasons to even merely add to their ranks are likely few.

Table 10 Aliases

Name

Use(s)

Type(s)

Type ID

Traffic Ops client and server Go code, Traffic Ops API requests and responses

positive integer (int, bigint, etc.)

Type Name

Traffic Ops API requests and responses, Traffic Ops database

unchanged (string, String etc.)

EDGE_LOC

This Type of Cache Group contains Edge-tier cache servers.

MID_LOC

This Type of Cache Group contains Mid-tier cache servers

ORG_LOC

This Type of Cache Group contains Origins. The primary purpose of these is to group Origins for the purposes of “multi-site-origins”, and it’s suggested that if that doesn’t meet your use-case that these be mostly avoided. In general, it’s not strictly necessary to create Origin servers in ATC at all, unless you have to support “multi-site-origins”.

TC_LOC

A catch-all Type of Cache Group that’s meant to house infrastructure servers that gain no special semantics based on the Cache Group containing them, e.g. Traffic Portal instances.

TR_LOC

This Type of Cache Group is meant specifically to contain Traffic Router instances.