Skip to content

add deprecation policy for k8s metrics #27202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 31, 2021
Merged

add deprecation policy for k8s metrics #27202

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b95b750
add deprecation policy for metrics
Mar 24, 2021
43ec777
Update content/en/docs/reference/using-api/deprecation-policy.md
Mar 30, 2021
2f8d0da
amend stability language given review comments
Mar 30, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 44 additions & 1 deletion content/en/docs/reference/using-api/deprecation-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,7 @@ Starting in Kubernetes v1.19, making an API request to a deprecated REST API end

1. Returns a `Warning` header (as defined in [RFC7234, Section 5.5](https://tools.ietf.org/html/rfc7234#section-5.5)) in the API response.
2. Adds a `"k8s.io/deprecated":"true"` annotation to the [audit event](/docs/tasks/debug-application-cluster/audit/) recorded for the request.
3. Sets an `apiserver_requested_deprecated_apis` gauge metric to `1` in the `kube-apiserver`
3. Sets an `apiserver_requested_deprecated_apis` gauge metric to `1` in the `kube-apiserver`
process. The metric has labels for `group`, `version`, `resource`, `subresource` that can be joined
to the `apiserver_request_total` metric, and a `removed_release` label that indicates the
Kubernetes release in which the API will no longer be served. The following Prometheus query
Expand Down Expand Up @@ -428,6 +428,49 @@ transitions a lifecycle stage as follows. Feature gates must function for no les
is deprecated it must be documented in both in the release notes and the corresponding CLI help.
Both warnings and documentation must indicate whether a feature gate is non-operational.**

## Deprecating a metric

Each component of the Kubernetes control-plane exposes metrics (usually the
`/metrics` endpoint), which are typically ingested by cluster administrators.
Not all metrics are the same: some metrics are commonly used as SLIs or used
to determine SLOs, these tend to have greater import. Other metrics are more
experimental in nature or are used primarily in the Kubernetes development
process.

Accordingly, metrics fall under two stability classes (`ALPHA` and `STABLE`);
this impacts removal of a metric during a Kubernetes release. These classes
are determined by the perceived importance of the metric. The rules for
deprecating and removing a metric are as follows:

**Rule #9: ALPHA metrics have no guarantees and can be removed at any time.**

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

* **STABLE metric: 3 releases**
Copy link
Member

@liggitt liggitt Mar 25, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@logicalhan logicalhan Mar 25, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@liggitt liggitt Mar 25, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

* **STABLE (but deprecated): 2 releases**
* **STABLE (but deprecated and now hidden by default): 1 release**
Copy link
Contributor

@lavalamp lavalamp Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@logicalhan logicalhan Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, they overlap. I'll rephrase.


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
Copy link
Contributor

@lavalamp lavalamp Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@logicalhan logicalhan Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sgtm

deprecating a stable metric, a future Kubernetes release is specified as the point from
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
Copy link
Contributor

@lavalamp lavalamp Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@logicalhan logicalhan Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@lavalamp lavalamp Mar 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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
Copy link
Contributor

@sftim sftim Mar 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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 provides cluster admins an
Copy link
Contributor

@sftim sftim Mar 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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.


## Exceptions

No policy can cover every possible situation. This policy is a living
Expand Down