As we've been making great strides in preserving API compatibility, we'll want to be able to phase out endpoints, features, and schema versions. In order to stay consistent with it, I propose that we have a general mechanism for expressing these deprecations.


      To summarize, some goals for the solution:

      • Deprecations, such as for health checks, will need to be asserted in multiple places in order to be effective, including in the storage layer (initial load should fail if your apps are using a deprecated feature)
      • Provide a common way of expressing these deprecations.
      • Provide a common way of communicating deprecations to users (for our API, map the exception to an appropriate error response. Otherwise, log the exception and crash Marathon).
      • Provide a mechanism by which users will know they are safe to upgrade (remove all deprecated flags, check to see config still works, then upgrade)
      • Prevent the user early from accidentally upgrading to a version that will no longer allow the deprecated flag.
      • Enforce this through automation, so we need only advance the version in order to progress the deprecation cycle.

      Proposed Solution (example versions)

      Marathon 1.8: Warning / Logs (UI)

      Each time an app/pod definition is updated/created that mentions marathon health checks, we will log a warning. During Marathon start up, for each app/pod loaded that uses Marathon health checks, a warning is logged.

      In Marathon 1.8, if a user edits an app/pod definition that mentions Marathon HealthChecks, then the DCOS UI and OSS UI will show a deprecation notice, with a link to instructions for how to switch to Mesos health checks, and the motivations, etc.

      Marathon 1.9: Marathon health checks are disabled, by default

      Here is an proposed example of what this deprecation mechanism could look like:

      class Deprecations(bypassedDeprecations: Seq[String]) {
        val deprecator = Deprecator(bypassedDeprecations)
        val HealthChecksDeprecation = deprecator[RunSpec]("MARATHON_HEALTH_CHECKS", description = "...", withFlag = "1.7", removeCompletely = "1.8") { runSpec =>
          runSpec.healthChecks.forall(_.healthCheckType != "HTTP") // etc.
      class AppsResource {
        def create(...): Response = {
          runSpec = Raml.fromRaml(Json.parse(body))

      If the user boots up Marathon 1.9, and has any apps defined with health checks, then while loading the initial state, the deprecation assertion logic will kick in and will cause Marathon to crash with the following message:

      Deprecation error: MARATHON_HEALTH_CHECKS have been deprecated!
      You are seeing this message because you are using a feature of Marathon than has been deprecated.
      Marathon HTTP/TCP health checks have known performance issues and have been deprecated in favor of Mesos health checks. This can be achieved by changing the health check types from "HTTP" to "MESOS_HTTP" (etc.)
      You can re-enable Marathon's health check functionality by adding the following command-line parameter to Marathon: {{--deprecated_features MARATHON_HEATLH_CHECKS}}. Please see the command-line parameter documentation [link] for further information about how this is used.

      Marathon 1.10: Marathon health checks are removed; launching with deprecation grace period feature flag crashes instantly.

      If the user boots up Marathon 1.10, and this feature flag is still enabled, we will crash instantly (won't even make it to leader election). With the following message:

      Deprecated features are enabled: MARATHON_HEALTH_CHECKS
      This feature has been removed in Marathon 1.10.x and it is not possible to re-enable. We recommend that you roll back to Marathon 1.9.x, remove all deprecation flags, and extensively check that your configuration works before attempting to upgrade again.


          Issue Links



              • Assignee:
                tharper Tim Harper
                tharper Tim Harper
                ( DO NOT USE ) Orchestration Team
                Pawel Rozlach, Tim Harper, Todd Greenstein (Inactive)
              • Watchers:
                3 Start watching this issue


                • Created: