2013-07-12 20:06:02 +04:00
# etcd
2013-11-13 06:28:51 +04:00
2018-08-28 05:19:36 +03:00
[![Go Report Card ](https://goreportcard.com/badge/github.com/etcd-io/etcd?style=flat-square )](https://goreportcard.com/report/github.com/etcd-io/etcd)
[![Coverage ](https://codecov.io/gh/etcd-io/etcd/branch/master/graph/badge.svg )](https://codecov.io/gh/etcd-io/etcd)
2018-08-28 06:03:17 +03:00
[![Build Status Travis ](https://img.shields.io/travis/etcd-io/etcdlabs.svg?style=flat-square&&branch=master )](https://travis-ci.com/etcd-io/etcd)
2018-08-28 05:19:36 +03:00
[![Build Status Semaphore ](https://semaphoreci.com/api/v1/etcd-io/etcd/branches/master/shields_badge.svg )](https://semaphoreci.com/etcd-io/etcd)
2019-05-21 00:32:08 +03:00
[![Docs ](https://img.shields.io/badge/docs-latest-green.svg )](https://etcd.io/docs)
2018-08-28 05:19:36 +03:00
[![Godoc ](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square )](https://godoc.org/github.com/etcd-io/etcd)
[![Releases ](https://img.shields.io/github/release/etcd-io/etcd/all.svg?style=flat-square )](https://github.com/etcd-io/etcd/releases)
[![LICENSE ](https://img.shields.io/github/license/etcd-io/etcd.svg?style=flat-square )](https://github.com/etcd-io/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
2018-04-30 21:27:15 +03:00
![etcd Logo ](logos/etcd-horizontal-color.svg )
2014-12-19 02:05:13 +03:00
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-08-28 05:19:36 +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** ](https://github.com/etcd-io/etcd/tree/master/functional ).
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
2018-08-28 05:19:36 +03:00
[etcdctl]: https://github.com/etcd-io/etcd/tree/master/etcdctl
2013-07-23 21:14:29 +04:00
2017-12-16 01:32:56 +03:00
## Community meetings
2018-12-22 02:53:59 +03:00
etcd contributors and maintainers have monthly (every four weeks) meetings at 11:00 AM (USA Pacific) on Thursday.
2018-08-28 05:19:36 +03:00
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.
2017-12-16 01:32:56 +03:00
2018-04-17 22:05:14 +03:00
[shared-meeting-notes]: https://docs.google.com/document/d/16XEGyPBisZvmmoIHSZzv__LoyOeluC5a4x353CX0SIM/edit
2017-12-16 01:32:56 +03:00
2018-12-22 02:53:59 +03:00
2019-08-22 20:46:34 +03:00
Time:
- [Jan 10th, 2019 11:00 AM video ](https://www.youtube.com/watch?v=0Cphtbd1OSc&feature=youtu.be )
- [Feb 7th, 2019 11:00 AM video ](https://youtu.be/U80b--oAlYM )
- [Mar 7th, 2019 11:00 AM video ](https://youtu.be/w9TI5B7D1zg )
- [Apr 4th, 2019 11:00 AM video ](https://youtu.be/oqQR2XH1L_A )
- [May 2nd, 2019 11:00 AM video ](https://youtu.be/wFwQePuDWVw )
- [May 30th, 2019 11:00 AM video ](https://youtu.be/2t1R5NATYG4 )
- [Jul 11th, 2019 11:00 AM video ](https://youtu.be/k_FZEipWD6Y )
- [Jul 25, 2019 11:00 AM video ](https://youtu.be/VSUJTACO93I )
2019-08-22 22:53:12 +03:00
- [Aug 22, 2019 11:00 AM video ](https://youtu.be/6IBQ-VxQmuM )
2019-09-19 21:55:43 +03:00
- [Sep 19, 2019 11:00 AM video ](https://youtu.be/SqfxU9DhBOc )
2019-08-22 20:46:34 +03:00
- Nov 14, 2019 11:00 AM
- Dec 12, 2019 11:00 AM
2018-12-22 02:53:59 +03:00
2019-08-22 20:46:34 +03:00
Join Hangouts Meet
meet.google.com/umg-nrxn-qvs
2018-12-24 08:53:36 +03:00
2019-08-22 20:46:34 +03:00
Join by phone
+1 405-792-0633 PIN: 299 906 #
More phone numbers
2018-12-24 08:53:36 +03:00
2018-12-22 02:53:59 +03: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
2018-04-09 23:32:58 +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, and Docker on the [release page][github-release].
2018-08-28 05:19:36 +03:00
For more installation guides, please check out [play.etcd.io ](http://play.etcd.io ) and [operating etcd ](https://github.com/etcd-io/etcd/tree/master/Documentation#operating-etcd-clusters ).
2013-07-12 20:49:10 +04:00
2019-09-10 20:43:06 +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.13+ 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
2018-08-28 05:19:36 +03:00
[github-release]: https://github.com/etcd-io/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:
2018-08-28 05:19:36 +03:00
```bash
2017-12-13 04:02:52 +03:00
/tmp/etcd-download-test/etcd
```
2018-05-21 11:48:10 +03:00
2017-12-13 04:02:52 +03:00
The etcd command can be simply run as such if it is moved to the system path as below:
2018-08-28 05:19:36 +03:00
```bash
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
```
2018-05-21 11:48:10 +03:00
If etcd is [built from the master branch][dl-build], run it as below:
2013-07-12 09:00:39 +04:00
2018-08-28 05:19:36 +03:00
```bash
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
```
2019-01-14 15:36:01 +03:00
etcdctl put mykey "this is awesome"
etcdctl get mykey
2013-12-11 22:40:10 +04:00
```
2018-04-09 23:32:58 +03:00
etcd is now running and serving client requests. For more, please check out:
2016-06-17 05:47:25 +03:00
2018-04-09 23:32:58 +03:00
- [Interactive etcd playground ](http://play.etcd.io )
- [Animated quick demo ](./Documentation/demo.md )
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
2018-08-28 05:19:36 +03:00
```bash
2015-01-27 00:54:26 +03:00
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
2019-09-05 00:15:19 +03:00
Follow the steps in [Procfile.learner ](./Procfile.learner ) to add a learner node to the cluster. Start the learner node with:
```bash
goreman -f ./Procfile.learner start
```
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
2018-08-28 05:19:36 +03:00
- Planning/Roadmap: [milestones ](https://github.com/etcd-io/etcd/milestones ), [roadmap ](./ROADMAP.md )
- Bugs: [issues ](https://github.com/etcd-io/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
2018-05-14 20:19:46 +03:00
## Reporting a security vulnerability
2019-07-31 05:23:55 +03:00
See [security disclosure and release process ](security/README.md ) for details on how to report a security vulnerability and how the etcd team manages it.
2018-05-14 20:19:46 +03:00
2019-06-05 17:44:04 +03:00
## Issue and PR management
See [issue triage guidelines ](Documentation/triage/issues.md ) for details on how issues are managed.
See [PR management ](Documentation/triage/PRs.md ) for guidelines on how pull requests are managed.
2019-05-23 06:58:17 +03:00
## etcd Emeritus Maintainers
2019-05-22 08:17:56 +03:00
2019-05-25 02:06:10 +03:00
These emeritus maintainers dedicated a part of their career to etcd and reviewed code, triaged bugs, and pushed the project forward over a substantial period of time. Their contribution is greatly appreciated.
2019-05-23 06:58:17 +03:00
* Fanmin Shi
2019-05-29 22:45:23 +03:00
* Anthony Romano
2019-05-22 08:17:56 +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.