add deprecation policy for k8s metrics #27202

logicalhan · 2021-03-24T19:00:21Z

Metric stability is now GA, updating deprecation policy accordingly.

logicalhan · 2021-03-24T19:00:37Z

/assign @lavalamp

logicalhan · 2021-03-24T19:00:48Z

/sig instrumentation

netlify · 2021-03-24T19:13:39Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit b95b750

https://deploy-preview-27202--kubernetes-io-master-staging.netlify.app

lavalamp · 2021-03-24T20:57:33Z

content/en/docs/reference/using-api/deprecation-policy.md

+
+ * **STABLE metric: 3 releases**
+ * **STABLE (but deprecated): 2 releases**
+ * **STABLE (but deprecated and now hidden by default): 1 release**


This list isn't super clear, are these separate steps? Or do they overlap?

ah, they overlap. I'll rephrase.

lavalamp · 2021-03-24T21:00:41Z

content/en/docs/reference/using-api/deprecation-policy.md

+ * **STABLE (but deprecated and now hidden by default): 1 release**
+
+Deprecated metrics have the same stability guarantees of their counterparts. If a stable
+metric is deprecated, then a deprecated stable metric is guaranteed to not change. When


this sentence is super confusing but I don't know how to help it. Maybe don't make "alpha and deprecated" to be a possible thing. Alpha metrics just get removed, not deprecated. So all "deprecated" metrics must have once been stable, and therefore can't be changed, just like other stable metrics.

lavalamp · 2021-03-24T21:01:31Z

content/en/docs/reference/using-api/deprecation-policy.md

+which the metric will be considered deprecated.
+
+Deprecated metrics will have their description text prefixed with a deprecation notice
+string '(Deprecated from x.y)' and a warning log will be emitted during metric


What is the point to this warning log? consumers of the metrics aren't going to be looking at the logs at that time.

I disagree actually. Cluster admins also tend to also be consumers of metrics, so they may end up looking at the logs.

Sure, I don't object to logging them, but I can't believe it's going to happen very often that the person in charge of metrics ingestion is going to happen to be reading the logs and learn about the deprecation there for the first time, in advance of their metrics ingestion breaking.

lavalamp · 2021-03-24T21:04:02Z

2 releases is pretty short for this. 4 would align more with api deprecation.

I think you should get someone other than me from sig arch to sign off too. Maybe @liggitt.

logicalhan · 2021-03-24T21:05:10Z

2 releases is pretty short for this. 4 would align more with api deprecation.

I think you should get someone other than me from sig arch to sign off too. Maybe @liggitt.

It's actually 3 releases. But yeah we can modify it to be 4.

logicalhan · 2021-03-24T21:06:21Z

I guess it depends where you are counting from though.

logicalhan · 2021-03-24T21:06:31Z

/assign @liggitt

lavalamp · 2021-03-24T21:08:12Z

Yeah I was counting until they disappear by default.

sftim · 2021-03-24T22:39:10Z

Is this a change for v1.21 or for v1.20 @logicalhan ?

(If it's for v1.21, the PR should target dev-1.21 - master represents the live website).

logicalhan · 2021-03-24T22:43:32Z

Is this a change for v1.21 or for v1.20 @logicalhan ?

(If it's for v1.21, the PR should target dev-1.21 - master represents the live website).

Updated :)

sftim · 2021-03-24T22:50:23Z

/milestone 1.21

reylejano · 2021-03-24T22:55:45Z

/assign
Hi @logicalhan, is this related to kubernetes/enhancements#1209

reylejano · 2021-03-24T23:00:19Z

/assign @PI-Victor

logicalhan · 2021-03-25T00:55:50Z

/assign
Hi @logicalhan, is this related to kubernetes/enhancements#1209

It is indeed.

liggitt · 2021-03-25T16:54:55Z

content/en/docs/reference/using-api/deprecation-policy.md

+
+**Rule #10: STABLE metrics must undergo a deprecation lifecycle prior to removal.**
+
+ * **STABLE metric: 3 releases**


Suggest a X releases or X months, whichever is longer approach (matching GA API lifetimes would make sense to me)

Also, the 12 month guaranteed lifetime for GA APIs looks increasingly insufficient. We have enormous difficulty getting people to move from beta APIs to GA APIs in a year, let alone moving from one GA API to another. I think the promise of GA APIs (or "stable" metrics in this case) is effectively forever

We have a built-in forcing function for migration. We break people but allow them to unbreak themselves for a release to migrate.

We break people but allow them to unbreak themselves for a release to migrate.

That doesn't match my understanding of "stable" or "GA".

content/en/docs/reference/using-api/deprecation-policy.md

reylejano · 2021-03-26T21:43:43Z

@kubernetes/sig-instrumentation-approvers , please provide a technical review for this PR by March 31 to get this into the release. Thank you!

PI-Victor · 2021-03-29T16:11:48Z

Hi @brancz @x13n @DirectXMan12 @lavalamp @dashpole @ehashman @mml @sttts @bsalamat @andrewsykim you are listed as reviewers for KEP-1209: Metrics Stability Framework i would like to ask you to please provide a tech review of this PR by March 31st in order for it to make it into the release.
Thank you!

reylejano · 2021-03-30T16:14:04Z

Hi @logicalhan, please address liggit's comment and sftim's comment

Co-authored-by: Tim Bannister <tim@scalefactory.com>

k8sio-netlify-preview-bot · 2021-03-30T17:36:36Z

Deploy preview for kubernetes-io-vnext-staging processing.

Building with commit 2f8d0da

https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/60636302d46bf30007023ee9

logicalhan · 2021-03-30T17:38:30Z

Hi @logicalhan, please address liggit's comment and sftim's comment

Amended to address comments.

dashpole · 2021-03-30T17:45:36Z

/lgtm

k8s-ci-robot · 2021-03-30T17:45:47Z

LGTM label has been added.

Git tree hash: f3f4dd9dcf02b924bc1fde9c51fc7123b97a4b91

brancz · 2021-03-31T11:15:55Z

/lgtm

reylejano · 2021-03-31T11:32:07Z

/label tide/merge-method-squash
/approve

k8s-ci-robot · 2021-03-31T11:32:30Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: reylejano

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [reylejano]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

sftim

Just for the record

sftim · 2021-03-31T11:26:03Z

content/en/docs/reference/using-api/deprecation-policy.md

+registration. Like their stable undeprecated counterparts, deprecated metrics will
+be automatically registered to the metrics endpoint and therefore visible.
+
+On a subsequent release (when the metric's deprecatedVersion is equal to


nit:

Suggested change

On a subsequent release (when the metric's deprecatedVersion is equal to

On a subsequent release (when the metric's `deprecatedVersion` is equal to

sftim · 2021-03-31T11:26:23Z

content/en/docs/reference/using-api/deprecation-policy.md

+**_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 provides cluster admins an


nit: we avoid Latin abbreviations

Suggested change

(i.e. `--show-hidden-metrics-for-version=`). This provides cluster admins an

( `--show-hidden-metrics-for-version=`). This provides cluster admins an

sftim · 2021-03-31T11:36:37Z

Thanks @logicalhan

reylejano · 2021-03-31T12:30:45Z

PR #27358 is a follow-up PR to address #27202 (review)

add deprecation policy for metrics

b95b750

logicalhan force-pushed the deprecation branch from 4a44447 to b95b750 Compare March 24, 2021 19:00

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Mar 24, 2021

k8s-ci-robot assigned lavalamp Mar 24, 2021

k8s-ci-robot added the sig/instrumentation Categorizes an issue or PR as relevant to SIG Instrumentation. label Mar 24, 2021

k8s-ci-robot requested a review from lavalamp March 24, 2021 19:01

k8s-ci-robot added the language/en Issues or PRs related to English language label Mar 24, 2021

k8s-ci-robot requested a review from thockin March 24, 2021 19:01

k8s-ci-robot added the sig/docs Categorizes an issue or PR as relevant to SIG Docs. label Mar 24, 2021

lavalamp reviewed Mar 24, 2021

View reviewed changes

k8s-ci-robot assigned liggitt Mar 24, 2021

logicalhan changed the base branch from master to dev-1.21 March 24, 2021 22:43

k8s-ci-robot added this to the 1.21 milestone Mar 24, 2021

k8s-ci-robot assigned reylejano Mar 24, 2021

reylejano removed their assignment Mar 24, 2021

k8s-ci-robot assigned PI-Victor Mar 24, 2021

liggitt reviewed Mar 25, 2021

View reviewed changes

sftim reviewed Mar 26, 2021

View reviewed changes

content/en/docs/reference/using-api/deprecation-policy.md Outdated Show resolved Hide resolved

Update content/en/docs/reference/using-api/deprecation-policy.md

43ec777

Co-authored-by: Tim Bannister <tim@scalefactory.com>

logicalhan force-pushed the deprecation branch from a0c0952 to 93ce48a Compare March 30, 2021 17:39

amend stability language given review comments

2f8d0da

logicalhan force-pushed the deprecation branch from 93ce48a to 2f8d0da Compare March 30, 2021 17:42

k8s-ci-robot assigned dashpole Mar 30, 2021

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 30, 2021

k8s-ci-robot assigned brancz Mar 31, 2021

k8s-ci-robot added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Mar 31, 2021

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Mar 31, 2021

k8s-ci-robot merged commit f9bacb2 into kubernetes:dev-1.21 Mar 31, 2021

sftim reviewed Mar 31, 2021

View reviewed changes

reylejano mentioned this pull request Mar 31, 2021

Update deprecation policy for k8s metrics #27358

Merged


		Rule #10: STABLE metrics must undergo a deprecation lifecycle prior to removal.

		* STABLE metric: 3 releases

	On a subsequent release (when the metric's deprecatedVersion is equal to
	On a subsequent release (when the metric's `deprecatedVersion` is equal to

	(i.e. `--show-hidden-metrics-for-version=`). This provides cluster admins an
	( `--show-hidden-metrics-for-version=`). This provides cluster admins an

add deprecation policy for k8s metrics #27202

add deprecation policy for k8s metrics #27202

Conversation

logicalhan commented Mar 24, 2021

logicalhan commented Mar 24, 2021

logicalhan commented Mar 24, 2021

netlify bot commented Mar 24, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lavalamp commented Mar 24, 2021

logicalhan commented Mar 24, 2021

logicalhan commented Mar 24, 2021

logicalhan commented Mar 24, 2021

lavalamp commented Mar 24, 2021

sftim commented Mar 24, 2021

logicalhan commented Mar 24, 2021

sftim commented Mar 24, 2021

reylejano commented Mar 24, 2021

reylejano commented Mar 24, 2021

logicalhan commented Mar 25, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

reylejano commented Mar 26, 2021

PI-Victor commented Mar 29, 2021

reylejano commented Mar 30, 2021

k8sio-netlify-preview-bot commented Mar 30, 2021 • edited Loading

logicalhan commented Mar 30, 2021

dashpole commented Mar 30, 2021

k8s-ci-robot commented Mar 30, 2021

brancz commented Mar 31, 2021

reylejano commented Mar 31, 2021

k8s-ci-robot commented Mar 31, 2021

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim commented Mar 31, 2021

reylejano commented Mar 31, 2021

k8sio-netlify-preview-bot commented Mar 30, 2021 •

edited

Loading