Support app/group config replacement instead of only updates (PUT semantics)

[kolloch]

Currently, PUT requests on apps or groups update current app definitions instead of replacing them. If the app already exists, only the fields mentioned in the request are updated. If a field is not mentioned, it will not be removed but it remains unchanged.

If you want to delete a field, it is not possible. Even setting it explicitly to null in the JSON does not work. You have to delete the app definition first and thus cannot perform a rolling update.

It would be very nice if you could specify a complete definition which completely replaces an old one. This way the app definition could be a build artefact. The developer adjusting the build artefact doesn't have to think in terms of all possible upgrade paths but only has to specify what he wants in the future.

We cannot just change the semantics of our PUT requests without breaking API compatibility but I propose to

[update] add a boolean parameter replace. The value false would correspond to the current semantics and remain the default. If you want to replace an app definition completely, you would use PUT /v2/apps/service1?replace=true instead of PUT /v2/apps/service1.

[initial version] add a Parameter op which can be either update or replace. update would correspond to the current semantics and remain the default. If you want to replace an app definition completely, you would use PUT /v2/apps/service1?op=replace instead of PUT /v2/apps/service1.

Example: Updating an App to a Dockerized Version

Start a simple non-docker app:

PUT /v2/apps/service1 HTTP/1.1
<some headers>

{
    "cmd": "python -m SimpleHTTPServer $PORT0", 
    "cpus": 0.0001, 
    "id": "service1", 
    "instances": 1, 
    "mem": 32, 
    "ports": [
        0
    ]
}

HTTP/1.1 201 Created
<some headers>

{
    "deploymentId": "552a0b26-9674-4c5d-a39d-528c0db25cf0", 
    "version": "2015-04-22T10:11:16.105Z"
}

Now try to upgrade it to a dockerized version:

PUT /v2/apps/service1 HTTP/1.1
<some headers>

{
    "args": [
        "python", 
        "-m", 
        "SimpleHTTPServer", 
        "8080"
    ], 
    "cmd": null, 
    "container": {
        "docker": {
            "image": "python:2.7", 
            "network": "BRIDGE", 
            "portMappings": [
                {
                    "containerPort": 8080, 
                    "hostPort": 0, 
                    "protocol": "tcp", 
                    "servicePort": 0
                }
            ]
        }, 
        "type": "DOCKER"
    }, 
    "cpus": 0.0001, 
    "id": "service1", 
    "instances": 1, 
    "mem": 32
}

HTTP/1.1 422 
<some headers>

{
    "errors": [
        {
            "attribute": "", 
            "error": "AppDefinition must either contain one of 'cmd' or 'args', and/or a 'container'."
        }
    ]
}

If you DELETE the app first and repeat the second request, it works.

[kolloch]

@ssk2, @ConnorDoyle For your client, it would also be nice to be able to replace app definitions fully instead of patching them. What do you think?

[ssk2]

That makes sense. I'd rephrase the parameter name to "replace=true" and leave update as the default behaviour (it's more intuitive than "op") - what do you think?

[kolloch]

@ssk2 makes sense. For me it's equally good. If it is better for you, then it's reason enough for me to change that.

[kolloch]

@ssk2 I checked the description above to match your proposal (hopefully ;) )

[ssk2]

Looks good :)

[modeyang]

whether this issue has solution? marathon version 1.1.0 still confront the bug. can any one help me ?

[Colstuwjx]

+1, wishes actually add replace=true feature to make it works.

[timoreimann]

The Marathon 1.4.0 release notes mention that PATCH semantics for PUT will be deprecated and replaced by a proper distinction in a future release.

[meichstedt]

Note: This issue has been migrated to https://jira.mesosphere.com/browse/MARATHON-4745. For more information see https://groups.google.com/forum/#!topic/marathon-framework/khtvf-ifnp8.