This topic provides field definitions and usage examples for pods. For more details on field definitions, see Marathon Configuration Reference.

Annotated simple pod definition

This pod, named simple-pod has a single container, simpletask1. The container pulls down an image (python:3.5.2-alpine) and runs a command.

{
   "id":"/simple-pod",
   "containers":[
      {
         "name":"simpletask1",
         "exec":{
            "command":{
               "shell":"env && sleep 10000"
            }
         },
         "resources":{
            "cpus":0.1,
            "mem":32
         },
         "image":{
            "kind":"DOCKER",
            "id":"python:3.5.2-alpine"
         }
      }
   ],
   "networks":[
      {
         "mode":"host"
      }
   ]
}

Basic pod fields

Basic pod container fields

Annotated multi-pod with all parameters

The example below shows a pod, test-pod, with three containers, healthtask1, healthtask2, and clienttask. The pod makes uses shared volumes and the native DC/OS virtual networking solution.

{
   "id":"/test-pod",
   "labels":{
      "pod_label":"pod"
   },
   "environment":{
      "POD_ENV":"pod"
   },
   "containers":[
      {
         "name":"healthtask1",
         "exec":{
            "command":{
               "shell":"./read-write-server.py 8080 mount1/test-file.txt"
            }
         },
         "resources":{
            "cpus":0.1,
            "mem":32,
            "disk":32,
            "gpus":0
         },
         "endpoints":[
            {
               "name":"httpendpoint",
               "containerPort":8080,
               "hostPort":0,
               "protocol":[
                  "tcp"
               ],
               "labels":{
                  "ep1_label":"ep1"
               }
            }
         ],
         "image":{
            "kind":"DOCKER",
            "id":"python:3.5.2-alpine"
         },
         "environment":{
            "C1_ENV":"c1"
         },
         "healthCheck":{
            "http":{
               "endpoint":"httpendpoint",
               "path":"/ping",
               "scheme":"HTTP"
            },
            "gracePeriodSeconds":30,
            "intervalSeconds":5,
            "maxConsecutiveFailures":3,
            "timeoutSeconds":3,
            "delaySeconds":2
         },
         "volumeMounts":[
            {
               "name":"sharedvolume",
               "mountPath":"mount1"
            }
         ],
         "artifacts":[
            {
               "uri":"https://s3-us-west-2.amazonaws.com/mesos-soak-cluster/read-write-server.py",
               "extract":false,
               "executable":true,
               "cache":true,
               "destPath":"read-write-server.py"
            }
         ],
         "labels":{
            "c1_label":"c1"
         }
      },
      {
         "name":"healthtask2",
         "exec":{
            "command":{
               "shell":"./read-write-server.py 8081 mount2/test-file.txt"
            }
         },
         "resources":{
            "cpus":0.1,
            "mem":32,
            "disk":32,
            "gpus":0
         },
         "endpoints":[
            {
               "name":"httpendpoint2",
               "containerPort":8081,
               "hostPort":0,
               "protocol":[
                  "tcp"
               ],
               "labels":{
                  "ep2_label":"ep2"
               }
            }
         ],
         "image":{
            "kind":"DOCKER",
            "id":"python:3.5.2-alpine"
         },
         "environment":{
            "C2_ENV":"c2"
         },
         "healthCheck":{
            "http":{
               "endpoint":"httpendpoint2",
               "path":"/ping",
               "scheme":"HTTP"
            },
            "gracePeriodSeconds":30,
            "intervalSeconds":5,
            "maxConsecutiveFailures":3,
            "timeoutSeconds":3,
            "delaySeconds":2
         },
         "volumeMounts":[
            {
               "name":"sharedvolume",
               "mountPath":"mount2"
            }
         ],
         "artifacts":[
            {
               "uri":"https://s3-us-west-2.amazonaws.com/mesos-soak-cluster/read-write-server.py",
               "extract":false,
               "executable":true,
               "cache":true,
               "destPath":"read-write-server.py"
            }
         ],
         "labels":{
            "c2_label":"c2"
         }
      },
      {
         "name":"clienttask",
         "exec":{
            "command":{
               "shell":"while true; do sleep 5 && curl -X GET localhost:8080/write && curl -X GET localhost:8081/read; done"
            }
         },
         "resources":{
            "cpus":0.1,
            "mem":32,
            "disk":32,
            "gpus":0
         },
         "endpoints":[

         ],
         "environment":{
            "C3_ENV":"c3"
         },
         "volumeMounts":[

         ],
         "artifacts":[

         ],
         "labels":{
            "c3_label":"c3"
         }
      }
   ],
   "secrets":{

   },
   "volumes":[
      {
         "name":"sharedvolume"
      }
   ],
   "networks":[
      {
         "name":"dcos",
         "mode":"container",
         "labels":{
            "net_label":"net"
         }
      }
   ],
   "scaling":{
      "kind":"fixed",
      "instances":1,
      "maxInstances":null
   },
   "scheduling":{
      "backoff":{
         "backoff":1,
         "backoffFactor":1.15,
         "maxLaunchDelaySeconds":300
      },
      "upgrade":{
         "minimumHealthCapacity":1,
         "maximumOverCapacity":1
      },
      "placement":{
         "constraints":[

         ],
         "acceptedResourceRoles":[

         ]
      },
      "killSelection":"YOUNGEST_FIRST",
      "unreachableStrategy":{
         "inactiveAfterSeconds":900,
         "expungeAfterSeconds":604800
      }
   },
   "executorResources":{
      "cpus":0.1,
      "mem":32,
      "disk":10
   }
}

Additional pod fields

Additional pod container fields

A pod with multiple containers

The following pod definition specifies a pod with 3 containers.

{
   "id":"/pod-with-multiple-containers",
   "version":"2017-01-03T18:21:19.31Z",
   "containers":[
      {
         "name":"sleep1",
         "exec":{
            "command":{
               "shell":"sleep 1000"
            }
         },
         "resources":{
            "cpus":0.01,
            "mem":32,
            "disk":0,
            "gpus":0
         }
      },
      {
         "name":"sleep2",
         "exec":{
            "command":{
               "shell":"sleep 1000"
            }
         },
         "resources":{
            "cpus":0.01,
            "mem":32,
            "disk":0,
            "gpus":0
         }
      },
      {
         "name":"sleep3",
         "exec":{
            "command":{
               "shell":"sleep 1000"
            }
         },
         "resources":{
            "cpus":0.01,
            "mem":32,
            "disk":0,
            "gpus":0
         }
      }
   ],
   "networks":[
      {
         "mode":"host"
      }
   ],
   "scaling":{
      "kind":"fixed",
      "instances":10,
      "maxInstances":null
   },
   "scheduling":{
      "backoff":{
         "backoff":1,
         "backoffFactor":1.15,
         "maxLaunchDelaySeconds":300
      },
      "upgrade":{
         "minimumHealthCapacity":1,
         "maximumOverCapacity":1
      },
      "killSelection":"Youngest_First",
      "unreachableStrategy":{
         "inactiveAfterSeconds":900,
         "expungeAfterSeconds":604800
      }
   },
   "executorResources":{
      "cpus":0.1,
      "mem":32,
      "disk":10
   }
}

A Pod that Uses Ephemeral Volumes

The following pod definition specifies an ephemeral volume called v1.

{
  "id": "/with-ephemeral-vol",
  "version": "2017-01-03T17:36:39.389Z",
  "containers": [
    {
      "name": "ct1",
      "exec": {
        "command": {
          "shell": "while true; do echo the current time is $(date) > ./jdef-v1/clock; sleep 1; done"
        }
      },
      "resources": {
        "cpus": 0.1,
        "mem": 32,
        "disk": 0,
        "gpus": 0
      },
      "volumeMounts": [
        {
          "name": "v1",
          "mountPath": "jdef-v1"
        }
      ]
    },
    {
      "name": "ct2",
      "exec": {
        "command": {
          "shell": "while true; do cat ./etc/clock; sleep 1; done"
        }
      },
      "resources": {
        "cpus": 0.1,
        "mem": 32,
        "disk": 0,
        "gpus": 0
      },
      "volumeMounts": [
        {
          "name": "v1",
          "mountPath": "etc"
        }
      ]
    }
  ],
  "volumes": [
    {
      "name": "v1"
    }
  ],
  "networks": [
    {
      "mode": "host"
    }
  ],
  "scaling": {
    "kind": "fixed",
    "instances": 1,
    "maxInstances": null
  },
  "scheduling": {
    "backoff": {
      "backoff": 1,
      "backoffFactor": 1.15,
      "maxLaunchDelaySeconds": 300
    },
    "upgrade": {
      "minimumHealthCapacity": 1,
      "maximumOverCapacity": 1
    },
    "killSelection": "Youngest_First",
    "unreachableStrategy": {
      "inactiveAfterSeconds": 900,
      "expungeAfterSeconds": 604800
    }
  },
  "executorResources": {
    "cpus": 0.1,
    "mem": 32,
    "disk": 10
  }
}

A Pod that Uses Persistent Volumes

For an example of a pod that uses a persistent volume, see Create a pod with a local persistent volume.

IP-per-Pod Networking

The following pod definition specifies a virtual (user) network named dcos. The networks:mode:container field creates the virtual network. The name field is optional. If you have installed DC/OS using our AWS templates, the default virtual network name is dcos.

{
   "id":"/pod-with-virtual-network",
   "scaling":{
      "kind":"fixed",
      "instances":1
   },
   "containers":[
      {
         "name":"sleep1",
         "exec":{
            "command":{
               "shell":"sleep 1000"
            }
         },
         "resources":{
            "cpus":0.1,
            "mem":32
         }
      }
   ],
   "networks":[
      {
         "mode":"container",
         "name":"dcos"
      }
   ]
}

This pod declares a “web” endpoint that listens on port 80.

{
   "id":"/pod-with-endpoint",
   "containers":[
      {
         "name":"simple-docker",
         "resources":{
            "cpus":1,
            "mem":128,
            "disk":0,
            "gpus":0
         },
         "image":{
            "kind":"DOCKER",
            "id":"nginx"
         },
         "endpoints":[
            {
               "name":"web",
               "containerPort":80,
               "protocol":[
                  "http"
               ]
            }
         ]
      }
   ],
   "networks":[
      {
         "mode":"container"
      }
   ]
}

This pod adds a healthcheck that references the web endpoint. Mesos will execute an HTTP request against <container_ip>:80. The health check will pass if Mesos receives an HTTP 200 response.

{
   "id":"/pod-with-healthcheck",
   "containers":[
      {
         "name":"simple-docker",
         "resources":{
            "cpus":1,
            "mem":128,
            "disk":0,
            "gpus":0
         },
         "image":{
            "kind":"DOCKER",
            "id":"nginx"
         },
         "endpoints":[
            {
               "name":"web",
               "containerPort":80,
               "protocol":[
                  "http"
               ]
            }
         ],
         "healthCheck":{
            "http":{
               "endpoint":"web",
               "path":"/"
            }
         }
      }
   ],
   "networks":[
      {
         "mode":"container"
      }
   ]
}

Complete Pod

The following pod definition can serve as a reference to create more complicated pods.

{
  "id": "/complete-pod",
  "labels": {
    "owner": "zeus",
    "note": "Away from olympus"
  },
  "environment": {
    "XPS1": "Test"
  },
  "volumes": [
    {
      "name": "etc",
      "host": "/etc"
    }
  ],
  "networks": [
    {
     "mode": "container",
     "name": "dcos"
    }
  ],
  "scaling": {
    "kind": "fixed",
    "instances": 1
  },
  "scheduling": {
    "backoff": {
      "backoff": 1,
      "backoffFactor": 1.15,
      "maxLaunchDelaySeconds": 300
    },
    "upgrade": {
      "minimumHealthCapacity": 1,
      "maximumOverCapacity": 1
    },
    "placement": {
      "constraints": [],
      "acceptedResourceRoles": []
    }
  },
  "containers": [
    {
      "name": "container1",
      "resources": {
        "cpus": 1,
        "mem": 128,
        "disk": 0,
        "gpus": 0
      },
      "endpoints": [
        {
          "name": "http-endpoint",
          "containerPort": 80,
          "hostPort": 0,
          "protocol": [ "HTTP" ],
          "labels": {}
        }
      ],
      "image": {
        "id": "nginx:latest",
        "kind": "DOCKER",
        "forcePull": false
      },
      "environment": {
        "XPS1": "Test"
      },
      "user": "root",
      "healthCheck": {
        "gracePeriodSeconds": 30,
        "intervalSeconds": 5,
        "maxConsecutiveFailures": 3,
        "timeoutSeconds": 4,
        "delaySeconds": 2,
        "http": {
          "path": "/",
          "scheme": "HTTP",
          "endpoint": "http-endpoint"
        }
      },
      "volumeMounts": [
        {
          "name": "etc",
          "mountPath": "/mnt/etc",
          "readOnly": true
        }
      ],
      "artifacts": [
        {
          "uri": "https://ftp.gnu.org/gnu/glibc/glibc-2.25.tar.gz",
          "executable": false,
          "extract": true,
          "cache": true,
          "destPath": "glibc-2.25.tar.gz"
        }
      ],
      "labels": {
        "owner": "zeus",
        "note": "Away from olympus"
      },
      "lifecycle": {
        "killGracePeriodSeconds": 60
      }
    }
  ]
}