Pod Examples

Understanding field definitions and examples of pods

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.

  1. {
  2.    "id":"/simple-pod",
  3.    "containers":[
  4.       {
  5.          "name":"simpletask1",
  6.          "exec":{
  7.             "command":{
  8.                "shell":"env && sleep 10000"
  9.             }
  10.          },
  11.          "resources":{
  12.             "cpus":0.1,
  13.             "mem":32
  14.          },
  15.          "image":{
  16.             "kind":"DOCKER",
  17.             "id":"python:3.5.2-alpine"
  18.          }
  19.       }
  20.    ],
  21.    "networks":[
  22.       {
  23.          "mode":"host"
  24.       }
  25.    ]
  26. }

Basic pod fields

FieldTypeValue
id (required)stringUnique ID for the pod.
containers (required)arraySee Basic pod container fields.
volumesarrayAll volumes associated with the pod.
volumes.namestringName of shared volume.
volumes.hoststringAbsolute path of the file or directory on the agent, or else the relative path of the directory in the executor’s sandbox. Useful for mapping directories that exist on the agent or within the executor sandbox.
networksarrayAccepts the following parameters: mode, name, and labels.
networks.modestringNetwork mode: host or container. host uses the network namespace of the host. container uses virtual networking, and a virtual network name must be specified.
networks:namestringRequired for container network mode.
networks.labelsobjectKey/value pairs (i.e., for passing metadata to Mesos modules).
scalingarrayAccepts the following parameters: kind, instances, and maxInstances.
scaling.kindstringType of scaling. Only fixed is currently supported.
scaling.instancesintegerInitial number of pod instances (default: 1).
scaling.maxInstancesintegerMaximum number of instances of this pod.

Basic pod container fields

FieldTypeValue
containers (required)arrayContainer definitions for all containers that belong to a pod.
containers.namestringUnique name for the container.
containers.execobjectAccepts the command parameter.
containers.exec.commandobjectCommand executed by Mesos.
containers.exec.command.shellstringCommand to execute. If using container entrypoint, use an empty string.
containers.exec.overrideEntrypointbooleanIf command is supplied, this is implicitly set to true. To use the default entrypoint, set to false.
containers:resources (required)objectContainer specifications for resources.
containers.resources.cpusnumberCPU shares (default: 1.0).
containers.resources.memnumberMemory resources in MiB (default: 128).
containers.resources.diskdoubleDisk resources in MiB (default: 128).
containers.resources.gpusintegerGPU resources (default: 0).
containers:resourceLimits (required)objectContainer specifications for CPU and memory limits.
containers.resourceLimits.cpusnumber or stringCPU resource limit (default: value of resources.cpus), can specify as “unlimited”.
containers.resourceLimits.memnumber or stringMemory resources in MiB (default: value of resources.mem), can specify as “unlimited”.
containers.imageobjectIf image is omitted, the Mesos containerizer is used.
containers.image.kindstringContainer image format (DOCKER or APPC).
containers.image.idstringContainer image tag.
containers.image.forcePullbooleanSet to true to always pull image (default: false).
containers.volumeMountsarrayAccepts the following parameters: name and mountPath.
containers.volumeMounts.namestringName of the shared volume (must be a valid volume defined at the pod layer).
containers.volumeMounts.mountPathstringContainer path to mount volume.
containers.endpointsarrayArray of objects.
containers.endpoints.namestringUnique name of port.
containers.endpoints.containerPortnumberThe container point the container task is listening on. Required if network mode is container.
containers.endpoints.hostPortnumberMapped port on host. If set to 0, Marathon dynamically allocates the port.
containers.endpoints.protocolarrayProtocol of port (tcp or http).
containers.endpoints.labelsobjectMetadata as key/value pairs.

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.

  1. {
  2.    "id":"/test-pod",
  3.    "labels":{
  4.       "pod_label":"pod"
  5.    },
  6.    "environment":{
  7.       "POD_ENV":"pod"
  8.    },
  9.    "containers":[
  10.       {
  11.          "name":"healthtask1",
  12.          "exec":{
  13.             "command":{
  14.                "shell":"./read-write-server.py 8080 mount1/test-file.txt"
  15.             }
  16.          },
  17.          "resources":{
  18.             "cpus":0.1,
  19.             "mem":32,
  20.             "disk":32,
  21.             "gpus":0
  22.          },
  23.          "resourceLimits":{
  24.             "cpus": "unlimited",
  25.             "mem": 1024
  26.          },
  27.          "endpoints":[
  28.             {
  29.                "name":"httpendpoint",
  30.                "containerPort":8080,
  31.                "hostPort":0,
  32.                "protocol":[
  33.                   "tcp"
  34.                ],
  35.                "labels":{
  36.                   "ep1_label":"ep1"
  37.                }
  38.             }
  39.          ],
  40.          "image":{
  41.             "kind":"DOCKER",
  42.             "id":"python:3.5.2-alpine"
  43.          },
  44.          "environment":{
  45.             "C1_ENV":"c1"
  46.          },
  47.          "healthCheck":{
  48.             "http":{
  49.                "endpoint":"httpendpoint",
  50.                "path":"/ping",
  51.                "scheme":"HTTP"
  52.             },
  53.             "gracePeriodSeconds":30,
  54.             "intervalSeconds":5,
  55.             "maxConsecutiveFailures":3,
  56.             "timeoutSeconds":3,
  57.             "delaySeconds":2
  58.          },
  59.          "volumeMounts":[
  60.             {
  61.                "name":"sharedvolume",
  62.                "mountPath":"mount1"
  63.             }
  64.          ],
  65.          "artifacts":[
  66.             {
  67.                "uri":"https://s3-us-west-2.amazonaws.com/mesos-soak-cluster/read-write-server.py",
  68.                "extract":false,
  69.                "executable":true,
  70.                "cache":true,
  71.                "destPath":"read-write-server.py"
  72.             }
  73.          ],
  74.          "labels":{
  75.             "c1_label":"c1"
  76.          }
  77.       },
  78.       {
  79.          "name":"healthtask2",
  80.          "exec":{
  81.             "command":{
  82.                "shell":"./read-write-server.py 8081 mount2/test-file.txt"
  83.             }
  84.          },
  85.          "resources":{
  86.             "cpus":0.1,
  87.             "mem":32,
  88.             "disk":32,
  89.             "gpus":0
  90.          },
  91.          "endpoints":[
  92.             {
  93.                "name":"httpendpoint2",
  94.                "containerPort":8081,
  95.                "hostPort":0,
  96.                "protocol":[
  97.                   "tcp"
  98.                ],
  99.                "labels":{
  100.                   "ep2_label":"ep2"
  101.                }
  102.             }
  103.          ],
  104.          "image":{
  105.             "kind":"DOCKER",
  106.             "id":"python:3.5.2-alpine"
  107.          },
  108.          "environment":{
  109.             "C2_ENV":"c2"
  110.          },
  111.          "healthCheck":{
  112.             "http":{
  113.                "endpoint":"httpendpoint2",
  114.                "path":"/ping",
  115.                "scheme":"HTTP"
  116.             },
  117.             "gracePeriodSeconds":30,
  118.             "intervalSeconds":5,
  119.             "maxConsecutiveFailures":3,
  120.             "timeoutSeconds":3,
  121.             "delaySeconds":2
  122.          },
  123.          "volumeMounts":[
  124.             {
  125.                "name":"sharedvolume",
  126.                "mountPath":"mount2"
  127.             }
  128.          ],
  129.          "artifacts":[
  130.             {
  131.                "uri":"https://s3-us-west-2.amazonaws.com/mesos-soak-cluster/read-write-server.py",
  132.                "extract":false,
  133.                "executable":true,
  134.                "cache":true,
  135.                "destPath":"read-write-server.py"
  136.             }
  137.          ],
  138.          "labels":{
  139.             "c2_label":"c2"
  140.          }
  141.       },
  142.       {
  143.          "name":"clienttask",
  144.          "exec":{
  145.             "command":{
  146.                "shell":"while true; do sleep 5 && curl -X GET localhost:8080/write && curl -X GET localhost:8081/read; done"
  147.             }
  148.          },
  149.          "resources":{
  150.             "cpus":0.1,
  151.             "mem":32,
  152.             "disk":32,
  153.             "gpus":0
  154.          },
  155.          "endpoints":[
  157.          ],
  158.          "environment":{
  159.             "C3_ENV":"c3"
  160.          },
  161.          "volumeMounts":[
  163.          ],
  164.          "artifacts":[
  166.          ],
  167.          "labels":{
  168.             "c3_label":"c3"
  169.          }
  170.       }
  171.    ],
  172.    "secrets":{
  174.    },
  175.    "volumes":[
  176.       {
  177.          "name":"sharedvolume"
  178.       }
  179.    ],
  180.    "networks":[
  181.       {
  182.          "name":"dcos",
  183.          "mode":"container",
  184.          "labels":{
  185.             "net_label":"net"
  186.          }
  187.       }
  188.    ],
  189.    "scaling":{
  190.       "kind":"fixed",
  191.       "instances":1,
  192.       "maxInstances":null
  193.    },
  194.    "scheduling":{
  195.       "backoff":{
  196.          "backoff":1,
  197.          "backoffFactor":1.15,
  198.          "maxLaunchDelaySeconds":300
  199.       },
  200.       "upgrade":{
  201.          "minimumHealthCapacity":1,
  202.          "maximumOverCapacity":1
  203.       },
  204.       "placement":{
  205.          "constraints":[
  207.          ],
  208.          "acceptedResourceRoles":[
  210.          ]
  211.       },
  212.       "killSelection":"YOUNGEST_FIRST",
  213.       "unreachableStrategy":{
  214.          "inactiveAfterSeconds":900,
  215.          "expungeAfterSeconds":604800
  216.       }
  217.    },
  218.    "executorResources":{
  219.       "cpus":0.1,
  220.       "mem":32,
  221.       "disk":10
  222.    }
  223. }

Additional pod fields

FieldTypeValue
labelsobjectPod metadata as key/value pairs.
environmentobjectEnvironment variables at the pod level. All pod containers will inherit these environment variables. Must be capitalized.
secretsobjectThe fully qualified path to the secret in the store.
schedulingobjectDefines exponential backoff behavior for faulty apps to prevent sandboxes from filling up.
scheduling.backoffnumberInitial backoff (seconds) applied when a launched instance fails (default: 1).
scheduling.backoffFactornumberFactor applied to current backoff to determine the new backoff (default: 1.15).
scheduling.maxLaunchDelaySecondsnumberMaximum backoff (seconds) applied when subsequent failures are detected (default: 300).
scheduling.unreachableStrategystring or objectDefine handling for unreachable instances.
scheduling.unreachableStrategy.inactiveAfterSecondsnumberLength of time an instance is unreachable after which it is marked as inactive.
scheduling.unreachableStrategy.expungeAfterSecondsnumberLength of time an instance is unreachable after which it is expunged.
scheduling.upgradeobjectUpgrade strategy that controls pod updates.
scheduling.upgrade.minimumHealthCapacitynumberNumber between 0 and 1 that represents the minimum number of healthy nodes to maintain during upgrade (default: 1).
scheduling.upgrade.maximumOverCapacitynumberNumber between 0 and 1 representing the maximum number of additional instances to launch during upgrade (default: 1).
placementobjectControls placement of pod tasks.
placement.constraintsstring[]Constraints control the placement policy of pod tasks. Options: UNIQUE, CLUSTER, GROUP_BY, LIKE, UNLIKE, MAX_PER.
placement.acceptedResourceRolesstring[]List of resource roles. The Marathon component will only consider resource offers with roles on this list for this pod’s tasks.
killSelectionstringDefines which instance is killed first when an app is in an over-provisioned state. Options: YOUNGEST_FIRST, OLDEST_FIRST.
unreachableStrategyBehavior when agents are partitioned from masters.
killSelection.inactiveAfterSecondsintegerTime in seconds to wait before replacing task (default: 900).
killSelection.expungeAfterSecondsintegerTime in seconds to wait for tasks to come back before expunging (default: 603800).
executorResourcesobjectResources reserved for the pod executor.
executorResources.cpusnumberCPU shares (default: 0.1).
executorResources.memnumberMemory resources in MiB (default: 32).
executorResources.disknumberDisk resources in MiB (default: 10.0),

Additional pod container fields

FieldTypeValue
labelsobjectContainer metadata as key/value pairs.
environmentobjectContainer environment variables. Can override pod environment variables. Must be capitalized.
healthCheckobjectAccepts the following parameters: http, tcp, and exec.
healthCheck.httpProtocol type. Options: http, tcp, exec.
healthCheck.http.endpointstringEndpoint name to use.
healthCheck.http.pathstringPath to the endpoint exposed by the task that provides health status.
healthCheck.http.schemestringFor httpHealthCheck, use http.
healthCheck.gracePeriodSecondsintegerInterval to ignore health check failures after a task is first started or until a task is first healthy (default: 300).
healthCheck.intervalSecondsintegerInterval between health checks (default: 60).
healthCheck.maxConsecutiveFailuresintegerNumber of consecutive failures before task is killed (default: 3).
healthCheck.timeoutSecondsintegerTime to wait until health check is complete (default: 20).
healthCheck.delaySecondsintegerTime to wait until starting health check (default: 2).
artifactsarrayArray of artifact objects
healthCheck.uristringsURI to resources to download (i.e., .tgz, tar.gz, .zip, .txz, etc).
healthCheck.extractbooleanExtract fetched artifact.
healthCheck.executablebooleanSet fetched artifact as executable.
healthCheck.cachebooleanCache fetched artifact.
healthCheck.destPathstringsDestination path of artifact.

A pod with multiple containers

The following pod definition specifies a pod with 3 containers.

  1. {
  2.    "id":"/pod-with-multiple-containers",
  3.    "version":"2017-01-03T18:21:19.31Z",
  4.    "containers":[
  5.       {
  6.          "name":"sleep1",
  7.          "exec":{
  8.             "command":{
  9.                "shell":"sleep 1000"
  10.             }
  11.          },
  12.          "resources":{
  13.             "cpus":0.01,
  14.             "mem":32,
  15.             "disk":0,
  16.             "gpus":0
  17.          }
  18.       },
  19.       {
  20.          "name":"sleep2",
  21.          "exec":{
  22.             "command":{
  23.                "shell":"sleep 1000"
  24.             }
  25.          },
  26.          "resources":{
  27.             "cpus":0.01,
  28.             "mem":32,
  29.             "disk":0,
  30.             "gpus":0
  31.          }
  32.       },
  33.       {
  34.          "name":"sleep3",
  35.          "exec":{
  36.             "command":{
  37.                "shell":"sleep 1000"
  38.             }
  39.          },
  40.          "resources":{
  41.             "cpus":0.01,
  42.             "mem":32,
  43.             "disk":0,
  44.             "gpus":0
  45.          }
  46.       }
  47.    ],
  48.    "networks":[
  49.       {
  50.          "mode":"host"
  51.       }
  52.    ],
  53.    "scaling":{
  54.       "kind":"fixed",
  55.       "instances":10,
  56.       "maxInstances":null
  57.    },
  58.    "scheduling":{
  59.       "backoff":{
  60.          "backoff":1,
  61.          "backoffFactor":1.15,
  62.          "maxLaunchDelaySeconds":300
  63.       },
  64.       "upgrade":{
  65.          "minimumHealthCapacity":1,
  66.          "maximumOverCapacity":1
  67.       },
  68.       "killSelection":"Youngest_First",
  69.       "unreachableStrategy":{
  70.          "inactiveAfterSeconds":900,
  71.          "expungeAfterSeconds":604800
  72.       }
  73.    },
  74.    "executorResources":{
  75.       "cpus":0.1,
  76.       "mem":32,
  77.       "disk":10
  78.    }
  79. }

A Pod that Uses Ephemeral Volumes

The following pod definition specifies an ephemeral volume called v1.

  1. {
  2.   "id": "/with-ephemeral-vol",
  3.   "version": "2017-01-03T17:36:39.389Z",
  4.   "containers": [
  5.     {
  6.       "name": "ct1",
  7.       "exec": {
  8.         "command": {
  9.           "shell": "while true; do echo the current time is $(date) > ./jdef-v1/clock; sleep 1; done"
  10.         }
  11.       },
  12.       "resources": {
  13.         "cpus": 0.1,
  14.         "mem": 32,
  15.         "disk": 0,
  16.         "gpus": 0
  17.       },
  18.       "volumeMounts": [
  19.         {
  20.           "name": "v1",
  21.           "mountPath": "jdef-v1"
  22.         }
  23.       ]
  24.     },
  25.     {
  26.       "name": "ct2",
  27.       "exec": {
  28.         "command": {
  29.           "shell": "while true; do cat ./etc/clock; sleep 1; done"
  30.         }
  31.       },
  32.       "resources": {
  33.         "cpus": 0.1,
  34.         "mem": 32,
  35.         "disk": 0,
  36.         "gpus": 0
  37.       },
  38.       "volumeMounts": [
  39.         {
  40.           "name": "v1",
  41.           "mountPath": "etc"
  42.         }
  43.       ]
  44.     }
  45.   ],
  46.   "volumes": [
  47.     {
  48.       "name": "v1"
  49.     }
  50.   ],
  51.   "networks": [
  52.     {
  53.       "mode": "host"
  54.     }
  55.   ],
  56.   "scaling": {
  57.     "kind": "fixed",
  58.     "instances": 1,
  59.     "maxInstances": null
  60.   },
  61.   "scheduling": {
  62.     "backoff": {
  63.       "backoff": 1,
  64.       "backoffFactor": 1.15,
  65.       "maxLaunchDelaySeconds": 300
  66.     },
  67.     "upgrade": {
  68.       "minimumHealthCapacity": 1,
  69.       "maximumOverCapacity": 1
  70.     },
  71.     "killSelection": "Youngest_First",
  72.     "unreachableStrategy": {
  73.       "inactiveAfterSeconds": 900,
  74.       "expungeAfterSeconds": 604800
  75.     }
  76.   },
  77.   "executorResources": {
  78.     "cpus": 0.1,
  79.     "mem": 32,
  80.     "disk": 10
  81.   }
  82. }

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.

  1. {
  2.    "id":"/pod-with-virtual-network",
  3.    "scaling":{
  4.       "kind":"fixed",
  5.       "instances":1
  6.    },
  7.    "containers":[
  8.       {
  9.          "name":"sleep1",
  10.          "exec":{
  11.             "command":{
  12.                "shell":"sleep 1000"
  13.             }
  14.          },
  15.          "resources":{
  16.             "cpus":0.1,
  17.             "mem":32
  18.          }
  19.       }
  20.    ],
  21.    "networks":[
  22.       {
  23.          "mode":"container",
  24.          "name":"dcos"
  25.       }
  26.    ]
  27. }

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

  1. {
  2.    "id":"/pod-with-endpoint",
  3.    "containers":[
  4.       {
  5.          "name":"simple-docker",
  6.          "resources":{
  7.             "cpus":1,
  8.             "mem":128,
  9.             "disk":0,
  10.             "gpus":0
  11.          },
  12.          "image":{
  13.             "kind":"DOCKER",
  14.             "id":"nginx"
  15.          },
  16.          "endpoints":[
  17.             {
  18.                "name":"web",
  19.                "containerPort":80,
  20.                "protocol":[
  21.                   "http"
  22.                ]
  23.             }
  24.          ]
  25.       }
  26.    ],
  27.    "networks":[
  28.       {
  29.          "mode":"container"
  30.       }
  31.    ]
  32. }

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.

  1. {
  2.    "id":"/pod-with-healthcheck",
  3.    "containers":[
  4.       {
  5.          "name":"simple-docker",
  6.          "resources":{
  7.             "cpus":1,
  8.             "mem":128,
  9.             "disk":0,
  10.             "gpus":0
  11.          },
  12.          "image":{
  13.             "kind":"DOCKER",
  14.             "id":"nginx"
  15.          },
  16.          "endpoints":[
  17.             {
  18.                "name":"web",
  19.                "containerPort":80,
  20.                "protocol":[
  21.                   "http"
  22.                ]
  23.             }
  24.          ],
  25.          "healthCheck":{
  26.             "http":{
  27.                "endpoint":"web",
  28.                "path":"/"
  29.             }
  30.          }
  31.       }
  32.    ],
  33.    "networks":[
  34.       {
  35.          "mode":"container"
  36.       }
  37.    ]
  38. }

Complete Pod

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

  1. {
  2.   "id": "/complete-pod",
  3.   "labels": {
  4.     "owner": "zeus",
  5.     "note": "Away from olympus"
  6.   },
  7.   "environment": {
  8.     "XPS1": "Test"
  9.   },
  10.   "volumes": [
  11.     {
  12.       "name": "etc",
  13.       "host": "/etc"
  14.     }
  15.   ],
  16.   "networks": [
  17.     {
  18.      "mode": "container",
  19.      "name": "dcos"
  20.     }
  21.   ],
  22.   "scaling": {
  23.     "kind": "fixed",
  24.     "instances": 1
  25.   },
  26.   "scheduling": {
  27.     "backoff": {
  28.       "backoff": 1,
  29.       "backoffFactor": 1.15,
  30.       "maxLaunchDelaySeconds": 300
  31.     },
  32.     "upgrade": {
  33.       "minimumHealthCapacity": 1,
  34.       "maximumOverCapacity": 1
  35.     },
  36.     "placement": {
  37.       "constraints": [],
  38.       "acceptedResourceRoles": []
  39.     }
  40.   },
  41.   "containers": [
  42.     {
  43.       "name": "container1",
  44.       "resources": {
  45.         "cpus": 1,
  46.         "mem": 128,
  47.         "disk": 0,
  48.         "gpus": 0
  49.       },
  50.       "resourceLimits": {
  51.         "cpus": "unlimited",
  52.         "mem": 1024
  53.       },
  54.       "endpoints": [
  55.         {
  56.           "name": "http-endpoint",
  57.           "containerPort": 80,
  58.           "hostPort": 0,
  59.           "protocol": [ "HTTP" ],
  60.           "labels": {}
  61.         }
  62.       ],
  63.       "image": {
  64.         "id": "nginx:latest",
  65.         "kind": "DOCKER",
  66.         "forcePull": false
  67.       },
  68.       "environment": {
  69.         "XPS1": "Test"
  70.       },
  71.       "user": "root",
  72.       "healthCheck": {
  73.         "gracePeriodSeconds": 30,
  74.         "intervalSeconds": 5,
  75.         "maxConsecutiveFailures": 3,
  76.         "timeoutSeconds": 4,
  77.         "delaySeconds": 2,
  78.         "http": {
  79.           "path": "/",
  80.           "scheme": "HTTP",
  81.           "endpoint": "http-endpoint"
  82.         }
  83.       },
  84.       "volumeMounts": [
  85.         {
  86.           "name": "etc",
  87.           "mountPath": "/mnt/etc",
  88.           "readOnly": true
  89.         }
  90.       ],
  91.       "artifacts": [
  92.         {
  93.           "uri": "https://ftp.gnu.org/gnu/glibc/glibc-2.25.tar.gz",
  94.           "executable": false,
  95.           "extract": true,
  96.           "cache": true,
  97.           "destPath": "glibc-2.25.tar.gz"
  98.         }
  99.       ],
  100.       "labels": {
  101.         "owner": "zeus",
  102.         "note": "Away from olympus"
  103.       },
  104.       "lifecycle": {
  105.         "killGracePeriodSeconds": 60
  106.       }
  107.     }
  108.   ]
  109. }