Merge pull request #3255 from adellape/kubernetes-deployments

Bug 1384018: New "Kubernetes Deployments Support" topic

Author: adellape

_topic_map.yml

@@ -623,6 +623,9 @@ Topics:
         File: deployment_strategies
       - Name: Advanced Deployment Strategies
         File: advanced_deployment_strategies
+      - Name: Kubernetes Deployments Support
+        File: kubernetes_deployments
+        Distros: openshift-enterprise,openshift-origin 
   - Name: Getting Traffic Into The Cluster
     File: getting_traffic_into_cluster
   - Name: Routes

cli_reference/basic_cli_operations.adoc

@@ -107,6 +107,7 @@ syntax:
 |`build` |
 |`buildConfig` | `bc`
 |`deploymentConfig` | `dc`
+|`deployments` (Technology Preview)| `deploy`
 |`event` |`ev`
 |`imageStream` | `is`
 |`imageStreamTag` | `istag`
@@ -117,6 +118,7 @@ syntax:
 |`pod` |`po`
 |`ResourceQuota` | `quota`
 |`replicationController` |`rc`
+|`replicaSet` (Technology Preview)|`rs`
 |`secrets` |
 |`service` |`svc`
 |`ServiceAccount` | `serviceaccounts`

dev_guide/deployments/kubernetes_deployments.adoc

@@ -0,0 +1,196 @@
+[[dev-guide-kubernetes-deployments-support]]
+= Kubernetes Deployments Support
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+
+toc::[]
+
+== New Object Type: Deployments
+
+In the upstream Kubernetes project, a new first-class object type called
+_deployments_  was added in version 1.2. This object type (referred to here as
+_Kubernetes deployments_ for distinction) serves as a descendant of the
+deployment configuration object type that has been in {product-title} since
+ifdef::openshift-origin[]
+1.0.
+endif::[]
+ifdef::openshift-enterprise[]
+3.0.
+endif::[]
+Starting in {product-title}
+ifdef::openshift-origin[]
+1.4,
+endif::[]
+ifdef::openshift-enterprise[]
+3.4,
+endif::[]
+support for Kubernetes deployments is available as a
+ifdef::openshift-origin[]
+link:https://github.com/openshift/origin#alpha-and-unsupported-kubernetes-features[Tech Preview]
+endif::[]
+ifdef::openshift-enterprise[]
+link:https://access.redhat.com/support/offerings/techpreview[Technology Preview]
+endif::[]
+feature.
+
+Like deployment configurations, Kubernetes deployments describe the desired
+state of a particular component of an application as a pod template. Kubernetes
+deployments create _replica sets_ (an iteration of
+xref:../../architecture/core_concepts/deployments.adoc#replication-controllers[replication controllers]), which orchestrate pod lifecycles.
+
+For example, this definition of a Kubernetes deployment creates a replica set to
+bring up three nginx pods:
+
+.Example Kubernetes Deployment Definition *_nginx-deployment.yaml_*
+----
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: nginx
+spec:
+  replicas: 3
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.7.9
+        ports:
+        - containerPort: 80
+----
+
+After saving the definition to a local file, you could then use it to create a
+Kubernetes deployment:
+
+----
+$ oc create -f nginx-deployment.yaml
+----
+
+You can use the CLI to inspect and operate on Kubernetes deployments and replica
+sets like other object types, as described in
+xref:../../cli_reference/basic_cli_operations.adoc#oc-common-operations[Common
+Operations], like `get` and `describe`. For the object type, use `deployments`
+or `deploy` for Kubernetes deployments and `replicasets` or `rs` for replica
+sets.
+
+See the Kubernetes documentation for more details about
+link:http://kubernetes.io/docs/user-guide/deployments/[Deployments] and
+link:http://kubernetes.io/docs/user-guide/replicasets/[Replica Sets],
+substituting `oc` for `kubectl` in CLI usage examples.
+
+[[kubernetes-deployments-vs-deployment-configurations]]
+== Kubernetes Deployments vs Deployment Configurations
+
+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 Kubernetes deployments and switch to using them as a
+single object type that provides fine-grained management over applications.
+
+Kubernetes 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 Kubernetes deployments, you may want to use them instead
+of deployment configurations in {product-title} if you do not plan to use any of
+the following in particular:
+
+- xref:../../dev_guide/managing_images.adoc#dev-guide-managing-images[image streams]
+- xref:../../dev_guide/deployments/deployment_strategies.html#lifecycle-hooks[lifecycle hooks]
+- xref:../../dev_guide/deployments/deployment_strategies.html#custom-strategy[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.
+
+[[deployment-configuration-specific-features]]
+=== Deployment Configuration-Specific Features
+
+[[dc-vs-d-automatic-rollbacks]]
+==== Automatic Rollbacks
+
+Kubernetes deployments do not support automatically rolling back to the last
+successfully deployed replica set in case of a failure. This feature should be
+added soon.
+
+[[dc-vs-d-triggers]]
+==== Triggers
+
+Kubernetes deployments have an implicit `ConfigChange` trigger in that every
+change in the pod template of a deployment automatically triggers a new rollout.
+If you do not want new rollouts on pod template changes, pause the deployment:
+
+----
+$ oc rollout pause deployments/<name>
+----
+
+At the moment, Kubernetes 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 Kubernetes deployments, but it would be
+more desirable for it to exist as part of the Kubernetes core.
+
+[[dc-vs-d-lifecycle-hooks]]
+==== Lifecycle Hooks
+
+Kubernetes deployments do not support any lifecycle hooks.
+
+[[dc-vs-d-custom-strategies]]
+==== Custom Strategies
+
+Kubernetes deployments do not yet support user-specified Custom deployment
+strategies yet.
+
+[[dc-vs-d-canary-deployments]]
+==== Canary Deployments
+
+Kubernetes deployments do not yet run canaries as part of a new rollout.
+
+[[dc-vs-d-test-deployments]]
+==== Test Deployments
+
+Kubernetes deployments do not support running test tracks.
+
+[[kubernetes-deployments-specific-features]]
+=== Kubernetes Deployment-Specific Features
+
+[[dc-vs-d-rollover]]
+==== Rollover
+
+The deployment process for Kubernetes deployments is driven by a controller
+loop, in contrast to deployment configurations which use deployer pods for every
+new rollout. This means that a Kubernetes deployment 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.
+
+Deployment configurations can have at most one deployer pod running, otherwise
+multiple deployers end up fighting with each other 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 Kubernetes deployments.
+
+[[dc-vs-d-proportional-scaling]]
+==== Proportional Scaling
+
+Because the Kubernetes deployment controller is the sole source of truth for the sizes of
+new and old replica sets owned by a deployment, it is able to scale ongoing
+rollouts. Additional replicas are distributed proportionally based on the size
+of each replica set.
+
+Deployment configurations cannot be scaled when a rollout is ongoing because the
+deployment configuration controller will end up fighting with the deployer
+process about the size of the new replication controller.
+
+[[dc-vs-d-pausing-mid-rollout]]
+==== Pausing Mid-rollout
+
+Kubernetes 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
+rollout, the deployer process will not be affected and will continue until it
+finishes.