What is the topology service? How does it work? #

The Topology Service is a set of backend processes. This service is exposed to all Vitess components. It delivers a key/value service that is highly available and consistent, while being offset by having higher latency cost and very low throughput. The Topology Service is used for several things by Vitess:

• It enables tablets to coordinate among themselves as a cluster.
• It enables VTGate to discover tablets, so it knows where to route queries.
• It stores Vitess configuration provided by the administrator which is required by the different components in the Vitess cluster and that must persist between server restarts.

The main functions the Topology Service provides are:

• It is both a repository for topology metadata and a distributed lock manager.
• It is used to store configuration data about the Vitess cluster. It stores small data structures (a few hundred bytes) per object.
  • E.g. information about the Keyspaces, the Shards, the Tablets, the Replication Graph, and the Serving Graph.
• It supports a watch interface that signals a client when changes occur on an object. This is used, for instance, by VTGate to know when the VSchema changes.
• It supports primary election.
• It supports quorum reads and writes.

What Topology servers can I use with Vitess? #

Vitess uses a plugin implementation to support multiple backend technologies for the Topology Service. The servers currently supported are as follows:

• etcd
• ZooKeeper

The Topology Service interfaces are defined in our code in go/vt/topo/, specific implementations are in go/vt/topo/, and we also have a set of unit tests for it in go/vt/topo/test.

How do I choose which topology server to use? #

The first question to consider is: do you use one already or are you required to use a specific one? If the answer to that question is yes, then you should likely implement that rather than adding a new server to run Vitess. However, in large implementations, it makes sense to run a separate topology server dedicated to Vitess. This avoids "noisy neighbor" problems.

By default, we recommend that you use etcd if you can, otherwise you may use ZooKeeper.

How do I implement etcd (etcd2)? #

If you want to implement etcd we recommend following the steps on Vitess’ documentation here.

How do I implement Zookeeper zk2? #

If you want to implement zk2 we recommend following the steps on Vitess’ documentation here.

How do I migrate between implementations? #

We provide the topo2topo utility to migrate between one implementation and another of the topology service.

This process is explained in Vitess’ documentation here.

If your migration is more complex, or has special requirements, we also support a ‘tee’ implementation of the topo service interface. It is defined in go/vt/topo/helpers/tee.go. It allows communicating to two topo services, and the migration uses multiple phases.

This process is explained in Vitess’ documentation here.