OCPBUGS 4543: Prioritizing deployments over deployment configs

applications/deployments/what-deployments-are.adoc

@@ -8,10 +8,12 @@ toc::[]
 
 The `Deployment` and `DeploymentConfig` API objects in {product-title} provide two similar but different methods for fine-grained management over common user applications. They are composed of the following separate API objects:
 
-* A `DeploymentConfig` or `Deployment` object, either of which describes the desired state of a particular component of the application as a pod template.
-* `DeploymentConfig` objects involve one or more _replication controllers_, which contain a point-in-time record of the state of a deployment as a pod template. Similarly, `Deployment` objects involve one or more _replica sets_, a successor of replication controllers.
+* A `Deployment` or `DeploymentConfig` object, either of which describes the desired state of a particular component of the application as a pod template.
+* `Deployment` objects involve one or more _replica sets_, which contain a point-in-time record of the state of a deployment as a pod template. Similarly, `DeploymentConfig` objects involve one or more _replication controllers_, which preceded replica sets.
 * One or more pods, which represent an instance of a particular version of an application.
 
+Use `Deployment` objects unless you need a specific feature or behavior provided by `DeploymentConfig` objects.
+
 ////
 Update when converted:
 [role="_additional-resources"]
@@ -31,7 +33,7 @@ xref:../../dev_guide/pod_autoscaling.adoc#dev-guide-pod-autoscaling[autoscaling]
 
 Deployments and deployment configs are enabled by the use of native Kubernetes API objects `ReplicaSet` and `ReplicationController`, respectively, as their building blocks.
 
-Users do not have to manipulate replication controllers, replica sets, or pods owned by `DeploymentConfig` objects or deployments. The deployment systems ensure changes are propagated appropriately.
+Users do not have to manipulate replica sets, replication controllers, or pods owned by `Deployment` or `DeploymentConfig` objects. The deployment systems ensure changes are propagated appropriately.
 
 [TIP]
 ====
@@ -40,11 +42,12 @@ If the existing deployment strategies are not suited for your use case and you m
 
 The following sections provide further details on these objects.
 
-include::modules/deployments-replicationcontrollers.adoc[leveloffset=+2]
 include::modules/deployments-replicasets.adoc[leveloffset=+2]
+include::modules/deployments-replicationcontrollers.adoc[leveloffset=+2]
 
-include::modules/deployments-deploymentconfigs.adoc[leveloffset=+1]
 include::modules/deployments-kube-deployments.adoc[leveloffset=+1]
+include::modules/deployments-deploymentconfigs.adoc[leveloffset=+1]
+
 include::modules/deployments-comparing-deploymentconfigs.adoc[leveloffset=+1]
 ////
 Update when converted:

modules/deployments-comparing-deploymentconfigs.adoc

@@ -18,6 +18,28 @@ For `DeploymentConfig` objects, if a node running a deployer pod goes down, it w
 
 However, deployment 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="delpoyments-specific-features_{context}"]
+== Deployment-specific features
+
+[discrete]
+==== Rollover
+
+The deployment process for `Deployment` objects is driven by a controller loop, in contrast to `DeploymentConfig` objects that use deployer pods for every new rollout. This means that the `Deployment` object can have as many active replica sets as possible, and eventually the deployment controller will scale down all old replica sets and scale up the newest one.
+
+`DeploymentConfig` objects can have at most one deployer pod running, otherwise multiple deployers might conflict when trying to scale up what they think should be the newest replication controller. Because of this, only two replication controllers can be active at any point in time. Ultimately, this results in faster rapid rollouts for `Deployment` objects.
+
+[discrete]
+==== Proportional scaling
+
+Because the deployment controller is the sole source of truth for the sizes of new and old replica sets owned by a `Deployment` object, it can scale ongoing rollouts. Additional replicas are distributed proportionally based on the size of each replica set.
+
+`DeploymentConfig` objects cannot be scaled when a rollout is ongoing because the controller will have issues with the deployer process about the size of the new replication controller.
+
+[discrete]
+==== Pausing mid-rollout
+
+Deployments can be paused at any point in time, meaning you can also pause ongoing rollouts. However, you currently cannot pause deployer pods; if you try to pause a deployment in the middle of a rollout, the deployer process is not affected and continues until it finishes.
+
 [id="delpoymentconfigs-specific-features_{context}"]
 == DeploymentConfig object-specific features
 
@@ -45,27 +67,4 @@ Deployments do not yet support any lifecycle hooks.
 [discrete]
 ==== Custom strategies
 
-Deployments do not support user-specified custom deployment strategies yet.
-
-[id="delpoyments-specific-features_{context}"]
-== Deployment-specific features
-
-[discrete]
-==== Rollover
-
-The deployment process for `Deployment` objects is driven by a controller loop, in contrast to `DeploymentConfig` objects which use deployer pods for every new rollout. This means that the `Deployment` object can have as many active replica sets as possible, and eventually the deployment controller will scale down all old replica sets and scale up the newest one.
-
-`DeploymentConfig` objects 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 replication controller. Because of this, only two replication controllers can be active at any point in time. Ultimately, this translates to faster rapid rollouts for `Deployment` objects.
-
-[discrete]
-==== Proportional scaling
-
-Because the deployment controller is the sole source of truth for the sizes of new and old replica sets owned by a `Deployment` object, it is able to scale ongoing rollouts. Additional replicas are distributed proportionally based on the size of each replica set.
-
-`DeploymentConfig` objects cannot be scaled when a rollout is ongoing because the controller will end up having issues with the deployer process about the size of the new replication controller.
-
-[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 in the middle of a rollout, the deployer process will not be affected and will continue until it finishes.
+Deployments do not support user-specified custom deployment strategies.

modules/deployments-kube-deployments.adoc

@@ -5,9 +5,7 @@
 [id="deployments-kube-deployments_{context}"]
 = Deployments
 
-Kubernetes provides a first-class, native API object type in {product-title} called `Deployment`. `Deployment` objects serve as a descendant of the {product-title}-specific `DeploymentConfig` object.
-
-Like `DeploymentConfig` objects, `Deployment` objects describe the desired state of a particular component of an application as a pod template. Deployments create replica sets, which orchestrate pod lifecycles.
+Kubernetes provides a first-class, native API object type in {product-title} called `Deployment`. `Deployment` objects describe the desired state of a particular component of an application as a pod template. Deployments create replica sets, which orchestrate pod lifecycles.
 
 For example, the following deployment definition creates a replica set to bring up one `hello-openshift` pod:
 

modules/deployments-replicasets.adoc

@@ -5,7 +5,7 @@
 [id="deployments-repliasets_{context}"]
 = Replica sets
 
-Similar to a replication controller, a `ReplicaSet` is a native Kubernetes API object that ensures a specified number of pod replicas are running at any given time. The difference between a replica set and a replication controller is that a replica set supports set-based selector requirements whereas a replication controller only supports equality-based selector requirements.
+A `ReplicaSet` is a native Kubernetes API object that ensures a specified number of pod replicas are running at any given time. 
 
 [NOTE]
 ====

modules/deployments-replicationcontrollers.adoc

@@ -5,7 +5,7 @@
 [id="deployments-replicationcontrollers_{context}"]
 = Replication controllers
 
-A replication controller ensures that a specified number of replicas of a pod are running at all times. If pods exit or are deleted, the replication controller acts to instantiate more up to the defined number. Likewise, if there are more running than desired, it deletes as many as necessary to match the defined amount.
+Similar to a replica set, a replication controller ensures that a specified number of replicas of a pod are running at all times. If pods exit or are deleted, the replication controller instantiates more up to the defined number. Likewise, if there are more running than desired, it deletes as many as necessary to match the defined amount. The difference between a replica set and a replication controller is that a replica set supports set-based selector requirements whereas a replication controller only supports equality-based selector requirements.
 
 A replication controller configuration consists of:
 
@@ -18,6 +18,13 @@ A selector is a set of labels assigned to the pods that are managed by the repli
 The replication controller does not perform auto-scaling based on load or traffic, as it does not track either. Rather, this requires its replica
 count to be adjusted by an external auto-scaler.
 
+[NOTE]
+====
+Use a `DeploymentConfig` to create a replication controller instead of creating replication controllers directly.
+
+If you require custom orchestration or do not require updates, use replica sets instead of replication controllers.
+====
+
 The following is an example definition of a replication controller:
 
 [source,yaml]