Documentation/learning: Glossary update #6531

sinsharat · 2016-09-27T15:27:54Z

added glossary items.
#6394

xiang90 · 2016-09-27T15:40:36Z

Documentation/learning/glossary.md

@@ -12,6 +12,10 @@ It has a unique identification, and records other nodes' progress internally whe

 Member is an instance of etcd. It hosts a node, and provides service to clients.

+## Machine (deprecated)


let's just remove machine?

sure will remove it.

xiang90 · 2016-09-27T15:43:05Z

Documentation/learning/glossary.md

@@ -26,10 +30,93 @@ Peer is another member of the same cluster.

 A proposal is a request (for example a write request, a configuration change request) that needs to go through raft protocol.

+## Quorum
+
+The number of members of a group/cluster required to be present to perform a set of instructions/operations, usually a majority.


The number of members of a cluster required to be available to perform requests (except for local request when specified). Quorum is the majority (N/2 + 1) of the cluster. For example, when there are 5 members in the cluster, the quorum is 3. When there are 6 members, the quorum is still 3. When there are 7 members, the quorum is 4.

sure will modify the description.

@xiang90 i had a doubt, for example when members are 6 the quorum should be 4 based on N/2+1. Do we have a special handling for this to keep it 3 only?

sorry. i made a mistake. it should be 4

ok no issues will correct it.
Thanks!

xiang90 · 2016-09-27T15:46:06Z

Documentation/learning/glossary.md

+
+## Transaction
+
+Transaction is a set of instructions which are to be performed as an atomic operation based on a certain set of conditions.


Transaction is a set of operations that are to be executed atomically based on a certain set of conditions.

ok will modify the description.

xiang90 · 2016-09-27T15:47:06Z

Documentation/learning/glossary.md

+## Keys
+
+Keys are unique idetifiers. Keys are used to store values to the store and the values can be retrieved from the store using the keys.
+In certain cases like server certification a key can be referred to as a unique identifier used for encrypting the values.


remove the second sentence? it is not etcd specific.

ok. will remove it. But i thought we support certificates.

xiang90 · 2016-09-27T15:47:51Z

Documentation/learning/glossary.md

+
+## Lease
+
+Lease is a contract given for a specified time. It can be used to attach to the keys to make keys available as long as the lease lasts. Once the lease expires all the keys associated with it also expire.


for a specified duration?

ok will modify it.

xiang90 · 2016-09-27T15:48:39Z

Documentation/learning/glossary.md

+
+Revision is the current revision of etcd. It is incremented every time the v3 backed is modified (e.g., Put, Delete, Txn).
+
+## ModRevision


Every time a key gets updated the modRevision gets updated to the current revision of the store.

ok will modify the description.

xiang90 · 2016-09-27T15:48:54Z

Documentation/learning/glossary.md

+
+ModRevision is the etcd revision of the last update done on a key. Every time a key gets updated the modrevision gets incremented by 1.
+
+## Version


Version of the key

@xiang90 i had mentioned both the cases(key version as well as etcd server and API version) under the version title. Do you want me to mention them separately?

@xiang90 need your opinion on this.
Thanks!

Yes. I want to make them separate. Actually I think software version is not etcd specific. i do not think we need to mention it.

ok will remove that part then.

xiang90 · 2016-09-27T15:49:31Z

Documentation/learning/glossary.md

+
+## Version
+
+Version is the number of times the key has been modified since it was created.


The version of a newly created key is 1. Once a key get deleted, the version of the key gets back to 0.

ok will modify the description.

xiang90 · 2016-09-27T15:49:56Z

Documentation/learning/glossary.md

+
+## Watches
+
+Watches are used by clients to watch over a specified key or a apecified set of keys.


When there is a modification on the watched keys, watchers will be notified.

ok will modify the description.

xiang90 · 2016-09-27T15:51:33Z

Documentation/learning/glossary.md

+
+Mirroring is a process of mirroring a prefix in the key-value space of an etcd cluster into another prefix in another cluster. Mirroring is designed for copying configuration to various clusters distributed around the world.
+
+## Migration


let's remove this? i want this doc to be v3 centric.

ok will remove it.

xiang90 · 2016-09-27T15:53:18Z

Let's group this a little bit? We can order them alphabetically? @heyitsanthony opinions?

sinsharat · 2016-09-27T15:54:05Z

@xiang90 yes i was thinking the same to keep it in alphabetical order. Will organize them like that.

sinsharat · 2016-09-27T17:00:01Z

@xiang90 i have done the changes as per your suggestion. Let me know if any other change is required.
Thank you!

xiang90 · 2016-09-27T17:00:39Z

LGTM. Defer to @heyitsanthony and @gyuho

heyitsanthony · 2016-09-27T20:38:15Z

Documentation/learning/glossary.md


-Node is an instance of raft state machine.
+Alarms are a means to recognize any fault in the etcd server.


The quota alarm isn't really a fault. How about: The etcd server raises an alarm whenever the cluster needs operator intervention to remain reliable.

ok sure will modify the description.

heyitsanthony · 2016-09-27T20:42:33Z

Documentation/learning/glossary.md


-## Member
+Authentication is used to authenticate a user before the user can perform a set of operations.


This is not a good definition because it's referencing itself (i.e., x is used to x). Try: Authentication manages user access permissions for etcd resources.

yes you are right will modify it.

heyitsanthony · 2016-09-27T20:48:57Z

Documentation/learning/glossary.md

-Member is an instance of etcd. It hosts a node, and provides service to clients.
+## Client
+
+Client is a caller of the cluster's HTTP API.


this isn't true, there are grpc clients as well.
A client connects to the etcd cluster to issue service requests such as fetching key-value pairs, writing data, or watching for updates.

i didn't modify this definition it was there from before. But will correct it.

heyitsanthony · 2016-09-27T20:49:32Z

Documentation/learning/glossary.md


 ## Cluster

 Cluster consists of several members.

 The node in each member follows raft consensus protocol to replicate logs. Cluster receives proposals from members, commits them and apply to local store.

+## Command


I don't think this is really etcd jargon. Remove?

sure will remove it.

heyitsanthony · 2016-09-27T20:54:55Z

Documentation/learning/glossary.md

+
+## Compaction
+
+Compaction discards all etcd event history prior to a given revision. Since etcd uses a multiversion concurrency control model, it preserves all key updates as event history. When the event history up to some revision is no longer needed, all superseded keys may be compacted away to reclaim storage space in the etcd backend database.


I don't think it needs to explain that etcd is MVCC?
Compaction discards all etcd event history and superseded keys prior to a given revision. It is used to reclaim storage space in the etcd backend database.

sure will modify the definition.

heyitsanthony · 2016-09-27T22:04:15Z

Documentation/learning/glossary.md

+
+## Transaction
+
+Transaction is a set of operations that are to be executed atomically based on a certain set of conditions.


I don't think the set of conditions stuff is necessary since people will see that when they try to create a transaction.

An atomically executed set of operations. All modified keys in a transaction share the same modification revision.

ok will change it

heyitsanthony · 2016-09-27T22:04:55Z

Documentation/learning/glossary.md

+
+Transaction is a set of operations that are to be executed atomically based on a certain set of conditions.
+
+## Version of the key


Key version, the "of the' is superfluous

ok will change it

heyitsanthony · 2016-09-27T22:08:09Z

Documentation/learning/glossary.md

+## Version of the key
+
+Version is the number of times the key has been modified since it was created.
+The version of a newly created key is 1. Once a key get deleted, the version of the key gets back to 0.


The number of writes to a key since it was created, starting at 1. The version of a nonexistent or deleted key is 0.

ok will chnage it.

heyitsanthony · 2016-09-27T22:24:01Z

Documentation/learning/glossary.md


-The alternative of Member in etcd before 2.0
+Watches are used by clients to watch over a specified key or a specified set of keys.


this is a circular definition Xes are used by clients to X and watches don't work on arbitrary sets

A client opens a watcher to observe updates on a given key range.

ok will change the definition.

heyitsanthony · 2016-09-27T22:29:50Z

Documentation/learning/glossary.md

+## Keys
+
+Keys are unique idetifiers. Keys are used to store values to the store and the values can be retrieved from the store using the keys.
+


probably should define ranges too since they're used everywhere

## Key range A set of keys containing either an individual key, a lexical interval for all x such that a < x <= b, or all keys greater than a given key.

will add it.

sinsharat · 2016-09-28T05:41:16Z

@heyitsanthony i have done the changes as per your suggestion. I have tweaked your lease suggestion a bit to make it clear. let me know if its fine with you.
Also i would like you to re-look at the definition you provided for mod revision, because i feel it's defined more in technical term which users might find difficult to understand and the glossary is meant for new etcd users who might not be familiar with these technicality.
Thank you!

heyitsanthony · 2016-09-28T18:17:17Z

lgtm

xiang90 reviewed Sep 27, 2016

View reviewed changes

heyitsanthony suggested changes Sep 27, 2016

View reviewed changes

Documentation/learning: Glossary update

6c2414e

heyitsanthony approved these changes Sep 28, 2016

View reviewed changes

gyuho merged commit 0ca0260 into etcd-io:master Sep 28, 2016

sinsharat deleted the glossary_update branch September 28, 2016 20:37

		@@ -12,6 +12,10 @@ It has a unique identification, and records other nodes' progress internally whe

		Member is an instance of etcd. It hosts a node, and provides service to clients.

		## Machine (deprecated)


		## Transaction

		Transaction is a set of instructions which are to be performed as an atomic operation based on a certain set of conditions.


		## Lease

		Lease is a contract given for a specified time. It can be used to attach to the keys to make keys available as long as the lease lasts. Once the lease expires all the keys associated with it also expire.


		Revision is the current revision of etcd. It is incremented every time the v3 backed is modified (e.g., Put, Delete, Txn).

		## ModRevision


		ModRevision is the etcd revision of the last update done on a key. Every time a key gets updated the modrevision gets incremented by 1.

		## Version


		## Version

		Version is the number of times the key has been modified since it was created.


		## Watches

		Watches are used by clients to watch over a specified key or a apecified set of keys.


		Mirroring is a process of mirroring a prefix in the key-value space of an etcd cluster into another prefix in another cluster. Mirroring is designed for copying configuration to various clusters distributed around the world.

		## Migration


		Node is an instance of raft state machine.
		Alarms are a means to recognize any fault in the etcd server.


		## Member
		Authentication is used to authenticate a user before the user can perform a set of operations.


		## Compaction

		Compaction discards all etcd event history prior to a given revision. Since etcd uses a multiversion concurrency control model, it preserves all key updates as event history. When the event history up to some revision is no longer needed, all superseded keys may be compacted away to reclaim storage space in the etcd backend database.


		Transaction is a set of operations that are to be executed atomically based on a certain set of conditions.

		## Version of the key


		The alternative of Member in etcd before 2.0
		Watches are used by clients to watch over a specified key or a specified set of keys.

		## Keys

		Keys are unique idetifiers. Keys are used to store values to the store and the values can be retrieved from the store using the keys.

Documentation/learning: Glossary update #6531

Documentation/learning: Glossary update #6531

Conversation

sinsharat commented Sep 27, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xiang90 commented Sep 27, 2016

sinsharat commented Sep 27, 2016

sinsharat commented Sep 27, 2016

xiang90 commented Sep 27, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heyitsanthony Sep 27, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heyitsanthony Sep 27, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heyitsanthony Sep 27, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sinsharat commented Sep 28, 2016

heyitsanthony commented Sep 28, 2016

sinsharat commented Sep 27, 2016 •

edited

Loading

heyitsanthony Sep 27, 2016 •

edited

Loading

heyitsanthony Sep 27, 2016 •

edited

Loading

heyitsanthony Sep 27, 2016 •

edited

Loading