etcd/README.md

139 lines
6.1 KiB
Markdown
Raw Normal View History

# etcd
2013-11-13 06:28:51 +04: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)
[![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
**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.
*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)
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
* *Simple*: well-defined, user-facing API (gRPC)
* *Secure*: automatic TLS with optional client cert authentication
2016-05-28 01:50:04 +03:00
* *Fast*: benchmarked 10,000 writes/sec
* *Reliable*: properly distributed using Raft
2013-07-23 21:14:29 +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
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].
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
[raft]: https://raft.github.io/
[k8s]: http://kubernetes.io/
[doorman]: https://github.com/youtube/doorman
[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
[etcd-tests]: http://dash.etcd.io
2013-07-23 21:14:29 +04:00
## Getting started
2013-07-11 22:51:13 +04:00
### Getting etcd
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].
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.9+ 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
[rkt]: https://github.com/rkt/rkt/releases/
[github-release]: https://github.com/coreos/etcd/releases/
2015-06-05 02:41:32 +03:00
[branch-management]: ./Documentation/branch_management.md
[dl-build]: ./Documentation/dl_build.md#build-the-latest-version
### Running etcd
2013-08-07 05:49:10 +04: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
./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
Next, let's set a single key, and then retrieve it:
2013-07-12 09:00:39 +04:00
```
ETCDCTL_API=3 etcdctl put mykey "this is awesome"
ETCDCTL_API=3 etcdctl get mykey
```
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/
### etcd TCP ports
The [official etcd ports][iana-ports] are 2379 for client requests, and 2380 for peer communication.
[iana-ports]: http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt
### Running a local etcd cluster
First install [goreman](https://github.com/mattn/goreman), which manages Procfile-based applications.
Our [Procfile script](./Procfile) will set up a local example cluster. Start it with:
```sh
goreman start
```
This will bring up 3 etcd members `infra1`, `infra2` and `infra3` and etcd `grpc-proxy`, which runs locally and composes a cluster.
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
To run an etcd cluster on Kubernetes, try [etcd operator](https://github.com/coreos/etcd-operator).
2016-11-05 03:51:58 +03:00
### Next steps
2013-07-23 22:37:39 +04:00
Now it's time to dig into the full etcd API and other guides.
- Read the full [documentation][fulldoc].
- Explore the full gRPC [API][api].
- Set up a [multi-machine cluster][clustering].
- Learn the [config format, env variables and flags][configuration].
- Find [language bindings and tools][integrations].
- Use TLS to [secure an etcd cluster][security].
- [Tune etcd][tuning].
[fulldoc]: ./Documentation/docs.md
[api]: ./Documentation/dev-guide/api_reference_v3.md
[clustering]: ./Documentation/op-guide/clustering.md
[configuration]: ./Documentation/op-guide/configuration.md
[integrations]: ./Documentation/integrations.md
[security]: ./Documentation/op-guide/security.md
[tuning]: ./Documentation/tuning.md
2013-12-16 19:00:16 +04:00
## Contact
- 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
- Planning/Roadmap: [milestones](https://github.com/coreos/etcd/milestones), [roadmap](./ROADMAP.md)
- Bugs: [issues](https://github.com/coreos/etcd/issues)
## Contributing
See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
2015-07-21 04:11:21 +03:00
## Reporting bugs
See [reporting bugs](Documentation/reporting_bugs.md) for details about reporting any issues.
2015-07-21 04:11:21 +03:00
### License
etcd is under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.