Understanding Diamond: Alibaba’s Distributed Persistent Configuration System

Diamond is an internal configuration management system used by Alibaba to centrally manage persistent configuration data across most of its services, offering simplicity, reliability, and ease of use.

It provides applications with the ability to fetch configuration at startup and to detect and retrieve configuration changes at runtime, persisting data to both disk and databases.

The system’s main characteristics are:

Simple architecture that minimizes error probability.

Highly reliable; it has operated continuously for over a year without major failures.

Easy to use, requiring only two lines of client code.

Diamond’s persistence mechanism stores configuration locally on the server’s disk to reduce database load, while still allowing direct database access via API when low‑latency is required.

Its disaster‑recovery strategy stores data in multiple locations—primary database, server disk, client cache, and a manual recovery directory—allowing the client to read from these sources in a fixed order to maintain service continuity even when the database or server is unavailable.

The architecture diagram (illustrated in the original article) shows the flow from the configuration server to client caches and fallback directories.

On the client side, Diamond uses a subscription model. A simple example demonstrates creating a DefaultDiamondManager with three parameters (groupId, dataId, listener). The listener receives configuration updates via the receiveConfigInfo() callback.

The client initializes a singleton via DiamondClientFactory, registers the listener, sets dataId and groupId, and starts a polling thread that periodically checks for updates.

Key internal components include: ServerAddressProcessor – retrieves the list of server addresses.

Random selection of a server address for load balancing.

HTTP client initialization for communication.

Configuration polling interval (default 15 seconds). rotateCheckConfigInfo – the core method that performs periodic checks.

The polling routine triggers three main checks: checkLocalConfigInfo – verifies local cache for updates. checkDiamondServerConfigInfo – contacts the server for the latest configuration. checkSnapshot – handles persistence of configuration snapshots.

Overall, the article provides a comprehensive overview of Diamond’s design, operational guarantees, and client‑side usage, making it a valuable reference for engineers building or maintaining distributed configuration services.