2013-07-12 20:06:02 +04:00
# etcd
2013-11-13 06:28:51 +04:00
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)
2015-10-20 02:08:40 +03:00
[![Build Status ](https://semaphoreci.com/api/v1/projects/406f9909-2f4f-4839-b59e-95082cb088f1/575109/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
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
2015-11-18 05:05:31 +03:00
* *Simple*: curl'able user-facing API (HTTP+JSON)
2014-04-04 21:58:34 +04:00
* *Secure*: optional SSL client cert authentication
* *Fast*: benchmarked 1000s of writes/s per instance
* *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
2015-12-16 02:54:59 +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], and many others.
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.
2015-11-18 05:05:31 +03:00
Or feel free to just use `curl` , as in the examples below.
2013-07-23 21:14:29 +04:00
2014-02-12 06:02:08 +04:00
[raft]: http://raftconsensus.github.io/
2015-11-18 05:05:31 +03:00
[k8s]: http://kubernetes.io/
[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
2013-07-23 21:14:29 +04:00
2013-07-12 20:06:02 +04: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
2015-06-05 02:41:32 +03:00
For those wanting to try the very latest version, you can build the latest version of etcd from the `master` branch.
2015-09-29 01:35:09 +03:00
You will first need [*Go* ](https://golang.org/ ) installed on your machine (version 1.4+ 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
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
```
2015-04-06 18:38:13 +03:00
curl -L http://127.0.0.1:2379/v2/keys/mykey -XPUT -d value="this is awesome"
curl -L http://127.0.0.1:2379/v2/keys/mykey
2013-12-11 22:40:10 +04:00
```
2015-01-27 00:54:26 +03:00
You have successfully started an etcd and written a key to the store.
### Running local etcd cluster
First install [goreman ](https://github.com/mattn/goreman ), which manages Procfile-based applications.
2015-03-26 00:01:02 +03:00
Our [Procfile script ](./Procfile ) will set up a local example cluster. You can 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.
You can write a key to the cluster and retrieve the value back from any member or proxy.
2013-07-23 23:59:18 +04:00
2014-01-04 01:45:03 +04: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.
2014-04-04 21:58:34 +04:00
- Explore the full [API][api].
- 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].
2015-08-29 06:57:12 +03:00
- [Upgrade from 0.4.9+ to 2.2.0][upgrade].
2014-04-04 21:58:34 +04:00
2014-12-23 14:30:47 +03:00
[api]: ./Documentation/api.md
[clustering]: ./Documentation/clustering.md
[configuration]: ./Documentation/configuration.md
[libraries-and-tools]: ./Documentation/libraries-and-tools.md
[security]: ./Documentation/security.md
[tuning]: ./Documentation/tuning.md
2015-08-29 06:57:12 +03:00
[upgrade]: ./Documentation/04_to_2_snapshot_migration.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:08:09 +04:00
## Project Details
### Versioning
2013-12-28 19:13:41 +04:00
#### Service Versioning
2014-04-04 21:58:34 +04:00
etcd uses [semantic versioning ](http://semver.org )
2013-12-28 19:13:41 +04:00
New minor versions may add additional features to the API.
2013-08-11 22:08:09 +04:00
2013-10-02 17:04:26 +04:00
You can get the version of etcd by issuing a request to /version:
2013-08-11 22:08:09 +04:00
```sh
2015-04-06 18:38:13 +03:00
curl -L http://127.0.0.1:2379/version
2013-08-11 22:08:09 +04:00
```
2013-12-28 19:13:41 +04:00
#### API Versioning
2015-01-28 09:54:10 +03:00
The `v2` API responses should not change after the 2.0.0 release but new features will be added over time.
2013-11-13 06:28:51 +04:00
2014-09-09 01:43:36 +04:00
#### 32-bit systems
2014-05-21 03:23:33 +04:00
2014-09-09 02:05:43 +04:00
etcd has known issues on 32-bit systems due to a bug in the Go runtime. See #[358][358] for more information.
[358]: https://github.com/coreos/etcd/issues/358
2014-05-21 03:23:33 +04: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.