2013-07-12 20:06:02 +04:00
# etcd
2013-11-13 06:28:51 +04:00
2014-05-21 04:08:17 +04:00
README version 0.4.0
2013-07-11 22:51:13 +04:00
2013-11-13 06:28:51 +04:00
A highly-available key value store for shared configuration and service discovery.
2014-04-04 21:58:34 +04:00
etcd is inspired by [Apache ZooKeeper][zookeeper] and [doozer][doozer], with a focus on being:
2013-07-23 21:14:29 +04:00
2014-04-04 21:58:34 +04:00
* *Simple*: curl'able user facing API (HTTP+JSON)
* *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
2013-11-13 06:28:51 +04:00
See [etcdctl][etcdctl] for a simple command line client.
Or feel free to just use curl, as in the examples below.
2013-07-23 21:14:29 +04:00
2014-04-04 21:58:34 +04:00
[zookeeper]: http://zookeeper.apache.org/
[doozer]: https://github.com/ha/doozerd
2014-02-12 06:02:08 +04:00
[raft]: http://raftconsensus.github.io/
2013-11-28 02:29:16 +04:00
[etcdctl]: http://github.com/coreos/etcdctl/
2013-07-23 21:14:29 +04:00
2014-04-14 08:36:41 +04:00
If you're considering etcd for production use, please see: [production-ready.md ](./Documentation/production-ready.md )
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
2014-04-04 21:58:34 +04:00
The latest release and setup instructions are available at [GitHub][github-release].
2013-07-12 20:49:10 +04:00
2013-08-11 23:17:45 +04:00
[github-release]: https://github.com/coreos/etcd/releases/
2013-11-13 06:28:51 +04:00
2013-08-07 05:49:10 +04:00
### Building
You can build etcd from source:
2013-08-11 23:17:45 +04:00
```sh
git clone https://github.com/coreos/etcd
2013-08-23 00:13:41 +04:00
cd etcd
2013-08-06 23:01:34 +04:00
./build
2013-07-12 20:49:10 +04:00
```
2014-01-09 08:47:45 +04:00
This will generate a binary called `./bin/etcd` .
2013-08-07 05:49:10 +04:00
2014-01-15 06:17:10 +04:00
_NOTE_: you need go 1.2+. Please check your installation with
2013-08-07 05:49:10 +04:00
```
go version
```
2014-04-04 21:58:34 +04:00
See the [development tools documentation][development-tools] for alternative build methods like using Vagrant.
2014-03-13 20:40:04 +04:00
2014-04-04 21:58:34 +04:00
[development-tools]: https://github.com/coreos/etcd/blob/master/Documentation/development-tools.md
2014-03-13 20:40:04 +04:00
2014-01-04 01:45:03 +04:00
### Running
2013-11-13 06:28:51 +04:00
2014-04-04 21:58:34 +04:00
First start a single-machine 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
```
2013-11-28 02:37:31 +04:00
This will bring up etcd listening on port 4001 for client communication and on port 7001 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
```
2014-01-08 03:57:18 +04:00
curl -L http://127.0.0.1:4001/v2/keys/mykey -XPUT -d value="this is awesome"
curl -L http://127.0.0.1:4001/v2/keys/mykey
2013-12-11 22:40:10 +04:00
```
2014-04-04 21:58:34 +04:00
You have successfully started an etcd on a single machine and written a key to the store. Now it's time to dig into the full etcd API and other guides.
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
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].
- Learn about the dashboard, lock and leader election [modules][modules].
- Use TLS to [secure an etcd cluster][security].
- [Tune etcd][tuning].
2014-04-18 06:25:15 +04:00
- [Upgrade from old version][upgrade].
2014-04-04 21:58:34 +04:00
[api]: https://github.com/coreos/etcd/blob/master/Documentation/api.md
[clustering]: https://github.com/coreos/etcd/blob/master/Documentation/clustering.md
[configuration]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md
[libraries-and-tools]: https://github.com/coreos/etcd/blob/master/Documentation/libraries-and-tools.md
[modules]: https://github.com/coreos/etcd/blob/master/Documentation/modules.md
[security]: https://github.com/coreos/etcd/blob/master/Documentation/security.md
[tuning]: https://github.com/coreos/etcd/blob/master/Documentation/tuning.md
2014-04-18 06:25:15 +04:00
[upgrade]: https://github.com/coreos/etcd/blob/master/Documentation/upgrade.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 )
2014-04-04 21:58:34 +04:00
- IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) oon freenode.org
- Planning/Roadmap: [milestones ](https://github.com/coreos/etcd/issues/milestones )
- 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
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
2013-10-02 17:04:26 +04:00
curl -L http://127.0.0.1:4001/version
2013-08-11 22:08:09 +04:00
```
2013-12-28 19:13:41 +04:00
#### API Versioning
Clients are encouraged to use the `v2` API. The `v1` API will not change.
The `v2` API responses should not change after the 0.2.0 release but new features will be added over time.
During the pre-v1.0.0 series of releases we may break the API as we fix bugs and get feedback.
2013-11-13 06:28:51 +04:00
2014-05-21 03:23:33 +04:00
#### 32bit systems
etcd has known issues on 32bit systems. We plan to address these issues after the 0.4 release.
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.