Pods

As of version 1.4, Marathon supports the creation and management of pods. Pods enable you to share storage, networking, and other resources among a group of applications on a single agent, address them as one group rather than as separate applications, and manage health as a unit.

Pods allow quick, convenient coordination between applications that need to work together, for instance a primary service and a related analytics service or log scraper. Pods are particularly useful for transitioning legacy applications to a microservices-based architecture.

Currently, Marathon pods can only be created and administered via the /v2/pods/ endpoint of the REST API, not via the web interface.

Note: Pods are only available as of Marathon 1.4 and are not supported in the strict security mode of Enterprise DC/OS 1.9 and below.

Features

  • Co-located containers.
  • Pod-level resource isolation.
  • Pod-level sandbox and ephemeral volumes.
  • Pod-level health checks.

Quick Start

  1. Run the following REST call, substituting your IP and port for <ip> and <port>:

     curl -X POST -H "Content-type: application/json" -d@- http://<ip>:<port>/v2/pods <<EOF
     {
        "id": "/simplepod",
        "scaling": { "kind": "fixed", "instances": 1 },
        "containers": [
          {
            "name": "sleep1",
            "exec": { "command": { "shell": "sleep 1000" } },
            "resources": { "cpus": 0.1, "mem": 32 }
          }
        ],
        "networks": [ {"mode": "host"} ]
     }
     EOF
    

    Note: The pod ID (the id parameter in the pod specification above) is used for all interaction with the pod once it is created.

  2. Verify the status of your new pod:

     curl -X GET http://<ip>:<port>/v2/pods/simplepod::status
    
  3. Delete your pod:

     curl -X DELETE http://<ip>:<port>/v2/pods/simplepod
    

Technical Overview

A pod is a special kind of Mesos task group, and the tasks or containers in the pod are the group members.* A pod instance’s containers are launched together, atomically, via the Mesos LAUNCH_GROUP call. Containers in pods share networking namespace and ephemeral volumes.

You configure a pod via a pod definition, which is similar to a Marathon application definition. There are some differences between pod and application definitions, however. For instance, you will need to specify an endpoint (not a port number) in order for other applications to communicate with your pod, pods have a separate REST API. This document outlines how to configure and manage pods.

Important Pods support only Mesos-level health checks.

* Pods cannot be modified by the /v2/groups/ endpoint, however. Pods are modified via the /v2/pods/ endpoint.

Networking

Marathon pods only support the Mesos containerizer. The Mesos containerizer supports multiple image formats, including Docker.

The Mesos containerizer simplifies networking by allowing the containers of each pod instance to share a network namespace and communicate over a VLAN or private network. If you specify a container network without a name in a pod definition, it will be assigned to the default network.

If you need other applications to communicate with your pod, specify an endpoint in your pod definition. Other applications will communicate with your pod by addressing those endpoints. See the Examples section for more information.

In your pod definition, you can declare a host or container network type. Pods created with host type share the network namespace of the host. Pods created with container type use virtual networking. If you specify the container network type and Marathon was not configured to have a default network name, you must also declare a virtual network name in the name field. See the Examples section for the full JSON.

Service name length limitations

According to RFC 1035 DNS labels are limited to 63 characters. Mesos-DNS will append a random 9-character long string to your service name. This means that your service name length must be less than or equal to 54 characters in order to have SRV records generated correctly.

To check that your SRV records were successfully generated, you can use dig command, for example:

dig _nginx-12345._tcp.marathon.mesos SRV

Correct output will look like this:

;; QUESTION SECTION:
;_nginx-12345._tcp.marathon.mesos. IN SRV

;; ANSWER SECTION:
_nginx-12345._tcp.marathon.mesos. 60 IN SRV 0 0 80 nginx-12345-eq1m3-s1.marathon.mesos.
_nginx-12345._tcp.marathon.mesos. 60 IN SRV 0 0 80 nginx-12345-9umtc-s1.marathon.mesos.
_nginx-12345._tcp.marathon.mesos. 60 IN SRV 0 0 80 nginx-12345-4c3em-s1.marathon.mesos.

;; ADDITIONAL SECTION:
nginx-12345-9umtc-s1.marathon.mesos. 60 IN A 10.0.6.43
nginx-12345-4c3em-s1.marathon.mesos. 60 IN A 10.0.6.43
nginx-12345-eq1m3-s1.marathon.mesos. 60 IN A 10.0.6.43

Ephemeral Storage

Containers within a pod share ephemeral storage. Volumes are declared at the pod-level and referenced by name when mounting them into specific containers.

Pod Events and State

When you update a pod that has already launched, the new version of the pod will only be available when redeployment is complete. If you query the system to learn which version is deployed before redeployment is complete, you may get the previous version as a response. The same is true for the status of a pod: if you update a pod, the change in status will not be reflected in a query until redeployment is complete.

History is permanently tied to pod_id. If you delete a pod and then reuse the ID, even if the details of the pod are different, the new pod will have the previous history (such as version information).

Pod Definitions

Pods are configured via a JSON pod definition, which is similar to an application definition. You must declare the resources required by each container in the pod because Mesos, not Marathon, determines how and when to perform isolation for all resources requested by a pod. See the Examples section for complete pod definitions.

Executor Resources

The executor runs on each node to manage the pods. By default, the executor reserves 32 MB and .1 CPUs per pod for overhead. Take this overhead into account when declaring resource needs for the containers in your pod. You can modify the executor resources in the executorResources field of your pod definition.

{
    "executorResources": {
        "cpus": 0.1,
        "mem": 64,
        "disk": 10mb
    }
}

Secrets

Specify a secret in the secrets field of your pod definition. The argument should be the fully qualified path to the secret in the store.

{
    "secrets": {
        "someSecretName": { "source": "/fully/qualified/path" }
    }
}

If you are not using Marathon on DC/OS, you will also need to enable the secrets feature via Marathon command-line flags and have a secrets plugin implementation.

Volumes

Pods support ephemeral volumes, which are defined at the pod level. Your pod definition must include a volumes field that specifies at least the name of the volume and a volumeMounts field that specifies at least the name and mount path of the volume.

{
    "volumes": [
        {
            "name": "etc"
        }
    ]
}
{
    "volumeMounts": [
        {
            "name": "env",
            "mountPath": "/mnt/etc"
        }
    ]
}

Pods also support host volumes. A pod volume parameter can declare a host field that references a pre-existing file or directory on the agent.

{
    "volumes": [
        {
            "name": "local",
            "host": "/user/local"
        }
    ]
}

Note: Data does not persist if pods are restarted.

Containerizers

Marathon pods support the Mesos containerizer. The Mesos containerizer supports multiple images, such as Docker. Learn more about running Docker containers on Marathon.

The following JSON specifies a Docker image for the pod:

{
   "image":{
      "id":"mesosphere/marathon:latest",
      "kind":"DOCKER",
      "forcePull":false
   }
}

An optional image.pullConfig is supported too. Here is an example of a pod pulling a Docker image from a private registry:

{
    "id": "/simple-pod",
    "scaling": {
        "kind": "fixed",
        "instances": 1
    },
    "containers": [{
        "name": "container0",
        "exec": {
            "command": {
                "shell": "sleep 1000"
            }
        },
        "image": {
            "kind": "DOCKER",
            "id": "company/private-image",
            "pullConfig": {
                "secret": "configSecret"
            }
        },
        "resources": {
            "cpus": 1,
            "mem": 50.0
        }
    }],
    "secrets": {
        "configSecret": {
            "source": "/config"
        }
    }
}

For further details, please refer to Configuration of Docker images with Mesos containerizer.

Create and Manage Pods

Use the /v2/pods/ endpoint to create and manage your pods. See the full API spec.

Create

curl -X POST -H "Content-type: application/json" -d@<mypod>.json http://<ip>:<port>/v2/pods

Sample response:

{
    "containers": [
        {
            "artifacts": [],
            "endpoints": [],
            "environment": {},
            "exec": {
                "command": {
                    "shell": "sleep 1000"
                }
            },
            "healthCheck": null,
            "image": null,
            "labels": {},
            "lifecycle": null,
            "name": "sleep1",
            "resources": {
                "cpus": 0.1,
                "disk": 0,
                "gpus": 0,
                "mem": 32
            },
            "user": null,
            "volumeMounts": []
        }
    ],
    "environment": {},
    "id": "/simplepod2",
    "labels": {},
    "networks": [
        {
            "labels": {},
            "mode": "host",
            "name": null
        }
    ],
    "scaling": {
        "instances": 2,
        "kind": "fixed",
        "maxInstances": null
    },
    "scheduling": {
        "backoff": {
            "backoff": 1,
            "backoffFactor": 1.15,
            "maxLaunchDelay": 3600
        },
        "placement": {
            "acceptedResourceRoles": [],
            "constraints": []
        },
        "upgrade": {
            "maximumOverCapacity": 1,
            "minimumHealthCapacity": 1
        }
    },
    "secrets": {},
    "user": null,
    "volumes": []
}

Status

Get the status of all pods:

curl -X GET http://<ip>:<port>/v2/pods/::status

Get the status of a single pod:

curl -X GET http://<ip>:<port>/v2/pods/<pod-id>::status

Delete

curl -X DELETE http://<ip>:<port>/v2/pods/<pod-id>

Example Pod Definitions

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

Field Type Value
id (required) string Unique ID for the pod.
containers (required) array See Basic pod container fields.
volumes array All volumes associated with the pod.
volumes.name string Name of shared volume.
volumes.host string Absolute 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.
networks array Accepts the following parameters: mode, name, and labels.
networks.mode string Network 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:name string Required for container network mode.
networks.labels object Key/value pairs (i.e., for passing metadata to Mesos modules).
scaling array Accepts the following parameters: kind, instances, and maxInstances.
scaling.kind string Type of scaling. Only fixed is currently supported.
scaling.instances integer Initial number of pod instances (default: 1).
scaling.maxInstances integer Maximum number of instances of this pod.

Basic pod container fields

Field Type Value
containers (required) array Container definitions for all containers that belong to a pod.
containers.name string Unique name for the container.
containers.exec object Accepts the command parameter.
containers.exec.command object Command executed by Mesos.
containers.exec.command.shell string Command to execute. If using container entrypoint, use an empty string.
containers.exec.overrideEntrypoint boolean If command is supplied, this is implicitly set to true. To use the default entrypoint, set to false.
containers:resources (required) object Container specifications for resources.
containers.resources.cpus number CPU shares (default: 1.0).
containers.resources.mem number Memory resources in MiB (default: 128).
containers.resources.disk double Disk resources in MiB (default: 128).
containers.resources.gpus integer GPU resources (default: 0).
containers.image object If image is omitted, the Mesos containerizer is used.
containers.image.kind string Container image format (DOCKER or APPC).
containers.image.id string Container image tag.
containers.image.forcePull boolean Set to true to always pull image (default: false).
containers.volumeMounts array Accepts the following parameters: name and mountPath.
containers.volumeMounts.name string Name of the shared volume (must be a valid volume defined at the pod layer).
containers.volumeMounts.mountPath string Container path to mount volume.
containers.endpoints array Array of objects.
containers.endpoints.name string Unique name of port.
containers.endpoints.containerPort number The container point the container task is listening on. Required if network mode is container.
containers.endpoints.hostPort number Mapped port on host. If set to 0, Marathon dynamically allocates the port.
containers.endpoints.protocol array Protocol of port (tcp or http).
containers.endpoints.labels object Metadata 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.

{
   "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,
         "maxLaunchDelay":3600
      },
      "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

Field Type Value
labels object Pod metadata as key/value pairs.
environment object Environment variables at the pod level. All pod containers will inherit these environment variables. Must be capitalized.
secrets object The fully qualified path to the secret in the store.
scheduling object Defines exponential backoff behavior for faulty apps to prevent sandboxes from filling up.
scheduling.backoff number Initial backoff (seconds) applied when a launched instance fails (default: 1).
scheduling.backoffFactor number Factor applied to current backoff to determine the new backoff (default: 1.15).
scheduling.maxLaunchDelay number Maximum backoff (seconds) applied when subsequent failures are detected (default: 3600).
upgrade object Upgrade strategy that controls pod updates.
upgrade.minimumHealthCapacity number Number between 0 and 1 that represents the minimum number of healthy nodes to maintain during upgrade (default: 1).
upgrade.maximumOverCapacity number Number between 0 and 1 representing the maximum number of additional instances to launch during upgrade (default: 1).
placement object Controls placement of pod tasks.
placement.constraints string[] Constraints control the placement policy of pod tasks. Options: UNIQUE, CLUSTER, GROUP_BY, LIKE, UNLIKE, MAX_PER.
placement.acceptedResourceRoles string[] List of resource roles. The Marathon component will only consider resource offers with roles on this list for this pod’s tasks.
killSelection string Defines which instance is killed first when an app is in an over-provisioned state. Options: YOUNGEST_FIRST, OLDEST_FIRST.
unreachableStrategy   Behavior when agents are partitioned from masters.
killSelection.inactiveAfterSeconds integer Time in seconds to wait before replacing task (default: 900).
killSelection.expungeAfterSeconds integer Time in seconds to wait for tasks to come back before expunging (default: 603800).
executorResources object Resources reserved for the pod executor.
executorResources.cpus number CPU shares (default: 0.1).
executorResources.mem number Memory resources in MiB (default: 32).
executorResources.disk number Disk resources in MiB (default: 10.0),

Additional pod container fields

Field Type Value
labels object Container metadata as key/value pairs.
environment object Container environment variables. Can override pod environment variables. Must be capitalized.
healthCheck object Accepts the following parameters: http, tcp, and exec.
healthCheck.http   Protocol type. Options: http, tcp, exec.
healthCheck.http.endpoint string Endpoint name to use.
healthCheck.http.path string Path to the endpoint exposed by the task that provides health status.
healthCheck.http.scheme string For httpHealthCheck, use http.
healthCheck.gracePeriodSeconds integer Interval to ignore health check failures after a task is first started or until a task is first healthy (default: 300).
healthCheck.intervalSeconds integer Interval between health checks (default: 60).
healthCheck.maxConsecutiveFailures integer Number of consecutive failures before task is killed (default: 3).
healthCheck.timeoutSeconds integer Time to wait until health check is complete (default: 20).
healthCheck.delaySeconds integer Time to wait until starting health check (default: 2).
artifacts array Array of artifact objects
healthCheck.uri strings URI to resources to download (i.e., .tgz, tar.gz, .zip, .txz, etc).
healthCheck.extract boolean Extract fetched artifact.
healthCheck.executable boolean Set fetched artifact as executable.
healthCheck.cache boolean Cache fetched artifact.
healthCheck.destPath strings Destination path of artifact.

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,
         "maxLaunchDelay":3600
      },
      "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,
      "maxLaunchDelay": 3600
    },
    "upgrade": {
      "minimumHealthCapacity": 1,
      "maximumOverCapacity": 1
    },
    "killSelection": "Youngest_First",
    "unreachableStrategy": {
      "inactiveAfterSeconds": 900,
      "expungeAfterSeconds": 604800
    }
  },
  "executorResources": {
    "cpus": 0.1,
    "mem": 32,
    "disk": 10
  }
}

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,
      "maxLaunchDelay": 3600
    },
    "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
      }
    }
  ]
}

Limitations

  • If a pod belongs to a group that declares dependencies, these dependencies are implicit for the pod. If a group deployment operation is blocked because of a dependency, and that group contains a pod, then that pod’s deployment is also blocked.

  • Pods cannot be modified by the /v2/groups/ endpoint. They are read-only at the /v2/groups/ endpoint.

  • Pods only support Mesos-based health checks.

  • There is no service port tracking or allocation for pods.

  • Pod definitions do not provide a field to declare dependencies on other v2 API objects.

  • Pods do not support readiness checks.

  • Killing any task of a pod will result in the suicide of the pod executor that owns the task, which means that all of the applications in that pod instance will die.