2013-07-12 20:06:02 +04:00
# etcd
2013-11-13 06:28:51 +04:00
2017-10-09 19:48:23 +03:00
[![Go Report Card ](https://goreportcard.com/badge/github.com/coreos/etcd?style=flat-square )](https://goreportcard.com/report/github.com/coreos/etcd)
2017-08-30 08:38:21 +03:00
[![Coverage ](https://codecov.io/gh/coreos/etcd/branch/master/graph/badge.svg )](https://codecov.io/gh/coreos/etcd)
2017-10-09 19:48:23 +03:00
[![Build Status Travis ](https://img.shields.io/travis/coreos/etcdlabs.svg?style=flat-square&&branch=master )](https://travis-ci.org/coreos/etcd)
[![Build Status Semaphore ](https://semaphoreci.com/api/v1/coreos/etcd/branches/master/shields_badge.svg )](https://semaphoreci.com/coreos/etcd)
[![Godoc ](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square )](https://godoc.org/github.com/coreos/etcd)
[![Releases ](https://img.shields.io/github/release/coreos/etcd/all.svg?style=flat-square )](https://github.com/coreos/etcd/releases)
[![LICENSE ](https://img.shields.io/github/license/coreos/etcd.svg?style=flat-square )](https://github.com/coreos/etcd/blob/master/LICENSE)
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 )
2017-05-06 04:07:26 +03:00
etcd is a distributed reliable key-value store for the most critical data of a distributed system, 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
2018-01-25 22:44:08 +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], [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
[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
2017-12-16 01:32:56 +03:00
## Community meetings
etcd contributors and maintainers have bi-weekly meetings at 11:00 AM (USA Pacific) on Tuesdays. There is an [iCalendar][rfc5545] format for the meetings [here ](meeting.ics ). Anyone is welcome to join via [Zoom][zoom] or audio-only: +1 669 900 6833. An initial agenda will be posted to the [shared Google docs][shared-meeting-notes] a day before each meeting, and everyone is welcome to suggest additional topics or other agendas.
[rfc5545]: https://tools.ietf.org/html/rfc5545
[zoom]: https://coreos.zoom.us/j/854793406
[shared-meeting-notes]: https://docs.google.com/document/d/1DbVXOHvd9scFsSmL2oNg4YGOHJdXqtx583DmeVWrB_M/edit#
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
2017-01-21 00:42:11 +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, [rkt][rkt], and Docker. Instructions for using these binaries are on the [GitHub releases page][github-release].
2013-07-12 20:49:10 +04:00
2018-02-17 02:28:37 +03:00
For those wanting to try the very latest version, [build the latest version of etcd][dl-build] from the `master` branch. This first needs [*Go* ](https://golang.org/ ) installed (version 1.10+ is required). 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
2017-04-11 18:48:48 +03:00
[rkt]: https://github.com/rkt/rkt/releases/
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
2017-12-13 04:02:52 +03:00
First start a single-member cluster of etcd.
If etcd is installed using the [pre-built release binaries][github-release], run it from the installation location as below:
```sh
/tmp/etcd-download-test/etcd
```
The etcd command can be simply run as such if it is moved to the system path as below:
```sh
2018-02-06 09:37:37 +03:00
mv /tmp/etcd-download-test/etcd /usr/local/bin/
2017-12-13 04:02:52 +03:00
etcd
```
If etcd is [build from the master branch][dl-build], run it as below:
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
2017-03-21 01:01:01 +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
2017-05-03 20:01:18 +03:00
[iana-ports]: http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt
2016-03-08 21:28:29 +03:00
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
```
2017-10-09 19:28:22 +03:00
This will bring up 3 etcd members `infra1` , `infra2` and `infra3` and etcd `grpc-proxy` , which runs locally and composes a cluster.
2015-01-27 00:54:26 +03:00
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-11-05 03:51:58 +03:00
### Running etcd on Kubernetes
2017-03-04 02:49:40 +03:00
To run an etcd cluster on Kubernetes, try [etcd operator ](https://github.com/coreos/etcd-operator ).
2016-11-05 03:51:58 +03: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].
2017-03-03 19:15:58 +03:00
- Find [language bindings and tools][integrations].
2014-04-04 21:58:34 +04:00
- 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
2017-03-03 19:15:58 +03:00
[integrations]: ./Documentation/integrations.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
2017-03-04 02:49:40 +03:00
See [reporting bugs ](Documentation/reporting_bugs.md ) for details about reporting any issues.
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.