|
|
@@ -1,70 +0,0 @@
|
|
|
-**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.**
|
|
|
-
|
|
|
-[v3-docs]: ../docs.md#documentation
|
|
|
-
|
|
|
-
|
|
|
-# FAQ
|
|
|
-
|
|
|
-## Initial Bootstrapping UX
|
|
|
-
|
|
|
-etcd initial bootstrapping is done via command line flags such as
|
|
|
-`--initial-cluster` or `--discovery`. These flags can safely be left on the
|
|
|
-command line after your cluster is running but they will be ignored if you have
|
|
|
-a non-empty data dir. So, why did we decide to have this sort of odd UX?
|
|
|
-
|
|
|
-One of the design goals of etcd is easy bringup of clusters using a one-shot
|
|
|
-static configuration like AWS Cloud Formation, PXE booting, etc. Essentially we
|
|
|
-want to describe several virtual machines and bring them all up at once into an
|
|
|
-etcd cluster.
|
|
|
-
|
|
|
-To achieve this sort of hands-free cluster bootstrap we had two other options:
|
|
|
-
|
|
|
-**API to bootstrap**
|
|
|
-
|
|
|
-This is problematic because it cannot be coordinated from a single service file
|
|
|
-and we didn't want to have the etcd socket listening but unresponsive to
|
|
|
-clients for an unbound period of time.
|
|
|
-
|
|
|
-It would look something like this:
|
|
|
-
|
|
|
-```
|
|
|
-ExecStart=/usr/bin/etcd
|
|
|
-ExecStartPost/usr/bin/etcd init localhost:2379 --cluster=
|
|
|
-```
|
|
|
-
|
|
|
-**etcd init subcommand**
|
|
|
-
|
|
|
-```
|
|
|
-etcd init --cluster='default=http://localhost:2380,default=http://localhost:7001'...
|
|
|
-etcd init --discovery https://discovery-example.etcd.io/193e4
|
|
|
-```
|
|
|
-
|
|
|
-Then after running an init step you would execute `etcd`. This however
|
|
|
-introduced problems: we now have to define a hand-off protocol between the etcd
|
|
|
-init process and the etcd binary itself. This is hard to coordinate in a single
|
|
|
-service file such as:
|
|
|
-
|
|
|
-```
|
|
|
-ExecStartPre=/usr/bin/etcd init --cluster=....
|
|
|
-ExecStart=/usr/bin/etcd
|
|
|
-```
|
|
|
-
|
|
|
-There are several error cases:
|
|
|
-
|
|
|
-0) Init has already run and the data directory is already configured
|
|
|
-1) Discovery fails because of network timeout, etc
|
|
|
-2) Discovery fails because the cluster is already full and etcd needs to fall back to proxy
|
|
|
-3) Static cluster configuration fails because of conflict, misconfiguration or timeout
|
|
|
-
|
|
|
-In hindsight we could have made this work by doing:
|
|
|
-
|
|
|
-```
|
|
|
-rc status
|
|
|
-0 Init already ran
|
|
|
-1 Discovery fails on network timeout, etc
|
|
|
-0 Discovery fails for cluster full, coordinate via proxy state file
|
|
|
-1 Static cluster configuration failed
|
|
|
-```
|
|
|
-
|
|
|
-Perhaps we can add the init command in a future version and deprecate if the UX
|
|
|
-continues to confuse people.
|
Gyu-Ho Lee