go.etcd.io/etcd@v3.3.27+incompatible/README.md (about) 1 # etcd 2 3 [](https://goreportcard.com/report/github.com/coreos/etcd) 4 [](https://codecov.io/gh/coreos/etcd) 5 [](https://travis-ci.org/coreos/etcd) 6 [](https://semaphoreci.com/coreos/etcd) 7 [](https://godoc.org/github.com/coreos/etcd) 8 [](https://github.com/coreos/etcd/releases) 9 [](https://github.com/coreos/etcd/blob/master/LICENSE) 10 11 **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. 12 13 *the etcd v2 [documentation](Documentation/v2/README.md) has moved* 14 15  16 17 etcd is a distributed reliable key-value store for the most critical data of a distributed system, with a focus on being: 18 19 * *Simple*: well-defined, user-facing API (gRPC) 20 * *Secure*: automatic TLS with optional client cert authentication 21 * *Fast*: benchmarked 10,000 writes/sec 22 * *Reliable*: properly distributed using Raft 23 24 etcd is written in Go and uses the [Raft][raft] consensus algorithm to manage a highly-available replicated log. 25 26 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]. 27 28 See [etcdctl][etcdctl] for a simple command line client. 29 30 [raft]: https://raft.github.io/ 31 [k8s]: http://kubernetes.io/ 32 [doorman]: https://github.com/youtube/doorman 33 [fleet]: https://github.com/coreos/fleet 34 [locksmith]: https://github.com/coreos/locksmith 35 [vulcand]: https://github.com/vulcand/vulcand 36 [etcdctl]: https://github.com/coreos/etcd/tree/master/etcdctl 37 [etcd-tests]: http://dash.etcd.io 38 39 ## Community meetings 40 41 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. 42 43 [rfc5545]: https://tools.ietf.org/html/rfc5545 44 [zoom]: https://coreos.zoom.us/j/854793406 45 [shared-meeting-notes]: https://docs.google.com/document/d/1DbVXOHvd9scFsSmL2oNg4YGOHJdXqtx583DmeVWrB_M/edit# 46 47 ## Getting started 48 49 ### Getting etcd 50 51 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]. 52 53 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. 54 55 [rkt]: https://github.com/rkt/rkt/releases/ 56 [github-release]: https://github.com/coreos/etcd/releases/ 57 [branch-management]: ./Documentation/branch_management.md 58 [dl-build]: ./Documentation/dl_build.md#build-the-latest-version 59 60 ### Running etcd 61 62 First start a single-member cluster of etcd. 63 64 If etcd is installed using the [pre-built release binaries][github-release], run it from the installation location as below: 65 66 ```sh 67 /tmp/etcd-download-test/etcd 68 ``` 69 The etcd command can be simply run as such if it is moved to the system path as below: 70 71 ```sh 72 mv /tmp/etcd-download-test/etcd /usr/locale/bin/ 73 74 etcd 75 ``` 76 77 If etcd is [build from the master branch][dl-build], run it as below: 78 79 ```sh 80 ./bin/etcd 81 ``` 82 83 This will bring up etcd listening on port 2379 for client communication and on port 2380 for server-to-server communication. 84 85 Next, let's set a single key, and then retrieve it: 86 87 ``` 88 ETCDCTL_API=3 etcdctl put mykey "this is awesome" 89 ETCDCTL_API=3 etcdctl get mykey 90 ``` 91 92 That's it! etcd is now running and serving client requests. For more 93 94 - [Animated quick demo][demo-gif] 95 - [Interactive etcd playground][etcd-play] 96 97 [demo-gif]: ./Documentation/demo.md 98 [etcd-play]: http://play.etcd.io/ 99 100 ### etcd TCP ports 101 102 The [official etcd ports][iana-ports] are 2379 for client requests, and 2380 for peer communication. 103 104 [iana-ports]: http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt 105 106 ### Running a local etcd cluster 107 108 First install [goreman](https://github.com/mattn/goreman), which manages Procfile-based applications. 109 110 Our [Procfile script](./Procfile) will set up a local example cluster. Start it with: 111 112 ```sh 113 goreman start 114 ``` 115 116 This will bring up 3 etcd members `infra1`, `infra2` and `infra3` and etcd `grpc-proxy`, which runs locally and composes a cluster. 117 118 Every cluster member and proxy accepts key value reads and key value writes. 119 120 ### Running etcd on Kubernetes 121 122 To run an etcd cluster on Kubernetes, try [etcd operator](https://github.com/coreos/etcd-operator). 123 124 ### Next steps 125 126 Now it's time to dig into the full etcd API and other guides. 127 128 - Read the full [documentation][fulldoc]. 129 - Explore the full gRPC [API][api]. 130 - Set up a [multi-machine cluster][clustering]. 131 - Learn the [config format, env variables and flags][configuration]. 132 - Find [language bindings and tools][integrations]. 133 - Use TLS to [secure an etcd cluster][security]. 134 - [Tune etcd][tuning]. 135 136 [fulldoc]: ./Documentation/docs.md 137 [api]: ./Documentation/dev-guide/api_reference_v3.md 138 [clustering]: ./Documentation/op-guide/clustering.md 139 [configuration]: ./Documentation/op-guide/configuration.md 140 [integrations]: ./Documentation/integrations.md 141 [security]: ./Documentation/op-guide/security.md 142 [tuning]: ./Documentation/tuning.md 143 144 ## Contact 145 146 - Mailing list: [etcd-dev](https://groups.google.com/forum/?hl=en#!forum/etcd-dev) 147 - IRC: #[etcd](irc://irc.freenode.org:6667/#etcd) on freenode.org 148 - Planning/Roadmap: [milestones](https://github.com/coreos/etcd/milestones), [roadmap](./ROADMAP.md) 149 - Bugs: [issues](https://github.com/coreos/etcd/issues) 150 151 ## Contributing 152 153 See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow. 154 155 ## Reporting bugs 156 157 See [reporting bugs](Documentation/reporting_bugs.md) for details about reporting any issues. 158 159 ### License 160 161 etcd is under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.