From 3c80dc48b60b725339f285088c0c420d395609dd Mon Sep 17 00:00:00 2001 From: RainbowMango Date: Tue, 5 Nov 2019 22:03:09 +0800 Subject: [PATCH 1/2] Update KEP about the escape hatch flag. --- ...ernetes-control-plane-metrics-stability.md | 37 ++++++++++++++++++- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md b/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md index 30d4e27981a..3511ced1a35 100644 --- a/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md +++ b/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md @@ -20,7 +20,7 @@ approvers: - "@x13n" editor: "@brancz" creation-date: 2019-04-04 -last-updated: 2019-06-05 +last-updated: 2019-11-06 status: implementable see-also: - 20181106-kubernetes-metrics-overhaul @@ -260,7 +260,40 @@ some_counter 0 ``` Like their stable metric counterparts, deprecated metrics will be automatically registered to the metrics endpoint. -On a subsequent release (when the metric's deprecatedVersion is equal to current_kubernetes_version - 1)), a deprecated metric will become a __hidden metric__. _Unlike_ their deprecated counterparts, hidden metrics will __*no longer be automatically registered*__ to the metrics endpoint (hence hidden). However, they can be explicitly enabled through a command line flag on the binary (i.e. '--enable-hidden-metrics=really_deprecated_metric'). This is to provide cluster admins an escape hatch to properly migrate off of a deprecated metric, if they were not able to react to the earlier deprecation warnings. Hidden metrics should be deleted after one release. +On a subsequent release (when the metric's deprecatedVersion is equal to current_kubernetes_version - 1)), a deprecated metric will become a __hidden metric__. _Unlike_ their deprecated counterparts, hidden metrics will __*no longer be automatically registered*__ to the metrics endpoint (hence hidden). However, they can be explicitly enabled through a command line flag on the binary (i.e. '--show-hidden-metrics-for-version='). This is to provide cluster admins an escape hatch to properly migrate off of a deprecated metric, if they were not able to react to the earlier deprecation warnings. Hidden metrics should be deleted after one release. + +### Show Hidden Metrics +As described above, admins can enable hidden metrics through a command-line flag on a specific binary. +This intends to be used as an escape hatch for admins if they missed the migration of the metrics deprecated in the last release. + +The flag `show-hidden-metrics-for-version` takes a version for which you want to show metrics deprecated in that release. +The version is expressed as __x.y__, where __x__ is the major version, __y__ is the minor version. +The patch version is not needed even though a metrics can be deprecated in a patch release, the reason for that is +the metrics deprecation policy runs against the minor release. + +The flag can only take the previous minor version as it's value. +All metrics hidden in previous will be emitted if admins set the previous version to `show-hidden-metrics-for-version`. +The too old version is not allowed because this violates the metrics deprecated policy. + +Take metric `A` as an example, here assumed that `A` is deprecated in `1.n`. +According to metrics deprecated policy, we can reach the following conclusion: +- In release `1.n`, the metric is deprecated, and it can be emitted by default. +- In release `1.n+1`, the metric is hidden by default and it can be emitted by command line `show-hidden-metrics-for-version=1.n`. +- In release `1.n+2`, the metric should be removed from the codebase. No escape hatch anymore. + +So, if admins want to enable metric `A` in release `1.n+1`, they should set `1.n` to the command line flag. +That is `show-hidden-metrics=1.n`. + +### Why Not Bool Flag +Alternatively, another solution which was previously suggested(refer to the discussion on [PR](https://github.com/kubernetes/kubernetes/pull/84292)) +was provide a bool flag-like `show-hidden-metrics`. That works like: +- `show-hidden-metrics=true`: enable all hidden metrics deprecated in a previous minor version. +- `show-hidden-metrics=false`: the default value, do nothing. + +This proposal has a side effect(thanks for @lavalamp pointed it out) in the scenario: +1. in version X, turn this on to get back deprecated metric M +2. in version Y, not turn this off, and therefore fail to notice metric N is being deprecated +3. in version Z, metric N is removed with (effectively) no warning ## Design Details From e81e67cdcc034b1c3326408203cb003b8705b3fa Mon Sep 17 00:00:00 2001 From: RainbowMango Date: Thu, 7 Nov 2019 21:34:01 +0800 Subject: [PATCH 2/2] Update TOC by hack/update-toc.sh --- .../20190404-kubernetes-control-plane-metrics-stability.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md b/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md index 3511ced1a35..8a53ea2bf27 100644 --- a/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md +++ b/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md @@ -43,6 +43,8 @@ see-also: - [Stability Classes](#stability-classes) - [API Review](#api-review) - [Deprecation Lifecycle](#deprecation-lifecycle) + - [Show Hidden Metrics](#show-hidden-metrics) + - [Why Not Bool Flag](#why-not-bool-flag) - [Design Details](#design-details) - [Test Plan](#test-plan) - [Graduation Criteria](#graduation-criteria)