discovery-naming-conventions.md

Discovery naming conventions

To load balance and route traffic to backend systems, Gimbal must discover the backends and synchronize them to the Gimbal cluster. This is done by the Gimbal discovery components -- currently the Kubernetes Discoverer and the OpenStack Discoverer.

During the discovery process, Gimbal translates the discovered backends into Kubernetes Services and Endpoints. The Discovered Name of each Service and Endpoint is formed by concatenating:

${backend-name}-${service-name}

The name of a service port is not specified, and is handled independently by each Discoverer implementation.

Kubernetes Service naming requirements

Kubernetes Service names must adhere to the rfc1035 DNS Label specification:

An alphanumeric (a-z, and 0-9) string, with a maximum length of 63 characters, with the '-' character allowed anywhere except the first or last character, suitable for use as a hostname or segment in a domain name.

Handling Discovered Names that are longer than 63 characters

When the Discovered Name is longer than 63 characters, it is shortened using the following process:

1. Each component of the Discovered Name gets the same number of maximum characters allowed. The Discovered Name has a total of two components, and thus each component is allocated a maximum of 31 characters (one of the 63 is used for the separator).

2. Starting at the last Discovered Name Component, check whether it is longer than the allocated number of characters. If it is, take the SHA256 hash of the Component. Truncate the excess characters of the Component, and replace with the first 6 characters of the hash.

3. If the resulting Discovered Name is still longer than 63 characters, move onto the next Component and shorten using the approach described above.

4. The shortening process produces the final Discovered Name.

Example

• ${backend-name}: us-east-cluster
• ${service-name}: the-really-long-kube-service-name-that-is-exactly-63-characters

1. The Discovered Name has a total of two components. Thus, allocate 31 characters to each component (62/2, as one char is allocated for the separator).

2. Check if the last Component of the Discovered Name goes over 31 characters:

   "the-really-long-kube-service-name-that-is-exactly-63-characters" has 63 characters.
   

3. Shorten the last Component as it is longer than 31 characters:

Take SHA256 of "the-really-long-kube-service-name-that-is-exactly-63-characters"
SHA256 hash = 1feeec450b150bcfd731a5e7399890e6c61088fec088eb61f83baa75ca3bd2d9
Short hash = 1feeec

Result = "the-really-long-kube-serv1feeec"

4. Check if the resulting Discovered Name is shorter than 63 characters:

   "us-east-cluster-the-really-long-kube-serv1feeec" has 47 characters.
   Thus, we have arrived at our shortened Discovered Name.
   

Discovered name after shortening: us-east-cluster-the-really-long-kube-serv1feeec

Discoverer Specifics

The specifics of each discoverer are documented below.

Kubernetes discoverer

• ${backend-name}: The value of the --backend-name flag provided to the discoverer. Must begin with a lowercase letter.
• ${service-name}: The name of the backend service, verbatim.

Service port names are copied verbatim from the backend service.

OpenStack discoverer

• ${backend-name}: The value of the --backend-name flag provided to the discoverer. Must begin with a lowercase letter.
• ${service-name}: ${id} of the LBaaS Load Balancer. Lowercased during the discovery process.

Service port names are set to port-${port-number}.

Why is the Load Balancer name not part of the service name?

The load balancer's name is not part of the service name because resources in OpenStack can be renamed. This prevents users from unintentionally renaming discovered services in Kubernetes and breaking IngressRoute rules.

Instead, the load balancer's name is available as a label (gimbal.projectcontour.io/load-balancer-name) on the service.