From d3c8f9e856b6ec45370d925486d2f8f2c0b46153 Mon Sep 17 00:00:00 2001 From: Gyu-Ho Lee Date: Tue, 22 Aug 2017 10:18:50 -0700 Subject: [PATCH] Documentation/v2: remove implementation detail Signed-off-by: Gyu-Ho Lee --- Documentation/v2/implementation-faq.md | 70 -------------------------- 1 file changed, 70 deletions(-) delete mode 100644 Documentation/v2/implementation-faq.md diff --git a/Documentation/v2/implementation-faq.md b/Documentation/v2/implementation-faq.md deleted file mode 100644 index 027c47aaf03..00000000000 --- a/Documentation/v2/implementation-faq.md +++ /dev/null @@ -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.