Discovery Service.

Every environment on Cycle comes equipped with the discovery service, which facilitates communication between container instances running within the same environment. It is responsible for looking up local container hostnames, and forwarding all other DNS requests made by containers within the environment.

How the Discovery Service Works

Cycle creates a file inside every container at /etc/resolv.conf, that routes all DNS requests to the local discovery service at hostname env-discovery. If the request is for a local container hostname, it is resolved to one or more private network IP addresses. If there are multiple results, all will be returned, sorted by proximity to the requesting instance.

If there are no matching instances, the request will be round-robined between DNS resolvers hosted by Google, Cloudflare, and OpenDNS. These requests will be cached for 2 minutes on the discovery service, improving lookup times for repeated queries. Failed responses are cached for 10 seconds.

The .cycle TLD

The discovery service will resolve any hostname directly, and any hostname appended with a .cycle TLD.

# Assuming the container hostname is `api`, these will both work
curl http://api
curl http://api.cycle

Types of Custom Resolvers

There are currently two different types of custom resolvers:

1. A custom host resolver - this configuration will inform the discovery service that certain hostnames should resolve to specific IP's.
2. Custom resolver - this configuration will tell the platform where to find additional nameservers to query when looking to resolve a hostname into an IP.

The first resolver (the host resolver) is specifically there for users to force the discovery service to return a specific record when a hostname or domain is queried. The second resolver (custom resolver) is there to inform the platform of additional nameservers that need to be checked when trying to resolve a domain or hostname.

Set Up Custom Resolvers

Custom Domain Suffix

Hostnames on Cycle are resolved by the discovery service. All hostnames also resolve with the .cycle domain suffix by default. Some teams may want to set their own custom domain suffix's and that is configurable on the Cycle Discovery service as well.

Once set, the hostname of the container can be resolved by appending the suffix to the hostname in the hostname.suffix pattern.

Handling Empty NOERROR responses

DNS responses are handled differently depending on the OS and the client used. When resolving IPs, the discovery service will return an empty response with the code NOERROR for any IPv4 lookups in a non-legacy mode environment.

Some older DNS clients don't know how to properly handle these empty responses, and get stuck waiting for an actual response to the query, eventually timing out. This can cause artificially long delays when resolving local services.

If there is a noticeable delay when resolving DNS queries, the discovery service can be set to delay the return of any empty NOERROR results. The delay ensures that a non-empty result will be returned first, which older clients will generally use without issue.

Configure Empty Sets

Forcing Random IP Order

By default, the discovery service returns a list of IPs by proximity to the requesting instance. If a randomized order is preferred, the hostname in the request can be prefixed with an _.

curl http://_api

Public Resolution Rate Limiting

The discovery service rate limits DNS resolutions for non-local (public) domains. Resolutions for local domains, records belonging to the environment, are not throttled.

How It Works

Each discovery instance allows 1,000 public resolutions per 5-minute window.

• Aggregate counter —the limit applies to the total number of non-local resolutions, not unique domains. 1,000 lookups against a single public domain consumes the window just as 1,000 lookups across 1,000 different domains would.
• Fixed window — the counter resets to 0 every 5 minutes, regardless of whether the limit was hit. There is no rolling/sliding calculation.
• Per instance — each discovery instance maintains its own counter. Limits are not shared across instances.

When the Limit Is Hit

Once an instance records 1,000 public resolutions within the current window, any further non-local resolution requests fail with an error until the window resets. At the next 5-minute boundary the counter returns to 0 and public resolution resumes normally.

What Is Not Limited

Local resolutions are exempt. Lookups for services and records within the environment always resolve, regardless of public resolution volume. (Earlier versions limited local resolutions as well; this no longer applies.)

Load Balancing Inter Environment

Containers do support using environment limited networking. If the container needs to be load balanced or has specific, granular requirements for routing - this option allows for more fine grained control.

Manage the Discovery Service

The discovery service can be configured in a number of different ways, including within a stack.