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.
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.
Here is an proposed example of what this deprecation mechanism could look like:
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:
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: