The networking section of the Marathon API has changed significantly in version 1.5. Marathon can still accept requests using the 1.4 version of the API, but it will always reply with the 1.5 version of the app definition.
This WILL likely break tools that consume networking-related fields of the application definition.
This document contains the high-level structural differences between the 1.4 and 1.5 API versions. You can read more details regarding the networking section and the correct values for every field in the networking documentation.
Marathon now supports applications attached to more than one network. However, additional rules apply when you specify more than one network:
If a portMapping has defined a hostPort and more than one container network is declared, the networkNames array must be defined with the name of the networks it’s referring to.
An application can join one or more container mode networks. When joining multiple container networks, there are additional restrictions on port mapping entries (see Port Mappings for details).
An application can only join one host mode network. This is the default if an app definition does not declare a networks field.
An application can only join one container/bridge network.
An application cannot mix networking modes: you must either specify a single host network, a single container/bridge network, or one or more container networks.
The following table summarizes the API transformations when using the network API in Virtual Network Mode:
| 1.4 API | 1.5 API |
|---|---|
{
"container": {
"docker": {
"image": "image-name",
"network": "USER",
"portMappings": [
{
"containerPort": 0,
"name": "port-name"
}
]
}
},
"ipAddress": {
"networkName": "network-name"
}
}
|
{
"container": {
"docker": {
"image": "image-name"
},
"portMappings": [
{
"containerPort": 0,
"name": "port-name"
}
]
},
"networks": [
{
"mode": "container",
"name": "network-name"
}
]
}
|
Changes from 1.4 to 1.5
ipAddresses : Removed.container.docker.network : Removed.container.docker.portMappings : Moved to container.portMappings.networks : Added.networks[x].mode : Is container for virtual network.Breaking Feature: Starting from the 1.5 API, you can specify multiple container networks. There are a few things to consider in this case:
An application can join only join multiple networks using the Mesos containerizer (MESOS). Although Docker itself supports multiple networks per container, the Docker containerizer implementation within Mesos does not support multiple networks.
An application cannot mix networking modes: you must specify a single host network, a single container/bridge network, or one or more container networks.
The following table summarizes the changes when using single or multiple networks:
| 1.5 API (Single Network) | 1.5 API (Multiple Networks) |
|---|---|
{
"container": {
"portMappings": [
{
"containerPort": 0,
"name": "port-name"
}
]
},
"networks": [
{
"mode": "container",
"name": "network-name-1"
}
]
}
|
{
"container": {
"portMappings": [
{
"containerPort": 0,
"name": "a-port-name",
"networkNames": ["network-name-1"]
},
{
"containerPort": 0,
"name": "another-port-name",
"networkNames": ["network-name-2"]
}
]
},
"networks": [
{
"mode": "container",
"name": "network-name-1"
},
{
"mode": "container",
"name": "network-name-2"
}
]
}
|
The following table summarizes the API transformations when using the network API in Bridge Mode:
| 1.4 API | 1.5 API |
|---|---|
{
"container": {
"docker": {
"image": "image-name",
"network": "BRIDGE",
"portMappings": [
{
"containerPort": 0,
"hostPort": 0,
"name": "port-name"
}
]
}
}
"ipAddress": {
"networkName": "network-name"
}
}
|
{
"container": {
"docker": {
"image": "image-name"
},
"portMappings": [
{
"containerPort": 0,
"hostPort": 0,
"name": "port-name"
}
]
},
"networks": [
{
"mode": "container/bridge"
}
]
}
|
Changes from 1.4 to 1.5
ipAddresses : Removed.container.docker.network : Removed.container.docker.portMappings : Moved to container.portMappings.networks : Added.networks[x].mode : Is container/bridge for bridge network.container/bridge network.host network, a single container/bridge network, or one or more container networks.The following table summarizes the API transformations when using the network API in Host Mode:
| 1.4 API | 1.5 API |
|---|---|
{
"container": {
"type": "DOCKER",
"docker": {
"image": "image-name",
"network": "HOST"
}
}
"portDefinitions": [
{
"name": "port-name",
"protocol" ...,
"port": ...
}
]
}
|
{
"container": {
"type": "DOCKER",
"docker": {
"image": "image-name"
}
},
"networks": [
{
"mode": "host",
}
],
"portDefinitions": [
{
"name": "port-name",
"protocol" ...,
"port": ...
}
]
}
|
Changes from 1.4 to 1.5
container.docker.network : Removed.portDefinitions : Remains the same.networks : Added. Optional (in this instance). Default is host mode.networks[x].mode : Is host for Bridge Network.host networks.host network, a single container/bridge network, or one or more container networks.The following definitions WILL be accepted by the new API.
| 1.4 API | 1.5 API |
|---|---|
{
"id": "user-net-old",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "DOCKER",
"docker": {
"network": "USER",
"image": "nginx",
"portMappings": [
{
"containerPort": 80,
"protocol": "tcp",
"name": "web"
}
]
}
},
"ipAddress": {
"networkName": "dcos"
}
}
|
{
"id": "user-net-new",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "DOCKER",
"docker": {
"image": "nginx"
},
"portMappings": [
{
"containerPort": 80,
"protocol": "tcp",
"name": "web"
}
]
},
"networks": [
{
"mode": "container",
"name": "dcos"
}
]
}
|
The following definition is now possible with the new API.
| 1.4 API | 1.5 API |
|---|---|
//not supported
|
{
"id": "user-net-multi",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "MESOS",
"docker": {
"image": "nginx"
},
"portMappings": [
{
"containerPort": 80,
"protocol": "tcp",
"name": "web",
"networkNames": ["first"]
},
{
"containerPort": 81,
"protocol": "tcp",
"name": "admin",
"networkNames": ["second"]
}
]
},
"networks": [
{
"mode": "container",
"name": "first"
},
{
"mode": "container",
"name": "second"
}
]
}
|
| 1.4 API | 1.5 API |
|---|---|
{
"id": "bridge-net-old",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "DOCKER",
"docker": {
"image": "nginx",
"network": "BRIDGE",
"portMappings": [
{
"containerPort": 80,
"hostPort": 0,
"protocol": "tcp",
"name": "web" }
]
}
}
}
|
{
"id": "bridge-net-new",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "DOCKER",
"docker": {
"image": "nginx"
},
"portMappings": [
{
"containerPort": 80,
"hostPort": 0,
"protocol": "tcp",
"name": "web"
}
]
},
"networks": [
{
"mode": "container/bridge"
}
]
}
|
| 1.4 API | 1.5 API |
|---|---|
{
"id": "host-net-old",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "DOCKER",
"docker": {
"image": "nginx",
"network": "HOST"
}
},
"portDefinitions": [
{
"port": 0,
"protocol": "tcp",
"name": "web"
}
]
}
|
{
"id": "host-net-new",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "DOCKER",
"docker": {
"image": "nginx"
}
},
"portDefinitions": [
{
"port": 0,
"protocol": "tcp",
"name": "web"
}
],
"networks": [
{
"mode": "host"
}
]
}
|
You cannot combine network types.
| 1.5 API |
|---|
{
"id": "x-mixed-networks",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "DOCKER",
"docker": {
"image": "nginx"
}
},
"portDefinitions": [
{
"port": 0,
"protocol": "tcp",
"name": "web"
}
],
"networks": [ // Invalid because network modes cannot be mixed. Only multiple container networks are allowed.
{ "mode": "host" },
{ "mode": "container/bridge" }
]
}
|
You must supply a name property to use a container network unless you set the default_network_name flag when configuring Marathon. Learn more about command line flags.
| 1.5 API |
|---|
{
"id": "x-missing-name",
"cpus": 1,
"mem": 128,
"instances": 1,
"container": {
"type": "DOCKER",
"docker": {
"image": "nginx"
}
},
"portDefinitions": [
{
"port": 0,
"protocol": "tcp",
"name": "web"
}
],
"networks": [ // Possibly invalid because the `networks[x].name` parameter is not supplied
{ "mode": "container" }
]
}
|