Universal Container Runtime (UCR)

Launching Mesos containers using the Universal Container Runtime

The Universal Container Runtime (UCR) launches Mesos containers from binary executables and extends the Mesos container runtime to support provisioning Docker images. The UCR has many advantages over the Docker Engine for running Docker images. Use the Docker Engine only if you need specific features of the Docker package.

Provision a container with the UCR from the DC/OS web interface

  1. Click the Services tab of the DC/OS web interface, then click RUN A SERVICE.

  2. Click Single Container.

  3. Enter the service ID.

  4. In the CONTAINER IMAGE field, optionally enter a container image. Otherwise, enter a command in the COMMAND field.

  5. Specify the UCR. Click MORE SETTINGS. In the Container Runtime section, choose the UNIVERSAL CONTAINER RUNTIME (UCR) radio button.

  6. Click REVIEW & RUN and RUN SERVICE.

Provision a container with the UCR from the DC/OS CLI

  1. In your Marathon application definition, set the container.type parameter to MESOS. Here, we specify a Docker container with the docker object. The UCR provides an optional pullConfig parameter to enable you to authenticate to a private Docker registry.
  "id": "/nginx-bridge",
  "container": {
    "portMappings": [
        "containerPort": 80,
        "hostPort": 0,
        "labels": {
          "VIP_0": "/nginx2:1024"
        "protocol": "tcp",
        "servicePort": 10000,
        "name": "webport"
    "type": "MESOS",
    "volumes": [],
    "docker": {
        "image": "nginx",
        "forcePullImage": false,
        "pullConfig": {
            "secret": "pullConfigSecret"
        "parameters": []
    "secrets": {
      "pullConfigSecret": {
        "source": "/mesos-docker/pullConfig"
  "cpus": 0.5,
  "disk": 0,
  "instances": 1,
  "mem": 128,
  "networks": [
    "mode": "container/bridge"
  "requirePorts": false

Important: If you leave the args field empty, the default entry point will be the launch command for the container. If your container does not have a default entry point, you must specify a command in the args field. If you do not, your service will fail to deploy.

Container Image Garbage Collection

For a long running cluster, container images may occupy disk spaces on the agent machines. To improve the operator’s experience with UCR, container image GC is introduced, starting from Mesos 1.5.0 (please read the Mesos docs for more details). The image GC is automatic by default in DC/OS while it can be triggered by the operator manually.

Automatic Image GC

Container Image Auto GC is enabled by default, configured by an image GC config file. This config file can be updated via MESOS_IMAGE_GC_CONFIG environment variable at /opt/mesosphere/etc/mesos-slave-common. The default config file locates at /opt/mesosphere/etc/mesos-slave-image-gc-config.json, and the followings are the parameters of the config file:

  • image_disk_headroom: The image disk headroom used to calculate the threshold of container image store size. Image garbage collection will be triggered automatically if the image disk usage reaches that threshold. Please note that the headroom value has to be between 0.0 and 1.0. (defaults to be 0.1, which represents 90% disk usage as the threshold)
  • image_disk_watch_interval: The periodic time interval to check the image store disk usage. Please note that the unit of this time interval is ‘nanosecond’. (defaults to be 300000000000, which represents the disk check every 5 minutes)
  • excluded_images: The excluded image list that should not be garbage collected. (defaults to be an empty list)

Manual Image GC

Comtainer Image Manual GC can be triggered via the HTTP Operator API. Please see PRUNE_IMAGES section in the v1 Operator API doc for more details.

Further Reading