doc: Add design document #253

asymmetric · 2018-04-23T15:36:47Z

Explains:

Basic operations
Custom versioning
Sub-resources
peer-watch-file ConfigMap

Signed-off-by: Lorenzo Manacorda lorenzo@kinvolk.io

Closes #253.

krnowak · 2018-04-24T05:48:26Z

doc/design.md

+
+The `ConfigMap` is maintained by the operator in the following ways:
+
+* When it's empty, it populates it with the IP of one of the running `Pod`s (the


I think I would drop the notion of a leader here - I'm afraid it will be too confusing for Habitat users, because the leader you mention has nothing to do with any leader stuff in Habitat (neither with leader in service group with leader-follower topology nor with update leader in the service group).

krnowak · 2018-04-24T06:03:18Z

doc/design.md

+
+* When it's empty, it populates it with the IP of one of the running `Pod`s (the
+  so called "leader")
+* Whenever a leader dies, the operator replaces the IP in the `ConfigMap` with


Whenever the Pod dies

krnowak · 2018-04-24T06:03:55Z

doc/design.md

+* When it's empty, it populates it with the IP of one of the running `Pod`s (the
+  so called "leader")
+* Whenever a leader dies, the operator replaces the IP in the `ConfigMap` with
+  that of another running Pod, which becomes the new leader


Pod in backticks?

krnowak · 2018-04-24T06:05:32Z

doc/design.md

+
+Once the operator is running, it performs the following actions:
+
+* watches for new `Habitat` manifests and deploys corresponding sub-resources


In bullet points I prefer to start with a capital letter and end with a full dot.

You may have a different preference, but please make it at least consistent.

krnowak · 2018-04-24T06:14:14Z

doc/design.md

+
+## Sub-resources
+
+As mentioned above, the operator creates several resources whenever it detects a


That makes me think that maybe we should put a label on all the resources we create, so we could tell the users in this document how to recognize a resource that is managed by the operator.

I think we don't put any label on on Deployments and StatefulSets. We do it for ConfigMaps and Pods.

We do for Deployments and StatefulSets as well.

I'll add a mention of it here.

That's a pod template spec, so the pods are labeled. I rather expected the label to be also here for Deployments and here for StatefulSets.

Anyway, I checked it with kubectl and it indeed seems like Deployments and StatefulSets are labeled too. That's a bit magical.

asymmetric · 2018-04-24T10:22:32Z

PTALA.

indradhanush

Mostly nits and some doubts.

indradhanush · 2018-04-24T10:13:22Z

doc/design.md

+`ConfigMap`s, `Secret`s, `PersistentVolume`s) according to its definition.
+
+Another example is changing the Docker image inside a Habitat object. In this
+case, the operator first goes to all `StatefulSet`s it manages and updates them


s/Statefultsets/Statefulsets makes it easier to read in the rendered version.

But it's wrong !!! ;)

indradhanush · 2018-04-24T10:14:45Z

doc/design.md

+
+Another example is changing the Docker image inside a Habitat object. In this
+case, the operator first goes to all `StatefulSet`s it manages and updates them
+with the new Docker images; afterwards, all `Pod`s from each `StatefulSet` are


Same for "Pods" and other similar places.

indradhanush · 2018-04-24T10:22:23Z

doc/design.md

+In a non-Kubernetes Habitat setup, every service in a group after the first one
+is [started][hab-sg] with the `--peer` flag, pointing to the first service's IP.
+
+Since it's not possible in Kubernetes to launch some members with different


members of?

indradhanush · 2018-04-24T10:27:28Z

doc/design.md

+The `ConfigMap` is maintained by the operator in the following ways:
+
+* When it's empty, it populates it with the IP of one of the running `Pod`s
+* Wenever a `Pod` dies, it makes sure that the IP in the `ConfigMap` is still


Typo in "Wenever".

indradhanush · 2018-04-24T10:27:58Z

doc/design.md

+
+The `ConfigMap` is maintained by the operator in the following ways:
+
+* When it's empty, it populates it with the IP of one of the running `Pod`s


Maybe add a line or two on how the operator decides which Pod should become leader?

There is no leader no more! :) (@krnowak was right that it would confuse people)

indradhanush · 2018-04-24T10:29:50Z

doc/design.md

+considered read-only; any modifications to them will be overwritten by the
+operator.
+
+The proper way to make changes is **always** to make them on the Habitat object,


Nit: "is to always make them"

indradhanush · 2018-04-24T10:31:16Z

doc/design.md

+operator.
+
+The proper way to make changes is **always** to make them on the Habitat object,
+and let the operator figure out the actual steps it needs to take.


This is not very clear to me as someone unfamiliar with the operator. When you say make changes on the Habitat object what are other ways by which things can be changed? Do you mean changing the Pod resource for example?

Yes, that's the point of this section. Is that not clear enough? Suggestions?

indradhanush · 2018-04-24T10:33:16Z

doc/design.md

+According to [Semantic Versioning][semver], backwards incompatible changes require
+releasing a new major version. Unfortunately, it is [currently not
+possible][crd-vers] to run multiple versions of a CRD side-by-side. The
+work-around currently relies on two steps:


"work-around" should be one word.

krnowak

Some typos.

krnowak · 2018-04-24T12:25:57Z

doc/design.md

+is [started][hab-sg] with the `--peer` flag, pointing to the first service's IP.
+
+Since it's not possible in Kubernetes to launch `Pod`s in a
+`Deployment`/`StatefulSet`with different arguments, the operator resorts to


Space between "StatefulSet" and "with".

krnowak · 2018-04-24T12:26:53Z

doc/design.md

+
+* When it's empty, it populates it with the IP of one of the running `Pod`s
+(which `Pod` gets chosen is irrelevant, the important thing is that
+the`Pod` is in the `Running` state)


Space between "the" and "Pod".

This one is not fixed.

krnowak · 2018-04-24T12:27:51Z

doc/design.md

+possible][crd-vers] to run multiple versions of a CRD side-by-side. The
+workaround currently relies on two steps:
+
+* defining an additional field, `customVersion`


Capitalize "defining".

asymmetric · 2018-04-24T13:10:25Z

PTALAA.

asymmetric · 2018-04-25T09:20:53Z

I will squash the hell out of this PR.

indradhanush · 2018-04-26T05:46:18Z

krnowak · 2018-04-27T06:37:17Z

LFAD, but squash some commits first, please.

Explains: * Basic operations * Custom versioning * Sub-resources * `peer-watch-file` `ConfigMap` Signed-off-by: Lorenzo Manacorda <lorenzo@kinvolk.io>

`doc/` should be the home for all documentation, excluding the one that has a place in the root directory (usually files with CAPITALIZED names) Signed-off-by: Lorenzo Manacorda <lorenzo@kinvolk.io>

asymmetric requested review from krnowak, iaguis and indradhanush April 23, 2018 15:36

krnowak suggested changes Apr 24, 2018

View reviewed changes

indradhanush reviewed Apr 24, 2018

View reviewed changes

krnowak suggested changes Apr 24, 2018

View reviewed changes

krnowak mentioned this pull request Apr 25, 2018

Updating yaml for running stateful set gets reverted #248

Closed

krnowak approved these changes Apr 27, 2018

View reviewed changes

asymmetric force-pushed the asymmetric/design-doc branch from 840b4a4 to 65bd1da Compare April 30, 2018 11:10

Lorenzo Manacorda added 2 commits April 30, 2018 13:15

doc: Add design document

555d5bf

Explains: * Basic operations * Custom versioning * Sub-resources * `peer-watch-file` `ConfigMap` Signed-off-by: Lorenzo Manacorda <lorenzo@kinvolk.io>

doc: Move release.md under doc/

0d8b680

`doc/` should be the home for all documentation, excluding the one that has a place in the root directory (usually files with CAPITALIZED names) Signed-off-by: Lorenzo Manacorda <lorenzo@kinvolk.io>

asymmetric force-pushed the asymmetric/design-doc branch from 65bd1da to 0d8b680 Compare April 30, 2018 11:15

krnowak merged commit d6ec488 into habitat-sh:master May 2, 2018

asymmetric mentioned this pull request May 2, 2018

Design document #246

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: Add design document #253

doc: Add design document #253

asymmetric commented Apr 23, 2018 •

edited

Loading

krnowak Apr 24, 2018

krnowak Apr 24, 2018

krnowak Apr 24, 2018

krnowak Apr 24, 2018

krnowak Apr 24, 2018

asymmetric Apr 24, 2018

krnowak Apr 24, 2018

asymmetric commented Apr 24, 2018

indradhanush left a comment

indradhanush Apr 24, 2018

asymmetric Apr 24, 2018

indradhanush Apr 24, 2018

indradhanush Apr 24, 2018

indradhanush Apr 24, 2018

indradhanush Apr 24, 2018

asymmetric Apr 24, 2018

indradhanush Apr 24, 2018

indradhanush Apr 24, 2018

asymmetric Apr 24, 2018

indradhanush Apr 24, 2018

krnowak left a comment

krnowak Apr 24, 2018

krnowak Apr 24, 2018

krnowak Apr 25, 2018 •

edited

Loading

krnowak Apr 24, 2018

asymmetric commented Apr 24, 2018

asymmetric commented Apr 25, 2018

indradhanush commented Apr 26, 2018

krnowak commented Apr 27, 2018


		The `ConfigMap` is maintained by the operator in the following ways:

		* When it's empty, it populates it with the IP of one of the running `Pod`s (the


		Once the operator is running, it performs the following actions:

		* watches for new `Habitat` manifests and deploys corresponding sub-resources


		## Sub-resources

		As mentioned above, the operator creates several resources whenever it detects a

doc: Add design document #253

doc: Add design document #253

Conversation

asymmetric commented Apr 23, 2018 • 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

asymmetric commented Apr 24, 2018

indradhanush left a 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

krnowak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krnowak Apr 25, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

asymmetric commented Apr 24, 2018

asymmetric commented Apr 25, 2018

indradhanush commented Apr 26, 2018

krnowak commented Apr 27, 2018

asymmetric commented Apr 23, 2018 •

edited

Loading

krnowak Apr 25, 2018 •

edited

Loading