Universal Container Runtime (UCR)

Launching Mesos containers using the Universal Container Runtime

Provision a Mesos container using UCR

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.

Docker Registry Support

UCR uses Docker v2 registry API to fetch Docker images/layers. Both Docker manifest v2 schema1 and v2 schema2 are supported (v2 schema2 is supported starting from DC/OS 1.13.0).


Use this procedure to provision a container with the UCR from the DC/OS UI.

  1. Click the Services tab of the DC/OS UI, 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.


Use this procedure to provision a container with the UCR from the DC/OS command line.

  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 garbage collection (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 the MESOS_IMAGE_GC_CONFIG environment variable at /opt/mesosphere/etc/mesos-slave-common. The default config file is located at /opt/mesosphere/etc/mesos-slave-image-gc-config.json, and the following 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

Container 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