Migrating Tools to the 1.5 Networking API

Overview

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.

Important notes

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.

Applications

Container Network (Virtual Network)

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.

Important Notes

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"
        }
    ]
}

Bridge Network

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.

Important Notes

  • An application cannot use more than one container/bridge network.
  • An application cannot mix networking modes: you must specify a single host network, a single container/bridge network, or one or more container networks.

Host Network

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.

Important Notes

  • An application cannot use more than one host 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.

Example Definitions

Valid Definitions

App with container network

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"
    }
  ]
}

App with multiple container networks

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"
    }
  ]
}

App with bridge network

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"
    }
  ]
}

App with host network

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"
    }
  ]
}

Invalid Definitions

Mixed Networks (Invalid)

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" }
  ]
}

Missing container network name (Invalid)

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" }
  ]
}