Sentinel caches

A cache in your environment can be given a failover owner — the party that decides which Pod writes when the writer is lost. A cache whose owner is Sentinel is guarded by a quorum of three platform-owned Sentinels, so the writer can move while your application is running.

That is a different contract from a cache the platform promotes itself, and it changes what your application has to be configured with.

Which cache is guarded by a quorum

A cache records one of three failover owners:

• none — the cache is a single instance, and losing it is an outage.
• platform — the platform promotes a follower itself when the writer is lost.
• sentinel — a quorum of three platform-owned Sentinels decides, and the platform records that decision instead of making one.

A cache with a follower must name an owner. A cache that has a follower and no owner is refused, because nothing would say which Pod writes and the writer's address would resolve to nothing.

Only a cache whose owner is Sentinel is guarded by a quorum. A cache with the platform owner keeps reporting the writer's own address, and the platform moves the writer on its own; a client that reads only that address keeps working and never learns that the writer moved. The endpoints the environment page shows are described under The cache.

The quorum is one per environment, not one per cache: it watches every guarded cache in the environment, and each cache is known to it by its own writer name. Its three small Pods are part of the environment rather than a service you add or price.

The failover owner is recorded when the cache is added. The browser's Add service dialog does not offer one, so a quorum-guarded cache is arranged with us — see Support.

The quorum your client talks to

The quorum is three Pods behind one headless Service, named sentinel, in your environment's own namespace. Each member answers at its own address inside the cluster, and the quorum answers on its own port, 26379.

Two of the three members must agree before anything happens, so the quorum keeps working when it loses one member. It is reachable from inside your environment only.

The quorum's port is protected by a password of its own, separate from the cache's credential: the quorum decides which Pod writes, and that decision must not be open to anything else in the cluster.

The values the platform delivers

These are the values a client of a quorum-guarded cache needs. The platform delivers them to your application's environment; the names in the first column are the ones you write in a configuration document.

Value	What it is
sentinel-host	The quorum's own address: the Service its three members answer through.
sentinel-port	The port the quorum answers on.
authoritative-endpoint	Which of the reported endpoints is the one to dial. It reads sentinel, which is how a client is told that the writer's own address is not the address to use.
sentinel-master	The name the quorum knows your cache's writer by. It is the writer's own Service name, so a client asking the quorum about this name is asking about the writer it already has a binding for.
sentinel-endpoints	The three members as host:port,host:port,host:port, in the order a client should try them. There is no scheme in this value: the scheme belongs to the cache's transport, not to the quorum.
sentinel-password	The credential your client presents to the quorum. It is not the cache's own credential.
sentinel-host-1 … sentinel-host-3	Each member's address, one value per member.
sentinel-port-1 … sentinel-port-3	Each member's port, one value per member.

There is no fourth member: the quorum has three, and a fourth name is refused rather than answered with an empty address.

The quorum's password is a credential, not a plain value

The password travels in your environment's Secret, not as a plain value in the Pod's environment, so it reaches the process the same way the cache's own credential does. You name it yourself; see below.

The names your process receives

A process that references the guarded cache is given the platform's own names for these values, so you do not have to restate them per process:

• REDIS_SENTINEL_MASTER — the writer's name in the quorum.
• REDIS_SENTINEL_ENDPOINTS — the three members as one comma-separated list.
• REDIS_SENTINEL_HOST_1 … REDIS_SENTINEL_HOST_3 — each member's address.
• REDIS_SENTINEL_PORT_1 … REDIS_SENTINEL_PORT_3 — each member's port.
• REDIS_SENTINEL_TLS — the cache's own transport setting, so the client reads the requirement where it reads the endpoint: required when the writer may only be reached over TLS, optional when the plaintext listener is composed as well.
• REDIS_SENTINEL_TLS_CA_PATH — the CA file a client verifies the writer against, delivered only when a CA is actually mounted into the Pod.

Two rules keep that predictable:

• A process that references no guarded cache receives none of them, and a cache that is not guarded contributes nothing at all. A process bound to a single-instance cache keeps exactly the environment it had.
• A name you declare yourself is yours. If your process already declares one of these names, the platform does not deliver a second value under it.

Naming the values in your configuration document

A configuration document reaches these values through a redis reference, and each reference names one value. The quorum's password is the one value the platform does not deliver by itself, because it is a credential: a document names it, and it reaches the process through the environment's Secret.

version: "1.6"
applications:
  web:
    runtime: node
    source:
      root: .
    build:
      install: [npm, ci]
      command: [npm, run build]
    run:
      command: [node, dist/server.js]
      port: 3000
    env:
      REDIS_SENTINEL_PASSWORD:
        redis: sentinel-password

The other values are delivered to any process that references the guarded cache, under the platform's own names — see The names your process receives. You may bind them yourself as well, under names of your own, and a name you declare is kept rather than overwritten.

A document that names these values must declare a version whose schema includes them: the sentinel values arrive in version 1.5, and the quorum's password in version 1.6. The published schema for the version you declare is the contract — see Configuration.

What your client must do

A client of a quorum-guarded cache does not connect to the writer. It:

1. asks the quorum which Pod is the writer, using the writer's name (sentinel-master / REDIS_SENTINEL_MASTER) and one of the quorum's addresses;
2. presents the quorum's password (sentinel-password / REDIS_SENTINEL_PASSWORD) to that address — a client that asks the quorum who the master is has to present one;
3. connects to the address the quorum returned, with the cache's own credential, over the transport the cache requires;
4. asks again when the connection fails, because the writer's address is not fixed.

The fourth point is the whole reason the cache asked for a quorum. A client that holds the writer's address — the host value, or the url — keeps working for as long as that Pod is alive and never learns that the writer moved. A client that asks the quorum follows the writer.

The cache's own address still names the writer, and it still follows a promotion, so a client that cannot use Sentinel keeps working. It simply never discovers the move.

What happens when the writer is lost

The quorum watches the writer and notices when it stops answering. It marks a writer down after five seconds without a reply, and gives a failover sixty seconds to complete. When it has decided, it promotes a follower and records the new writer; the platform then moves the writer's address onto the promoted Pod, so the address your client was given starts answering again.

After the first writer, the quorum makes every promotion decision and the platform records it. The platform does not promote a second time under a Sentinel owner: two owners each convinced the other chose wrong is the fight this arrangement exists to avoid.

The first writer is the one exception, and the platform establishes it. A fresh cache starts with every Pod as a follower, and the quorum has no writer to watch, so the platform promotes the follower holding the most data — the highest replication offset — and labels it. A Pod whose role cannot be read is never promoted, because it holds an unknown amount of your data.

Two situations change nothing, and both are deliberate:

• The quorum cannot be reached, or refuses the question. The writer stays where it is and the reason is recorded. A platform that promoted here would be choosing the master the quorum exists to choose.
• Two Pods both claim to be the writer. The split brain is named and the writer is left alone. The platform does not pick between two writers; that would be a third opinion nobody asked for.

When the endpoint moves

The endpoint itself does not move. The quorum's address, its three member addresses and its port are the same for the life of the environment: the members are named, not generated, so a restart does not change them. What moves is the writer, and the quorum is what says where it is now.

So there is nothing for you to reconfigure and no address for you to update. The client's job is to ask the quorum rather than to remember the writer — a client that re-reads the writer on every failed connection follows it, and a client that stored the writer's address follows it only until that address stops answering.

Next

• See the endpoints your environment reports for its cache: Databases.
• See how a document names the values it needs: Configuration.
• Arrange a quorum-guarded cache: Support.