Treat Kubernetes lifecycle data as a compatibility signal

A generated answer is not a support promise

A generated compatibility record can look authoritative because it is structured, versioned, and easy for tooling to consume. That does not make it a complete support statement. I would use API lifecycle data to identify what needs checking, then reconcile it with the release notes before declaring a Kubernetes version supported.

A recent Kubernetes 1.38 readiness issue makes the distinction concrete. It describes lifecycle data generated from k8s.io/api that already contains entries for APIs marked as removed in 1.38, while the knowledge base still identifies 1.37 as its newest known version. The issue also notes that the 1.38 release notes are not yet available to verify those entries. That is a useful early signal, but it is not enough evidence to call the data confirmed compatibility information.

This is a general data-design problem, not a claim that the generated records are wrong. Derived data can be valuable and still be provisional. If a downstream tool quietly treats every generated row as confirmed, it can turn an upstream signal into a stronger promise than its evidence supports. A platform support matrix is not merely a convenient view of source data; it is a statement that people may rely on when planning upgrades.

I am still learning the deeper mechanics of Kubernetes releases, so I would not present this as authoritative guidance on the release process. The design lesson seems clear without that expertise: distinguish what a source suggests from what the product has verified.

Keep evidence and status together

I would model compatibility as a record with provenance, not as a bare version-to-answer mapping. The entry needs to say where its claim came from, what it has been checked against, and whether it is ready to influence a user-facing support decision.

For example, a small record might look like this:

kubernetesVersion: "1.38"
apiLifecycleSource: "k8s.io/api"
status: provisional
releaseNotesChecked: false
verifiedSources: []

This is illustrative, not a prescribed Kubernetes format. The important part is that status and releaseNotesChecked are explicit fields rather than assumptions hidden in the generation process. If the record is rebuilt from a newer dependency, the build should not silently upgrade its status from provisional to confirmed. Verification is a separate act with separate evidence.

I would also keep the generated fact distinct from the product decision. A lifecycle record can say that an API is associated with a removal version. The compatibility check can then report that the version needs review. The platform’s support matrix should change only when the relevant evidence has been reviewed and the resulting policy decision is recorded.

That separation makes disagreement visible. If generated data and release notes differ, a reviewer sees a discrepancy to resolve instead of a single overwritten value. If the release notes do not yet exist, the system can still expose the early signal while accurately communicating its provisional status. Missing confirmation becomes useful information rather than an awkward hole in an apparently final answer.

Make the check part of the workflow

I would make the reconciliation a gate in the data pipeline, not a reminder in someone’s memory. Generation can happen early and often. Promotion to confirmed should require a deliberate review of the relevant release material, with the evidence stored alongside the result.

A useful sequence is: generate the lifecycle data, mark new-version entries provisional, compare those entries with the release notes when they are available, record any differences, and then decide whether the support matrix can advance. The Kubernetes 1.38 release schedule provides milestones for that cycle, including the planned release date. The schedule is a planning input; the version’s actual release notes remain the evidence to check before making a confirmed claim.

I would want the system to make the workflow visible in its output. A provisional result should say that lifecycle data exists but has not been reconciled with release notes. A confirmed result should point to the reviewed source and record when the check occurred. If the check finds a mismatch, the result should be blocked or flagged for review rather than choosing whichever source happens to be easiest to parse.

That can be represented as a small promotion rule:

compatibilityDecision:
  provisionalWhen:
    - lifecycleDataAvailable
    - releaseNotesNotChecked
  confirmedWhen:
    - lifecycleDataAvailable
    - releaseNotesChecked
    - discrepanciesResolved

The rule is deliberately conservative. It does not say that release notes alone determine every part of platform support. A support promise can depend on testing, provider behavior, add-ons, or an organization’s own policy. It says only that generated lifecycle data should not become a confirmed compatibility claim before it has passed the check the team chose to require.

Make uncertainty legible to users

A compatibility tool that only returns supported or unsupported forces uncertain evidence into a false binary. I would rather expose a small vocabulary such as provisional, confirmed, and needs review, with a short explanation of what is missing. That gives an operator a practical next step without pretending the system knows more than it does.

This distinction matters most when people use the output to plan upgrades. A provisional warning can prompt someone to investigate early. A confirmed warning can support a stronger decision. If both are displayed identically, users cannot tell whether they are seeing a verified change or a prediction based on incomplete evidence. The tool has then hidden the most important fact about its own answer: how much confidence the operator should place in it.

The official Kubernetes deprecated API migration guide is organized around APIs removed by release and provides migration information. That kind of release-oriented reference is a useful check against a derived dataset, but the underlying principle applies beyond Kubernetes: a generated index helps find relevant facts; it does not automatically inherit the authority of every source needed to make a support decision.

I would keep the distinction visible in both the stored data and the user interface. Let generated lifecycle data raise the question. Let a recorded review answer it. Until then, label the result provisional.