2013-07-12 20:06:02 +04:00
# etcd
2013-11-13 06:28:51 +04:00
2016-03-14 04:14:00 +03:00
[![Go Report Card ](https://goreportcard.com/badge/github.com/coreos/etcd )](https://goreportcard.com/report/github.com/coreos/etcd)
2015-09-13 08:12:11 +03:00
[![Build Status ](https://travis-ci.org/coreos/etcd.svg?branch=master )](https://travis-ci.org/coreos/etcd)
2016-04-08 21:24:30 +03:00
[![Build Status ](https://semaphoreci.com/api/v1/coreos/etcd/branches/master/shields_badge.svg )](https://semaphoreci.com/coreos/etcd)
2014-10-28 03:39:16 +03:00
[![Docker Repository on Quay.io ](https://quay.io/repository/coreos/etcd-git/status "Docker Repository on Quay.io" )](https://quay.io/repository/coreos/etcd-git)
2014-09-10 02:44:41 +04:00
2015-11-18 05:05:31 +03:00
**Note**: The `master` branch may be in an *unstable or even broken state* during development. Please use [releases][github-release] instead of the `master` branch in order to get stable binaries.
2015-09-11 00:11:44 +03:00
2016-04-26 22:58:49 +03:00
*the etcd v2 [documentation ](Documentation/v2/README.md ) has moved*
2014-12-19 02:05:13 +03:00
![etcd Logo ](logos/etcd-horizontal-color.png )
2015-06-05 02:41:32 +03:00
etcd is a distributed, consistent key-value store for shared configuration and service discovery, with a focus on being:
2013-07-23 21:14:29 +04:00
2016-04-26 22:58:49 +03:00
* *Simple*: well-defined, user-facing API (gRPC)
2016-05-11 20:42:36 +03:00
* *Secure*: automatic TLS with optional client cert authentication
2016-05-28 01:50:04 +03:00
* *Fast*: benchmarked 10,000 writes/sec
2014-04-04 21:58:34 +04:00
* *Reliable*: properly distributed using Raft
2013-07-23 21:14:29 +04:00
2014-04-04 21:58:34 +04:00
etcd is written in Go and uses the [Raft][raft] consensus algorithm to manage a highly-available replicated log.
2013-07-23 21:14:29 +04:00
2016-06-17 05:47:25 +03:00
etcd is used [in production by many companies ](./Documentation/production-users.md ), and the development team stands behind it in critical deployment scenarios, where etcd is frequently teamed with applications such as [Kubernetes][k8s], [fleet][fleet], [locksmith][locksmith], [vulcand][vulcand], [Doorman][doorman], and many others. Reliability is further ensured by rigorous [testing][etcd-tests].
2015-11-18 05:05:31 +03:00
2013-11-13 06:28:51 +04:00
See [etcdctl][etcdctl] for a simple command line client.
2013-07-23 21:14:29 +04:00
2016-01-24 16:28:18 +03:00
[raft]: https://raft.github.io/
2015-11-18 05:05:31 +03:00
[k8s]: http://kubernetes.io/
2016-05-23 22:00:03 +03:00
[doorman]: https://github.com/youtube/doorman
2015-11-18 05:05:31 +03:00
[fleet]: https://github.com/coreos/fleet
[locksmith]: https://github.com/coreos/locksmith
[vulcand]: https://github.com/vulcand/vulcand
2014-12-30 20:20:57 +03:00
[etcdctl]: https://github.com/coreos/etcd/tree/master/etcdctl
2016-06-17 05:47:25 +03:00
[etcd-tests]: http://dash.etcd.io
2013-07-23 21:14:29 +04:00
2016-04-26 22:58:49 +03:00
## Getting started
2013-07-11 22:51:13 +04:00
2013-08-11 23:17:45 +04:00
### Getting etcd
2013-07-12 20:49:10 +04:00
2015-10-21 00:17:33 +03:00
The easiest way to get etcd is to use one of the pre-built release binaries which are available for OSX, Linux, Windows, AppC (ACI), and Docker. Instructions for using these binaries are on the [GitHub releases page][github-release].
2013-07-12 20:49:10 +04:00
2016-07-05 19:55:44 +03:00
For those wanting to try the very latest version, you can [build the latest version of etcd][dl-build] from the `master` branch.
2016-07-01 21:13:22 +03:00
You will first need [*Go* ](https://golang.org/ ) installed on your machine (version 1.6+ is required).
2015-06-05 02:41:32 +03:00
All development occurs on `master` , including new features and bug fixes.
Bug fixes are first targeted at `master` and subsequently ported to release branches, as described in the [branch management][branch-management] guide.
2015-03-14 00:10:25 +03:00
2013-08-11 23:17:45 +04:00
[github-release]: https://github.com/coreos/etcd/releases/
2015-06-05 02:41:32 +03:00
[branch-management]: ./Documentation/branch_management.md
2016-07-05 19:55:44 +03:00
[dl-build]: ./Documentation/dl_build.md#build-the-latest-version
2013-08-11 23:17:45 +04:00
2014-09-09 01:57:16 +04:00
### Running etcd
2013-08-07 05:49:10 +04:00
2015-01-27 00:54:26 +03:00
First start a single-member cluster of etcd:
2013-07-12 09:00:39 +04:00
2013-07-12 09:08:41 +04:00
```sh
2014-01-09 08:47:45 +04:00
./bin/etcd
2013-07-12 09:08:41 +04:00
```
2015-04-06 18:38:13 +03:00
This will bring up etcd listening on port 2379 for client communication and on port 2380 for server-to-server communication.
2013-07-12 09:00:39 +04:00
2014-04-04 21:58:34 +04:00
Next, let's set a single key, and then retrieve it:
2013-07-12 09:00:39 +04:00
2013-12-28 20:37:32 +04:00
```
2016-04-26 22:58:49 +03:00
ETCDCTL_API=3 etcdctl put mykey "this is awesome"
2016-04-30 00:20:14 +03:00
ETCDCTL_API=3 etcdctl get mykey
2013-12-11 22:40:10 +04:00
```
2016-06-17 05:47:25 +03:00
That's it! etcd is now running and serving client requests. For more
- [Animated quick demo][demo-gif]
- [Interactive etcd playground][etcd-play]
[demo-gif]: ./Documentation/demo.md
[etcd-play]: http://play.etcd.io/
2015-01-27 00:54:26 +03:00
2016-03-08 21:28:29 +03:00
### etcd TCP ports
2016-04-26 22:58:49 +03:00
The [official etcd ports][iana-ports] are 2379 for client requests, and 2380 for peer communication.
2016-03-08 21:28:29 +03:00
[iana-ports]: https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=etcd
2016-04-26 22:58:49 +03:00
### Running a local etcd cluster
2015-01-27 00:54:26 +03:00
First install [goreman ](https://github.com/mattn/goreman ), which manages Procfile-based applications.
2016-04-26 22:58:49 +03:00
Our [Procfile script ](./Procfile ) will set up a local example cluster. Start it with:
2015-01-27 00:54:26 +03:00
```sh
goreman start
```
This will bring up 3 etcd members `infra1` , `infra2` and `infra3` and etcd proxy `proxy` , which runs locally and composes a cluster.
2016-04-26 22:58:49 +03:00
Every cluster member and proxy accepts key value reads and key value writes.
2013-07-23 23:59:18 +04:00
2016-04-26 22:58:49 +03:00
### Next steps
2013-07-23 22:37:39 +04:00
2015-01-27 00:54:26 +03:00
Now it's time to dig into the full etcd API and other guides.
2016-04-26 22:58:49 +03:00
- Read the full [documentation][fulldoc].
- Explore the full gRPC [API][api].
2014-04-04 21:58:34 +04:00
- Set up a [multi-machine cluster][clustering].
- Learn the [config format, env variables and flags][configuration].
- Find [language bindings and tools][libraries-and-tools].
- Use TLS to [secure an etcd cluster][security].
- [Tune etcd][tuning].
2016-04-26 22:58:49 +03:00
[fulldoc]: ./Documentation/docs.md
[api]: ./Documentation/dev-guide/api_reference_v3.md
[clustering]: ./Documentation/op-guide/clustering.md
2016-05-12 07:57:30 +03:00
[configuration]: ./Documentation/op-guide/configuration.md
2014-12-23 14:30:47 +03:00
[libraries-and-tools]: ./Documentation/libraries-and-tools.md
2016-04-26 22:58:49 +03:00
[security]: ./Documentation/op-guide/security.md
2014-12-23 14:30:47 +03:00
[tuning]: ./Documentation/tuning.md
2013-12-16 19:00:16 +04:00
2014-02-08 06:23:26 +04:00
## Contact
2014-04-11 02:18:13 +04:00
- Mailing list: [etcd-dev ](https://groups.google.com/forum/?hl=en#!forum/etcd-dev )
2015-07-16 22:52:26 +03:00
- IRC: #[etcd](irc://irc.freenode.org:6667/#etcd) on freenode.org
2015-07-16 22:54:46 +03:00
- Planning/Roadmap: [milestones ](https://github.com/coreos/etcd/milestones ), [roadmap ](./ROADMAP.md )
2014-04-04 21:58:34 +04:00
- Bugs: [issues ](https://github.com/coreos/etcd/issues )
2014-02-08 06:23:26 +04:00
2013-09-30 23:10:56 +04:00
## Contributing
2014-04-04 21:58:34 +04:00
See [CONTRIBUTING ](CONTRIBUTING.md ) for details on submitting patches and the contribution workflow.
2013-09-30 23:10:56 +04:00
2015-07-21 04:11:21 +03:00
## Reporting bugs
2015-10-20 03:03:40 +03:00
See [reporting bugs ](Documentation/reporting_bugs.md ) for details about reporting any issue you may encounter.
2015-07-21 04:11:21 +03:00
2013-08-11 22:15:07 +04:00
### License
2014-04-04 21:58:34 +04:00
etcd is under the Apache 2.0 license. See the [LICENSE ](LICENSE ) file for details.
2016-06-24 20:40:55 +03:00