OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Deployments

Overview

A deployment in OpenShift is a replication controller based on a user defined template called a deployment configuration. Deployments are created manually or in response to triggered events.

The deployment system provides:

  • A deployment configuration, which is a template for deployments.

  • Triggers that drive automated deployments in response to events.

  • User-customizable strategies to transition from the previous deployment to the new deployment.

  • Rollbacks to a previous deployment.

  • Manual replication scaling.

The deployment configuration contains a version number that is incremented each time a new deployment is created from that configuration. In addition, the cause of the last deployment is added to the configuration.

Creating a Deployment Configuration

A deployment configuration consists of the following key parts:

  • A replication controller template which describes the application to be deployed.

  • The default replica count for the deployment.

  • A deployment strategy which will be used to execute the deployment.

  • A set of triggers which cause deployments to be created automatically.

Deployment configurations are deploymentConfig OpenShift API resources which can be managed with the oc command like any other resource. The following is an example of a deploymentConfig resource:

{
  "kind": "DeploymentConfig",
  "apiVersion": "v1",
  "metadata": {
    "name": "frontend"
  },
  "spec": {
    "template": { (1)
      "metadata": {
        "labels": {
          "name": "frontend"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "helloworld",
            "image": "openshift/origin-ruby-sample",
            "ports": [
              {
                "containerPort": 8080,
                "protocol": "TCP"
              }
            ]
          }
        ]
      }
    }
    "replicas": 5, (2)
    "selector": {
      "name": "frontend"
    },
    "triggers": [
      {
        "type": "ConfigChange" (3)
      },
      {
        "type": "ImageChange", (4)
        "imageChangeParams": {
          "automatic": true,
          "containerNames": [
            "helloworld"
          ],
          "from": {
            "kind": "ImageStreamTag",
            "name": "origin-ruby-sample:latest"
          }
        }
      }
    ],
    "strategy": { (5)
      "type": "Rolling"
    }
  }
}
1 The replication controller template named frontend describes a simple Ruby application.
2 There will be 5 replicas of frontend by default.
3 A configuration change trigger causes a new deployment to be created any time the replication controller template changes.
4 An image change trigger trigger causes a new deployment to be created each time a new version of the origin-ruby-sample:latest image repository is available.
5 The Rolling strategy is the default and may be omitted.

Starting a Deployment

To start a new deployment manually:

$ oc deploy <deployment_config> --latest
If there’s already a deployment in progress, the command will display a message and a new deployment will not be started.

Viewing a Deployment

To get basic information about recent deployments:

$ oc deploy <deployment_config>

This will show details about the latest and recent deployments, including any currently running deployment.

For more detailed information about a deployment configuration and the latest deployment:

$ oc describe dc <deployment_config>

Canceling a Deployment

To cancel a running or stuck deployment:

$ oc deploy <deployment_config> --cancel
The cancellation is a best-effort operation, and may take some time to complete. It’s possible the deployment will partially or totally complete before the cancellation is effective.

Retrying a Deployment

To retry the last failed deployment:

$ oc deploy <deployment_config> --retry

If the last deployment didn’t fail, the command will display a message and the deployment will not be retried.

Retrying a deployment restarts the deployment and does not create a new deployment version. The restarted deployment will have the same configuration it had when it failed.

Rolling Back a Deployment

Rollbacks revert an application back to a previous deployment and can be performed using the REST API or the CLI.

To rollback to the last successful deployment:

$ oc rollback <deployment_config>

The deployment configuration’s template will be reverted to match the deployment specified in the rollback command, and a new deployment will be started.

Image change triggers on the deployment configuration are disabled as part of the rollback to prevent unwanted deployments soon after the rollback is complete. To re-enable the image change triggers:

$ oc deploy <deployment_config> --enable-triggers

To roll back to a specific version:

$ oc rollback <deployment_config> --to-version=1

To see what the rollback would look like without performing the rollback:

$ oc rollback <deployment_config> --dry-run

Triggers

A deployment configuration can contain triggers, which drive the creation of new deployments in response to events, both inside and outside OpenShift.

If no triggers are defined on a deployment configuration, deployments must be started manually.

Configuration Change Trigger

The ConfigChange trigger results in a new deployment whenever changes are detected to the replication controller template of the deployment configuration.

If a ConfigChange trigger is defined on a deployment configuration, the first deployment will be automatically created soon after the deployment configuration itself is created.

The following is an example of a ConfigChange trigger:

"triggers": [
  {
    "type": "ConfigChange"
  }
]

Image Change Trigger

The ImageChange trigger results in a new deployment whenever the value of an image stream tag changes.

The following is an example of an ImageChange trigger:

"triggers": [
  {
    "type": "ImageChange",
    "imageChangeParams": {
      "automatic": true, (1)
      "from": {
        "kind": "ImageStreamTag",
        "name": "origin-ruby-sample:latest"
      },
      "containerNames": [
        "helloworld"
      ]
    }
  }
]
1 If the automatic option is set to false, the trigger is disabled.

With the above example, when the latest tag value of the origin-ruby-sample image stream changes and the new tag value differs from the current image specified in the deployment configuration’s helloworld container, a new deployment is created using the new tag value for the helloworld container.

Strategies

A deployment strategy determines the deployment process, and is defined by the deployment configuration. Each application has different requirements for availability (and other considerations) during deployments. OpenShift provides strategies to support a variety of deployment scenarios.

A deployment strategy uses readiness checks to determine if a new pod is ready for use. If a readiness check fails, the deployment is stopped.

The Rolling strategy is the default strategy used if no strategy is specified on a deployment configuration.

Rolling Strategy

The rolling strategy performs a rolling update and supports lifecycle hooks for injecting code into the deployment process.

The rolling deployment strategy waits for pods to pass their readiness check before scaling down old components, and does not allow pods that do not pass their readiness check within a configurable timeout.

The following is an example of the Rolling strategy:

"strategy": {
  "type": "Rolling",
  "rollingParams": {
    "timeoutSeconds": 120, (1)
    "maxSurge": "20%", (2)
    "maxUnavailable": "10%" (3)
    "pre": {}, (4)
    "post": {}
  }
}
1 How long to wait for a scaling event before giving up. Optional; the default is 120.
2 maxSurge is optional and defaults to 25%; see below.
3 maxUnavailable is optional and defaults to 25%; see below.
4 pre and post are both lifecycle hooks.

The Rolling strategy will:

  1. Execute any pre lifecycle hook.

  2. Scale up the new deployment based on the surge configuration.

  3. Scale down the old deployment based on the max unavailable configuration.

  4. Repeat this scaling until the new deployment has reached the desired replica count and the old deployment has been scaled to zero.

  5. Execute any post lifecycle hook.

When scaling down, the Rolling strategy waits for pods to become ready so it can decide whether further scaling would affect availability. If scaled up pods never become ready, the deployment will eventually time out and result in a deployment failure.

When executing the post lifecycle hook, all failures will be ignored regardless of the failure policy specified on the hook.

The maxUnavailable parameter is the maximum number of pods that can be unavailable during the update. The maxSurge parameter is the maximum number of pods that can be scheduled above the original number of pods. Both parameters can be set to either a percentage (e.g., 10%) or an absolute value (e.g., 2). The default value for both is 25%.

These parameters allow the deployment to be tuned for availability and speed. For example:

  • maxUnavailable=0 and maxSurge=20% ensures full capacity is maintained during the update and rapid scale up.

  • maxUnavailable=10% and maxSurge=0 performs an update using no extra capacity (an in-place update).

  • maxUnavailable=10% and maxSurge=10% scales up and down quickly with some potential for capacity loss.

Recreate Strategy

The Recreate strategy has basic rollout behavior and supports lifecycle hooks for injecting code into the deployment process.

The following is an example of the Recreate strategy:

"strategy": {
  "type": "Recreate",
  "recreateParams": { (1)
    "pre": {}, (2)
    "post": {}
  }
}
1 recreateParams are optional.
2 pre and post are both lifecycle hooks.

The Recreate strategy will:

  1. Execute any "pre" lifecycle hook.

  2. Scale down the previous deployment to zero.

  3. Scale up the new deployment.

  4. Execute any "post" lifecycle hook.

During scale up, if the replica count of the deployment is greater than one, the first replica of the deployment will be validated for readiness before fully scaling up the deployment. If the validation of the first replica fails, the deployment will be considered a failure.
When executing the "post" lifecycle hook, all failures will be ignored regardless of the failure policy specified on the hook.

Custom Strategy

The Custom strategy allows you to provide your own deployment behavior.

The following is an example of the Custom strategy:

"strategy": {
  "type": "Custom",
  "customParams": {
    "image": "organization/strategy",
    "command": ["command", "arg1"],
    "environment": [
      {
        "name": "ENV_1",
        "value": "VALUE_1"
      }
    ]
  }
}

In the above example, the organization/strategy Docker image provides the deployment behavior. The optional command array overrides any CMD directive specified in the image’s Dockerfile. The optional environment variables provided are added to the execution environment of the strategy process.

Additionally, OpenShift provides the following environment variables to the strategy process:

Environment Variable Description

OPENSHIFT_DEPLOYMENT_NAME

The name of the new deployment (a replication controller).

OPENSHIFT_DEPLOYMENT_NAMESPACE

The namespace of the new deployment.

The replica count of the new deployment will initially be zero. The responsibility of the strategy is to make the new deployment active using the logic that best serves the needs of the user.

Lifecycle Hooks

The Recreate and Rolling strategies support lifecycle hooks, which allow behavior to be injected into the deployment process at predefined points within the strategy:

The following is an example of a "pre" lifecycle hook:

"pre": {
  "failurePolicy": "Abort",
  "execNewPod": {} (1)
}
1 execNewPod is a pod-based lifecycle hook.

Every hook has a failurePolicy, which defines the action the strategy should take when a hook failure is encountered:

Abort

The deployment should be considered a failure if the hook fails.

Retry

The hook execution should be retried until it succeeds.

Ignore

Any hook failure should be ignored and the deployment should proceed.
Some hook points for a strategy might support only a subset of failure policy values. For example, the Recreate and Rolling strategies do not currently support the Abort policy for a "post" deployment lifecycle hook. Consult the documentation for a given strategy for details on any restrictions regarding lifecycle hooks.

Hooks have a type-specific field that describes how to execute the hook. Currently pod-based hooks are the only supported hook type, specified by the execNewPod field.

Pod-based Lifecycle Hook

Pod-based lifecycle hooks execute hook code in a new pod derived from the template in a deployment configuration.

The following simplified example deployment configuration uses the Rolling strategy. Triggers and some other minor details are omitted for brevity:

{
  "kind": "DeploymentConfig",
  "apiVersion": "v1",
  "metadata": {
    "name": "frontend"
  },
  "spec": {
    "template": {
      "metadata": {
        "labels": {
          "name": "frontend"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "helloworld",
            "image": "openshift/origin-ruby-sample"
          }
        ]
      }
    }
    "replicas": 5,
    "selector": {
      "name": "frontend"
    },
    "strategy": {
      "type": "Rolling",
      "rollingParams": {
        "pre": {
          "failurePolicy": "Abort",
          "execNewPod": {
            "containerName": "helloworld", (1)
            "command": [ (2)
              "/usr/bin/command", "arg1", "arg2"
            ],
            "env": [ (3)
              {
                "name": "CUSTOM_VAR1",
                "value": "custom_value1"
              }
            ]
          }
        }
      }
    }
  }
}
1 The helloworld name refers to spec.template.spec.containers[0].name.
2 This command overrides any ENTRYPOINT defined by the openshift/origin-ruby-sample image.
3 env is an optional set of environment variables for the hook container.

In this example, the "pre" hook will be executed in a new pod using the openshift/origin-ruby-sample image from the helloworld container. The hook container command will be /usr/bin/command arg1 arg2, and the hook container will have the CUSTOM_VAR1=custom_value1 environment variable. Because the hook failure policy is Abort, the deployment will fail if the hook fails.

Deployment Resources

A deployment is completed by a pod that consumes resources (memory and cpu) on a node. By default, pods consume unbounded node resources. However, if a project specifies default container limits, then pods consume resources up to those limits. Another way to limit resource use is to specify resource limits as part of the deployment strategy. In the following example, each of resources, cpu, and memory is optional.

{
  "type": "Recreate",
  "resources": {
    "limits": {
      "cpu": "100m", (1)
      "memory": "256Mi" (2)
    }
  },
}
1 cpu is in cpu units; 100m represents 0.1 cpu units (100 * 1e-3)
2 memory is in bytes; 256Mi represents 268435456 bytes (256 * 2 ^ 20)

Deployment resources can be used with the Recreate, Rolling, or Custom deployment strategies.

Manual Scaling

In addition to rollbacks, you can exercise fine-grained control over the number of replicas by using the oc scale command. For example, the following command sets the replicas in the deployment configuration frontend to 3.

$ oc scale dc frontend --replicas=3

The number of replicas eventually propagates to the desired and current state of the deployment configured by the deployment configuration frontend.