Merge pull request #14168 from bergerhoffer/OSDOCS-317

OSDOCS-317: Clarifications for deployment and dc comparison

Author: bergerhoffer

modules/deployments-comparing-deploymentconfigs.adoc

@@ -5,25 +5,33 @@
 [id="deployments-comparing-deploymentconfigs-{context}"]
 = Comparing Deployments and DeploymentConfigs
 
-Because deployment configurations existed in {product-title} prior to
-deployments being added in Kubernetes 1.2, the latter object type naturally
-diverges slightly from the former. The long-term goal in {product-title} is to reach
-full feature parity in Deployments and switch to using them as a
-single object type that provides fine-grained management over applications.
-
-Deployments are supported to ensure upstream projects and examples that use the
-new object type can run smoothly on {product-title}. Given the current feature
-set of Deployments, you might want to use them instead of deployment
-configurations in {product-title} if you do not plan to use any of the following
-in particular:
-
-- Image streams
-- Lifecycle hooks
-- Custom deployment strategies
-
-The following sections go into more details on the differences between the two
-object types to further help you decide when you might want to use Kubernetes
-deployments over deployment configurations.
+Both Kubernetes Deployments and {product-title}-provided
+DeploymentConfigs are supported in {product-title}; however, it is
+recommended to use Deployments unless you need a specific feature or behavior
+provided by DeploymentConfigs.
+
+The following sections go into more detail on the differences between the two
+object types to further help you decide which type to use.
+
+[id='deployments-design-{context}']
+== Design
+
+One important difference between Deployments and DeploymentConfigs is the
+properties of the link:https://en.wikipedia.org/wiki/CAP_theorem[CAP theorem]
+that each design has chosen for the rollout process. DeploymentConfigs prefer
+consistency, whereas Deployments take availability over consistency.
+
+For DeploymentConfigs, if a node running a deployer Pod goes down, it will
+not get replaced. The process waits until the node comes back online or is
+manually deleted. Manually deleting the node also deletes the corresponding Pod.
+This means that you can not delete the Pod to unstick the rollout, as the
+kubelet is responsible for deleting the associated Pod.
+
+However, Deployments rollouts are driven from a controller manager. The
+controller manager runs in high availability mode on masters and uses leader
+election algorithms to value availability over consistency. During a failure it
+is possible for other masters to act on the same Deployment at the same time,
+but this issue will be reconciled shortly after the failure occurs.
 
 [id="delpoymentconfigs-specific-features-{context}"]
 == DeploymentConfigs-specific features
@@ -45,46 +53,30 @@ If you do not want new rollouts on pod template changes, pause the deployment:
 $ oc rollout pause deployments/<name>
 ----
 
-Currently, Deployments do not support `ImageChange` triggers. A generic
-triggering mechanism has been proposed upstream, but it is unknown if and when
-it may be accepted. Eventually, a {product-title}-specific mechanism could be
-implemented to layer on top of Deployments, but it would be more desirable for
-it to exist as part of the Kubernetes core.
-
 [discrete]
 ==== Lifecycle hooks
 
-Deployments do not support any lifecycle hooks.
+Deployments do not yet support any lifecycle hooks.
 
 [discrete]
 ==== Custom strategies
 
-Deployments do not yet support user-specified Custom deployment
+Deployments do not support user-specified Custom deployment
 strategies yet.
 
-[discrete]
-==== Canary deployments
-
-Deployments do not yet run canaries as part of a new rollout.
-
-[discrete]
-==== Test deployments
-
-Deployments do not support running test tracks.
-
 [id="delpoyments-specific-features-{context}"]
 == Deployments-specific features
 
 [discrete]
 ==== Rollover
 
 The deployment process for Deployments is driven by a controller
-loop, in contrast to deployment configurations which use deployer pods for every
+loop, in contrast to DeploymentConfigs which use deployer pods for every
 new rollout. This means that a Deployment can have as many active
 ReplicaSets as possible, and eventually the deployment controller will scale
 down all old ReplicaSets and scale up the newest one.
 
-Deployment configurations can have at most one deployer pod running, otherwise
+DeploymentConfigs can have at most one deployer pod running, otherwise
 multiple deployers end up conflicting while trying to scale up what they think
 should be the newest ReplicationController. Because of this, only two
 ReplicationControllers can be active at any point in time. Ultimately, this
@@ -94,19 +86,19 @@ translates to faster rapid rollouts for Deployments.
 ==== Proportional scaling
 
 Because the Deployment controller is the sole source of truth for the sizes of
-new and old ReplicaSets owned by a deployment, it is able to scale ongoing
+new and old ReplicaSets owned by a Deployment, it is able to scale ongoing
 rollouts. Additional replicas are distributed proportionally based on the size
 of each ReplicaSet.
 
-Deployment configurations cannot be scaled when a rollout is ongoing because the
-deployment configuration controller will end up having issues with the deployer
+DeploymentConfigs cannot be scaled when a rollout is ongoing because the
+DeploymentConfig controller will end up having issues with the deployer
 process about the size of the new ReplicationController.
 
 [discrete]
 ==== Pausing mid-rollout
 
 Deployments can be paused at any point in time, meaning you can also
 pause ongoing rollouts. On the other hand, you cannot pause deployer pods
-currently, so if you try to pause a deployment configuration in the middle of a
+currently, so if you try to pause a DeploymentConfig in the middle of a
 rollout, the deployer process will not be affected and will continue until it
 finishes.