<!-- **Note:** When your KEP is complete, all of these comment blocks should be removed. To get started with this template: - [ ] **Pick a hosting SIG.** Make sure that the problem space is something the SIG is interested in taking up. KEPs should not be checked in without a sponsoring SIG. - [ ] **Create an issue in kubernetes/enhancements** When filing an enhancement tracking issue, please make sure to complete all fields in that template. One of the fields asks for a link to the KEP. You can leave that blank until this KEP is filed, and then go back to the enhancement and add the link. - [ ] **Make a copy of this template directory.** Copy this template into the owning SIG's directory and name it `NNNN-short-descriptive-title`, where `NNNN` is the issue number (with no leading-zero padding) assigned to your enhancement above. - [ ] **Fill out as much of the kep.yaml file as you can.** At minimum, you should fill in the "Title", "Authors", "Owning-sig", "Status", and date-related fields. - [ ] **Fill out this file as best you can.** At minimum, you should fill in the "Summary" and "Motivation" sections. These should be easy if you've preflighted the idea of the KEP with the appropriate SIG(s). - [ ] **Create a PR for this KEP.** Assign it to people in the SIG who are sponsoring this process. - [ ] **Merge early and iterate.** Avoid getting hung up on specific details and instead aim to get the goals of the KEP clarified and merged quickly. The best way to do this is to just start with the high-level sections and fill out details incrementally in subsequent PRs. Just because a KEP is merged does not mean it is complete or approved. Any KEP marked as `provisional` is a working document and subject to change. You can denote sections that are under active debate as follows: ``` <<[UNRESOLVED optional short context or usernames ]>> Stuff that is being argued. <<[/UNRESOLVED]>> ``` When editing KEPS, aim for tightly-scoped, single-topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes. One KEP corresponds to one "feature" or "enhancement" for its whole lifecycle. You do not need a new KEP to move from beta to GA, for example. If new details emerge that belong in the KEP, edit the KEP. Once a feature has become "implemented", major changes should get new KEPs. The canonical place for the latest set of instructions (and the likely source of this file) is [here](/keps/NNNN-kep-template/README.md). **Note:** Any PRs to move a KEP to `implementable`, or significant changes once it is marked `implementable`, must be approved by each of the KEP approvers. If none of those approvers are still appropriate, then changes to that list should be approved by the remaining approvers and/or the owning SIG (or SIG Architecture for cross-cutting KEPs). -->

KEP-5468: Invariant Testing

<!-- This is the title of your KEP. Keep it short, simple, and descriptive. A good title can help communicate what the KEP is and should be considered as part of any review. --> <!-- A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template. Ensure the TOC is wrapped with <code>&lt;!-- toc --&rt;&lt;!-- /toc --&rt;</code> tags, and then generate with `hack/update-toc.sh`. --> <!-- toc -->

• Release Signoff Checklist
• Summary
• Motivation
  • Goals
  • Non-Goals
• Proposal
  • Risks and Mitigations
• Design Details
  • Test Plan
    • Prerequisite testing updates
    • Unit tests
    • Integration tests
    • e2e tests
  • Graduation Criteria
  • Upgrade / Downgrade Strategy
  • Version Skew Strategy
• Production Readiness Review Questionnaire
  • Feature Enablement and Rollback
  • Rollout, Upgrade and Rollback Planning
  • Monitoring Requirements
  • Dependencies
  • Scalability
  • Troubleshooting
• Implementation History
• Drawbacks
• Alternatives
  • Implement outside of test framework
  • Collect data, and scan for it externally
• Infrastructure Needed (Optional)

<!-- /toc -->

§ Release Signoff Checklist

<!-- **ACTION REQUIRED:** In order to merge code into a release, there must be an issue in [kubernetes/enhancements] referencing this KEP and targeting a release milestone **before the [Enhancement Freeze](https://git.k8s.io/sig-release/releases) of the targeted release**. For enhancements that make changes to code or processes/procedures in core Kubernetes—i.e., [kubernetes/kubernetes], we require the following Release Signoff checklist to be completed. Check these off as they are completed for the Release Team to track. These checklist items _must_ be updated for the enhancement to be released. -->

Items marked with (R) are required prior to targeting to a milestone / release.

• (R) Enhancement issue in release milestone, which links to KEP dir in kubernetes/enhancements (not the initial KEP PR)
• (R) KEP approvers have approved the KEP status as implementable
• (R) Design details are appropriately documented
• (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input (including test refactors)
  • e2e Tests for all Beta API Operations (endpoints)
  • (R) Ensure GA e2e tests meet requirements for Conformance Tests
  • (R) Minimum Two Week Window for GA e2e tests to prove flake free
• (R) Graduation criteria is in place
  • (R) all GA Endpoints must be hit by Conformance Tests
• (R) Production readiness review completed
• (R) Production readiness review approved
• "Implementation History" section is up-to-date for milestone
• User-facing documentation has been created in kubernetes/website, for publication to kubernetes.io
• Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes

<!-- **Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone. -->

§ Summary

<!-- This section is incredibly important for producing high-quality, user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins, in order to avoid requiring implementors to split their attention between writing release notes and implementing the feature itself. KEP editors and SIG Docs should help to ensure that the tone and content of the `Summary` section is useful for a wide audience. A good summary is probably at least a paragraph in length. Both in this section and below, follow the guidelines of the [documentation style guide]. In particular, wrap lines to a reasonable length, to make it easier for reviewers to cite specific portions, and to minimize diff churn on updates. [documentation style guide]: https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md -->

With this KEP, we introduce an approach to testing invariants within the cluster across the entire end-to-end test run, with rules in place to minimize the risk of "tragedy of the commons" flakes across CI.

§ Motivation

<!-- This section is for explicitly listing the motivation, goals, and non-goals of this KEP. Describe why the change is important and the benefits to users. The motivation section can optionally provide links to [experience reports] to demonstrate the interest in a KEP within the wider Kubernetes community. [experience reports]: https://github.com/golang/go/wiki/ExperienceReports -->

SIG Testing has received multiple requests to enable testing invariants that span entire end to end test suite runs, as opposed to being isolated to individual tests.

For example, [declarative validation] introduces a metric which, when incremented, indicates a mismatch in declarative and imperative validation, indicating a bug.

Because there is concern about flaking tests and "tragedy of the commons" when a test that spans the entire suite starts to fail in any number of jobs the authors may not be monitoring, we will formalize the approach in this KEP and introduce a principled approach with rules and guardrails.

See:

• https://git.k8s.io/enhancements/keps/sig-api-machinery/4153-declarative-validation/README.md
• https://github.com/kubernetes/kubernetes/pull/133013
• https://github.com/kubernetes/kubernetes/pull/132613#discussion_r2244072152
• https://github.com/kubernetes/kubernetes/pull/133844

Goals

<!-- List the specific goals of the KEP. What is it trying to achieve? How will we know that this has succeeded? -->

• Enable end to end tests to check invariants after the rest of the test suite
• Prevent unowned tests
• Allow opting into / out-of this testing
• Prevent flaking, unreliable tests
• Ensure result reporting is structured
• Must not impact the conformance test suite

Non-Goals

<!-- What is out of scope for this KEP? Listing non-goals helps to focus discussion and make progress. -->

• Enable completely arbitrary checks
• Targeting integration tests.
  • We are specifically aiming for end to end tests for this purpose.

§ Proposal

<!-- This is where we get down to the specifics of what the proposal actually is. This should have enough detail that reviewers can understand exactly what you're proposing, but should not include things like API designs or implementation. What is the desired outcome and how do we measure success?. The "Design Details" section below is for the real nitty-gritty. -->

First, all invariant MUST have clearly documented owners, which will be surfaced with the failure results. No invariant tests may roll up to the general test owners. There is precedent in documenting featuregate and metrics owners.

Similarly, the associated SIG(s) must be registered, for use in tagged related issues.

A shared system will be introduced to the e2e framework to enable this form of testing.

All utilities for this will be owned by the SIG Testing Leads and thoroughly vetted for reliability.

New invariants will be tested many times before merge, and may be demoted at any time by tagging the associated sentinel test [Flaky]. Failure to respond to flaking invariant tests in a timeline fashion will result in demoting or removing them.

Risks and Mitigations

<!-- What are the risks of this proposal, and how do we mitigate? Think broadly. For example, consider both security and how this will impact the larger Kubernetes ecosystem. How will security be reviewed, and by whom? How will UX be reviewed, and by whom? Consider including folks who also work outside the SIG or subproject. -->

If implemented poorly, this could result in tests flaking in any number of e2e test CI jobs that are now running these tests.

We will mitigate this by thoroughly reviewing and testing the invariant checking utilities, and by limiting to only portable, reliable mechanisms.

If not run in many CI jobs, there will be limited benefit to the signal. We will aim to generally introduce these as default selected tests.

§ Design Details

<!-- This section should contain enough information that the specifics of your change are understandable. This may include API specs (though not always required) or even code snippets. If there's any ambiguity about HOW your proposal will be implemented, this is the place to discuss them. -->

[Ginkgo], which we use for the e2e tests, does not have a facility for "this test must run after all other tests". It does have ordering, but only within a group of tests. Alternatively we can run arbitrary code after the suite, but that does not suit our ability to opt-in/out of the tests.

We will introduce a package under test/e2e that contains sentinel test(s) which do nothing other than register to Ginkgo that they have run, if selected.

These tests can be labeled appropriately, allowing the existing test selection mechanisms to select / skip them.

We can then use ginkgo.ReportAfterSuite to inspect which, if any, of these sentinel invariant tests ran, and run the actual test logic, reporting pass/fail.

This allows us the flexibility of treating them like regular tests while ensuring that the actual invariant check occurs after all other tests.

It also ensures that while default-enabled, these tests will not impact conformance testing, since the sentinel tests will not be tagged [Conformance] and therefore will not run, in turn disabling the actual after-suite checks.

Invariant checks will be limited to read-only, such as fetching metrics. Invariant checks should be simple, reliable, cheap code. They ideally run in most e2e test runs for useful coverage.

Failure logs for these invariant checks will include instructions about how to handle the test failure and who to report bugs to, from the documented owners.

Something like this, for the failure message:

Invariant failed for missing metric: <metric-name>

If this failed on a pull request, please check if the PR changes may be related to the failure, if not, you can also search for an existing GitHub issue before filing a new issue.

If this failed in a periodic CI, please file a bug and assign the owners.

Owners for this metric: <github-handles> Associated Special Interest Groups: <sig-foo>

Test Plan

<!-- **Note:** *Not required until targeted at a release.* The goal is to ensure that we don't accept enhancements with inadequate testing. All code is expected to have adequate tests (eventually with coverage expectations). Please adhere to the [Kubernetes testing guidelines][testing-guidelines] when drafting this test plan. [testing-guidelines]: https://git.k8s.io/community/contributors/devel/sig-testing/testing.md -->

[x] I/we understand the owners of the involved components may require updates to existing tests to make this code solid enough prior to committing the changes necessary to implement this enhancement.

Prerequisite testing updates

<!-- Based on reviewers feedback describe what additional tests need to be added prior implementing this enhancement to ensure the enhancements have also solid foundations. -->

This KEP is itself entirely testing updates.

Unit tests

<!-- In principle every added code should have complete unit test coverage, so providing the exact set of tests will not bring additional value. However, if complete unit test coverage is not possible, explain the reason of it together with explanation why this is acceptable. --> <!-- Additionally, for Alpha try to enumerate the core package you will be touching to implement this enhancement and provide the current unit coverage for those in the form of: - <package>: <date> - <current test coverage> The data can be easily read from: https://testgrid.k8s.io/sig-testing-canaries#ci-kubernetes-coverage-unit This can inform certain test coverage improvements that we want to do before extending the production code to implement this enhancement. -->

Not applicable, these are e2e tests.

Integration tests

<!-- Integration tests are contained in https://git.k8s.io/kubernetes/test/integration. Integration tests allow control of the configuration parameters used to start the binaries under test. This is different from e2e tests which do not allow configuration of parameters. Doing this allows testing non-default options and multiple different and potentially conflicting command line options. For more details, see https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/testing-strategy.md If integration tests are not necessary or useful, explain why. --> <!-- This question should be filled when targeting a release. For Alpha, describe what tests will be added to ensure proper quality of the enhancement. For Beta and GA, document that tests have been written, have been executed regularly, and have been stable. This can be done with: - permalinks to the GitHub source code - links to the periodic job (typically https://testgrid.k8s.io/sig-release-master-blocking#integration-master), filtered by the test name - a search in the Kubernetes bug triage tool (https://storage.googleapis.com/k8s-triage/index.html) -->

Not applicable, these are e2e tests.

e2e tests

<!-- This question should be filled when targeting a release. For Alpha, describe what tests will be added to ensure proper quality of the enhancement. For Beta and GA, document that tests have been written, have been executed regularly, and have been stable. This can be done with: - permalinks to the GitHub source code - links to the periodic job (typically a job owned by the SIG responsible for the feature), filtered by the test name - a search in the Kubernetes bug triage tool (https://storage.googleapis.com/k8s-triage/index.html) We expect no non-infra related flakes in the last month as a GA graduation criteria. If e2e tests are not necessary or useful, explain why. -->

TBD: We will need to settle on the tests and names.

To start we will add something to cover the declarative validation metric.

Graduation Criteria

N/A. Alpha/Beta/GA does not apply to a KEP of this nature. This KEP is about decision making around the e2e tests, it does not have any feature-gated changes or user-facing API changes.

<!-- **Note:** *Not required until targeted at a release.* Define graduation milestones. These may be defined in terms of API maturity, [feature gate] graduations, or as something else. The KEP should keep this high-level with a focus on what signals will be looked at to determine graduation. Consider the following in developing the graduation criteria for this enhancement: - [Maturity levels (`alpha`, `beta`, `stable`)][maturity-levels] - [Feature gate][feature gate] lifecycle - [Deprecation policy][deprecation-policy] Clearly define what graduation means by either linking to the [API doc definition](https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning) or by redefining what graduation means. In general we try to use the same stages (alpha, beta, GA), regardless of how the functionality is accessed. [feature gate]: https://git.k8s.io/community/contributors/devel/sig-architecture/feature-gates.md [maturity-levels]: https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions [deprecation-policy]: https://kubernetes.io/docs/reference/using-api/deprecation-policy/ Below are some examples to consider, in addition to the aforementioned [maturity levels][maturity-levels]. #### Alpha - Feature implemented behind a feature flag - Initial e2e tests completed and enabled #### Beta - Gather feedback from developers and surveys - Complete feature