etcd Client
Last updated
Was this helpful?
Last updated
Was this helpful?
This package implements the gen.Registrar
interface and serves as a client library for , a distributed key-value store that provides a reliable way to store data that needs to be accessed by a distributed system or cluster of machines. In addition to the primary Service Discovery function, it automatically notifies all connected nodes about cluster configuration changes and supports hierarchical configuration management with type conversion.
To create a client, use the Create
function from the etcd
package. The function requires a set of options etcd.Options
to configure the connection and behavior.
Then, set this client in the gen.NetworkOption.Registrar
options:
Using etcd.Options
, you can specify:
Cluster
- The cluster name for your node (default: "default")
Endpoints
- List of etcd endpoints (default: ["localhost:2379"])
Username
- Username for etcd authentication (optional)
Password
- Password for etcd authentication (optional)
TLS
- TLS configuration for secure connections (optional)
InsecureSkipVerify
- Option to ignore TLS certificate verification
DialTimeout
- Connection timeout (default: 10s)
RequestTimeout
- Request timeout (default: 10s)
KeepAlive
- Keep-alive timeout (default: 10s)
When the node starts, it will register with the etcd cluster and maintain a lease to ensure automatic cleanup if the node becomes unavailable.
The etcd registrar provides hierarchical configuration management with four priority levels:
Cross-cluster node-specific: services/ergo/config/{cluster}/{node}/{item}
Cluster node-specific: services/ergo/cluster/{cluster}/config/{node}/{item}
Cluster-wide default: services/ergo/cluster/{cluster}/config/*/{item}
Global default: services/ergo/config/global/{item}
The etcd registrar supports typed configuration values using string prefixes. Configuration values are stored as strings in etcd and automatically converted to the appropriate Go types when read by the registrar:
"int:123"
→ int64(123)
"float:3.14"
→ float64(3.14)
"bool:true"
→ bool(true)
, "bool:false"
→ bool(false)
"hello"
→ "hello"
(strings without prefixes remain unchanged)
Important: All configuration values must be stored as strings in etcd. The type conversion happens automatically when the registrar reads the configuration.
Example configuration setup using etcdctl:
Access configuration in your application:
The etcd registrar registers a gen.Event
and generates messages based on changes in the etcd cluster within the specified cluster. This allows the node to stay informed of any updates or changes within the cluster, ensuring real-time event-driven communication and responsiveness to cluster configurations:
etcd.EventNodeJoined
- Triggered when another node is registered in the same cluster
etcd.EventNodeLeft
- Triggered when a node disconnects or its lease expires
etcd.EventApplicationLoaded
- An application was loaded on a remote node
etcd.EventApplicationStarted
- Triggered when an application starts on a remote node
etcd.EventApplicationStopping
- Triggered when an application begins stopping on a remote node
etcd.EventApplicationStopped
- Triggered when an application is stopped on a remote node
etcd.EventConfigUpdate
- The cluster configuration was updated
To receive such messages, you need to subscribe to etcd client events using the LinkEvent
or MonitorEvent
methods from the gen.Process
interface. You can obtain the name of the registered event using the Event
method from the gen.Registrar
interface:
To get information about available applications in the cluster, use the ResolveApplication
method from the gen.Resolver
interface, which returns a list of gen.ApplicationRoute
structures:
Name
- The name of the application
Node
- The name of the node where the application is loaded or running
Weight
- The weight assigned to the application in gen.ApplicationSpec
Mode
- The application's startup mode (gen.ApplicationModeTemporary
, gen.ApplicationModePermanent
, gen.ApplicationModeTransient
)
State
- The current state of the application (gen.ApplicationStateLoaded
, gen.ApplicationStateRunning
, gen.ApplicationStateStopping
)
You can access the gen.Resolver
interface using the Resolver
method from the gen.Registrar
interface:
Get a list of all nodes in the cluster:
The etcd registrar organizes data in etcd using the following key structure:
Important Architecture Notes:
Routes (nodes/applications) use edf.Encode + base64
encoding and are stored in the routes/
subpath. Don't change anything there.
Configuration uses string encoding with type prefixes and is stored in the config/
subpath
This example demonstrates how to run multiple Ergo nodes using etcd as a registrar for service discovery. It showcases service discovery, actor communication, typed configuration management, and real-time configuration event monitoring across a cluster.
The etcd registrar includes comprehensive testing infrastructure:
Use the included Docker Compose setup for testing:
For debugging and manual operations:
The etcd registrar provides a robust, scalable solution for service discovery and configuration management in distributed Ergo applications, with the reliability and consistency guarantees of etcd.
A fully featured example can be found at in the docker
directory.