k8s-conformance: how a Kubernetes distribution earns the CNCF Certified mark

A repository of evidence, not a test suite to run

The first thing to get straight is what this repository is. It is not the conformance test suite, and it is not a tool you point at your cluster. It is the place where the evidence lives, and the process by which a vendor asks the CNCF to certify its Kubernetes distribution.

The README opens with the invitation: eligible vendors are invited to submit conformance testing results for review and certification by the CNCF, and if your company provides software based on Kubernetes, you are encouraged to get certified. The programme page is cncf.io/ck, and the certification requirements plus technical instructions are in the terms-conditions and instructions files at the repository root.

Who this is for falls into two groups. The first is the vendor side, which is the primary audience: a company that sells a Kubernetes distribution, an orchestrator built on Kubernetes, or a managed platform, and wants the Certified Kubernetes mark to remove procurement friction. The second group reads the repository rather than writes to it, and that is engineers and buyers who want to know which distributions have been certified and against which Kubernetes release. The per-release directories are the mechanism for that, with one directory per Kubernetes version from v1.24 through v1.37 in the tree.

The repository is Apache-2.0 licensed, the default branch is master, it is not archived, and the last push was on 2026-10-22. The primary language is Shell, which fits a repository whose content is mostly documents, test logs and XML rather than code.

One structural note matters for anyone browsing it. Older conformance files were moved out to a separate archive repository, cncf/k8s-conformance-archive, in an effort described as optimising repository size and improving navigation. The CNCF published a blog post on the tidy-up in January 2024. So a missing v1.20 directory is a relocation, not a deletion, and the history is still reachable elsewhere.

Two test runners, two artefacts, one pull request

The submission mechanics are described in the README's Run the tests section, and they are specific enough to be useful.

The submission requires four files, two of which have to be generated by one of two applications. The first is Sonobuoy, which the README says has been used for a number of years to generate both of the key artefacts, the e2e.log file and the junit_01.xml file. The second is Hydrophone, described as a lightweight runner for Kubernetes tests. Hydrophone uses the conformance images released by the Kubernetes release team, either to run individual tests or to run the entire Conformance suite. The README points at the Hydrophone project README for how to use it.

The choice between the two is a practical one rather than a philosophical one. Sonobuoy is the established path and the one the instructions in the repository were written around, and the README says to follow instructions.md for it. Hydrophone is the lighter option, and it is the one that works directly against the release team's published images, which is convenient when you are chasing a specific Kubernetes version.

The output of that run then becomes a pull request. The PR instructions live at instructions.md under a section on the contents of the PR, and before any human looks at it, the submission has to pass a series of automated checks performed by the verify conformance bot, hosted in the cncf-infra organisation. The bot checks several scenarios and updates the pull request with the results, which the README describes as providing timely feedback and reducing the time the CNCF needs to confirm the PR meets policy requirements.

That bot step is the part people underestimate. A submission is not simply a pull request, it is a pull request that has to satisfy an automated policy check first, and the review queue at the CNCF is behind that gate rather than in front of it.

Who decides what conformance means, and where the boundaries are

The conformance test suite itself is not in this repository, and understanding where it lives matters for anyone deciding what a certification actually asserts.

The README points to kubernetes/community and the sig-architecture working group, described as reviewing, approving and driving changes to the conformance test suite, reviewing and guiding new conformance profiles, and creating new ones. The actual test definitions live in the Kubernetes repository itself, in a conformance.yaml file, and the group publishes guidance on conformance testing in the community repository.

The division of labour runs like this. sig-architecture owns the definition of what conformant means and curates the test list. The Kubernetes release team publishes the images that run those tests. The k8s-conformance repository holds the evidence and the review, and the per-release directories record which tests each release required. APISnoop appears as a related tool that tracks testing and conformance coverage by analysing the audit logs created by e2e test runs, which is useful for understanding coverage rather than for producing a submission.

The limit of all this is worth stating plainly. A conformance run tells you that a distribution implements the behaviours the test suite asserts. It does not tell you that the distribution is well operated, that its defaults are sensible in production, or that its documentation is any good. Certification is a floor, not a ceiling, and the README's own framing of it, a list of tests required for a release of Kubernetes to be conformant, is deliberately narrow.

A second limit is timing. The required test list moves with each Kubernetes release, so a certification is against a version. The repository's per-release directories are how you find the list for the version you are targeting, and the README is clear that each release document contains the list of conformance tests required for that release.

What the review process adds over a green test run

A passing test run is necessary but it is not the submission. The README's PR Submit section and the reviewing.md file at the repository root describe what happens around the pull request.

The process is layered. There is the automated check by the verify conformance bot, which confirms the pull request satisfies the mechanical requirements. Then there is a human review by the CNCF against the policy requirements, and the bot's role is to make sure that review starts from a submission that already passes. The reviewing.md file is where the review expectations are written down, and the participation-form directory in the repository tree suggests there is also a signed participation step that precedes submission.

The terms-conditions directory carries the contractual side. The Certified_Kubernetes_Terms.md file is the certification requirements document that the Prepare section points you to, and the README's advice to learn about the certification requirements and technical instructions before preparing a product is aimed at exactly the failure mode where a team runs the tests, gets them passing, and then discovers the paperwork was the harder half.

For the reader who is not a vendor, the value of the process is different but just as concrete. A pull request in this repository is a public record that a named distribution passed a named test list against a named Kubernetes version, and the review is what makes it a record rather than a claim. The reviewing.md file is worth reading on that basis, since it tells you what the CNCF is actually looking at when it says a submission is acceptable.

One documentation gap is worth flagging. The README does not state how long review takes, nor does it describe what happens to a submission that fails the bot checks beyond the general promise of timely feedback. If your certification is on a customer deadline, that timeline question is worth asking the CNCF directly rather than assuming.

Staying conformant after the badge is issued

Certification is a point event, and the repository's structure is a reminder of what comes after it.

The per-release directories from v1.24 to v1.37 are the current record, and they show a rolling window rather than a static set. Every new Kubernetes release means a new test list, which means a new certification cycle for a distribution that wants to keep the mark against the current version. The README's Conformance Tests per Release section exists for that reason, to help the community understand the range of tests required for a release to be conformant.

Two other things in the tree help with the ongoing work. The docs/ directory at the root holds additional documentation, and hack/ holds the scripts the project uses for its own automation, which is the expected shape for a repository whose primary language is Shell.

For an engineer choosing a distribution, the practical reading of the per-release directories is this: a certification tells you what was tested, and the release directory tells you how much of the current test list the certification covered. A distribution certified against an older Kubernetes release will have been tested against an older list, and the newer directories show what was added since.

The FAQ file at the repository root is where the cost and eligibility questions live, including a section on what the cost of certification is, and the README links directly to that anchor. The participation-form directory suggests the commercial side of the arrangement is formalised rather than implied, which is what you would expect from a programme run by a foundation on behalf of vendors.

Editorial conclusion

k8s-conformance is the right starting point for a vendor preparing a CNCF Certified Kubernetes submission, because it names the two artifacts the review expects, points at the bot that checks them mechanically, and keeps one directory per Kubernetes release so the required test list is explicit. It is not a test suite you can run against your own cluster and it is not a substitute for the sig-architecture conformance definition, which decides what the tests actually assert, and it will not tell you whether a given distribution is certified without checking the per-release directory. Before you start, read instructions.md and the terms-conditions directory in the repository root, confirm with the CNCF that your Kubernetes version has a conformance release document here, and budget for a pull request that must pass the verify conformance bot before a human reviews it.

Frequently asked questions

Official sources

1. cncf/k8s-conformance on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README