etcd developer guide on etcd

Discovery service protocol

Mon, 01 Jan 0001 00:00:00 +0000

Discovery service protocol helps new etcd member to discover all other members in cluster bootstrap phase using a shared discovery URL.

Discovery service protocol is only used in cluster bootstrap phase, and cannot be used for runtime reconfiguration or cluster monitoring.

The protocol uses a new discovery token to bootstrap one unique etcd cluster. Remember that one discovery token can represent only one etcd cluster. As long as discovery protocol on this token starts, even if it fails halfway, it must not be used to bootstrap another etcd cluster.

etcd API Reference

Mon, 01 Jan 0001 00:00:00 +0000

This is a generated documentation. Please read the proto files for more.

service `Auth` (etcdserver/etcdserverpb/rpc.proto)

Method	Request Type	Response Type	Description
AuthEnable	AuthEnableRequest	AuthEnableResponse	AuthEnable enables authentication.
AuthDisable	AuthDisableRequest	AuthDisableResponse	AuthDisable disables authentication.
Authenticate	AuthenticateRequest	AuthenticateResponse	Authenticate processes an authenticate request.
UserAdd	AuthUserAddRequest	AuthUserAddResponse	UserAdd adds a new user.
UserGet	AuthUserGetRequest	AuthUserGetResponse	UserGet gets detailed user information.
UserList	AuthUserListRequest	AuthUserListResponse	UserList gets a list of all users.
UserDelete	AuthUserDeleteRequest	AuthUserDeleteResponse	UserDelete deletes a specified user.
UserChangePassword	AuthUserChangePasswordRequest	AuthUserChangePasswordResponse	UserChangePassword changes the password of a specified user.
UserGrantRole	AuthUserGrantRoleRequest	AuthUserGrantRoleResponse	UserGrant grants a role to a specified user.
UserRevokeRole	AuthUserRevokeRoleRequest	AuthUserRevokeRoleResponse	UserRevokeRole revokes a role of specified user.
RoleAdd	AuthRoleAddRequest	AuthRoleAddResponse	RoleAdd adds a new role.
RoleGet	AuthRoleGetRequest	AuthRoleGetResponse	RoleGet gets detailed role information.
RoleList	AuthRoleListRequest	AuthRoleListResponse	RoleList gets lists of all roles.
RoleDelete	AuthRoleDeleteRequest	AuthRoleDeleteResponse	RoleDelete deletes a specified role.
RoleGrantPermission	AuthRoleGrantPermissionRequest	AuthRoleGrantPermissionResponse	RoleGrantPermission grants a permission of a specified key or range to a specified role.
RoleRevokePermission	AuthRoleRevokePermissionRequest	AuthRoleRevokePermissionResponse	RoleRevokePermission revokes a key or range permission of a specified role.

service `Cluster` (etcdserver/etcdserverpb/rpc.proto)

Method	Request Type	Response Type	Description
MemberAdd	MemberAddRequest	MemberAddResponse	MemberAdd adds a member into the cluster.
MemberRemove	MemberRemoveRequest	MemberRemoveResponse	MemberRemove removes an existing member from the cluster.
MemberUpdate	MemberUpdateRequest	MemberUpdateResponse	MemberUpdate updates the member configuration.
MemberList	MemberListRequest	MemberListResponse	MemberList lists all the members in the cluster.

service `KV` (etcdserver/etcdserverpb/rpc.proto)

for grpc-gateway

Experimental APIs and features

Mon, 01 Jan 0001 00:00:00 +0000

For the most part, the etcd project is stable, but we are still moving fast! We believe in the release fast philosophy. We want to get early feedback on features still in development and stabilizing. Thus, there are, and will be more, experimental features and APIs. We plan to improve these features based on the early feedback from the community, or abandon them if there is little interest, in the next few releases. Please do not rely on any experimental features or APIs in production environment.

gRPC Gateway

Mon, 01 Jan 0001 00:00:00 +0000

etcd v3 uses gRPC for its messaging protocol. The etcd project includes a gRPC-based Go client and a command line utility, etcdctl, for communicating with an etcd cluster through gRPC. For languages with no gRPC support, etcd provides a JSON grpc-gateway. This gateway serves a RESTful proxy that translates HTTP/JSON requests into gRPC messages.

Using grpc-gateway

The gateway accepts a JSON mapping for etcd’s protocol buffer message definitions. Note that key and value fields are defined as byte arrays and therefore must be base64 encoded in JSON.

gRPC naming and discovery

Mon, 01 Jan 0001 00:00:00 +0000

etcd provides a gRPC resolver to support an alternative name system that fetches endpoints from etcd for discovering gRPC services. The underlying mechanism is based on watching updates to keys prefixed with the service name.

Using etcd discovery with go-grpc

The etcd client provides a gRPC resolver for resolving gRPC endpoints with an etcd backend. The resolver is initialized with an etcd client and given a target for resolution:

import (
	"github.com/coreos/etcd/clientv3"
	etcdnaming "github.com/coreos/etcd/clientv3/naming"

	"google.golang.org/grpc"
)

...

cli, cerr := clientv3.NewFromURL("http://localhost:2379")
r := &etcdnaming.GRPCResolver{Client: cli}
b := grpc.RoundRobin(r)
conn, gerr := grpc.Dial("my-service", grpc.WithBalancer(b))

Managing service endpoints

The etcd resolver treats all keys under the prefix of the resolution target following a “/” (e.g., “my-service/”) with JSON-encoded go-grpc naming.Update values as potential service endpoints. Endpoints are added to the service by creating new keys and removed from the service by deleting keys.

Interacting with etcd

Mon, 01 Jan 0001 00:00:00 +0000

Users mostly interact with etcd by putting or getting the value of a key. This section describes how to do that by using etcdctl, a command line tool for interacting with etcd server. The concepts described here should apply to the gRPC APIs or client library APIs.

By default, etcdctl talks to the etcd server with the v2 API for backward compatibility. For etcdctl to speak to etcd using the v3 API, the API version must be set to version 3 via the ETCDCTL_API environment variable.

Setup a local cluster

Mon, 01 Jan 0001 00:00:00 +0000

For testing and development deployments, the quickest and easiest way is to set up a local cluster. For a production deployment, refer to the clustering section.

Local standalone cluster

Deploying an etcd cluster as a standalone cluster is straightforward. Start it with just one command:

$ ./etcd
...

The started etcd member listens on localhost:2379 for client requests.

To interact with the started cluster by using etcdctl:

# use API version 3
$ export ETCDCTL_API=3

$ ./etcdctl put foo bar
OK

$ ./etcdctl get foo
bar

Local multi-member cluster

A Procfile at the base of this git repo is provided to easily set up a local multi-member cluster. To start a multi-member cluster go to the root of an etcd source tree and run:

System limits

Mon, 01 Jan 0001 00:00:00 +0000

Request size limit

etcd is designed to handle small key value pairs typical for metadata. Larger requests will work, but may increase the latency of other requests. For the time being, etcd guarantees to support RPC requests with up to 1MB of data. In the future, the size limit may be loosened or made it configurable.

Storage size limit

The default storage size limit is 2GB, configurable with --quota-backend-bytes flag; supports up to 8GB.

etcd developer guide on etcd

Discovery service protocol

etcd API Reference

service Auth (etcdserver/etcdserverpb/rpc.proto)

service Cluster (etcdserver/etcdserverpb/rpc.proto)

service KV (etcdserver/etcdserverpb/rpc.proto)

Experimental APIs and features

gRPC Gateway

Using grpc-gateway

gRPC naming and discovery

Using etcd discovery with go-grpc

Managing service endpoints

Interacting with etcd

Setup a local cluster

Local standalone cluster

Local multi-member cluster

System limits

Request size limit

Storage size limit

service `Auth` (etcdserver/etcdserverpb/rpc.proto)

service `Cluster` (etcdserver/etcdserverpb/rpc.proto)

service `KV` (etcdserver/etcdserverpb/rpc.proto)