gen-apidocs Markdown backend omits ContainerStatus from the Pod API reference

[qiujiaro]

Problem

The gen-apidocs Markdown backend omits the ContainerStatus definition from the generated Pod API reference.

The OpenAPI input contains the complete io.k8s.api.core.v1.ContainerStatus definition, and PodStatus references it through:

• containerStatuses
• initContainerStatuses
• ephemeralContainerStatuses

However, the generated core/pod-v1.md only displays the unlinked type ContainerStatus array.

The generated Markdown contains neither:

• a ## ContainerStatus section in pod-v1.md; nor
• a standalone ContainerStatus page under definitions/.

As a result, the ContainerStatus schema and its fields are not reachable from the generated Markdown API reference.

Steps to reproduce

1. Clone kubernetes-sigs/reference-docs and check out master.

2. Generate the Kubernetes 1.36 Markdown API reference:

export K8S_RELEASE=1.36.0
make apimd

3. Confirm that the OpenAPI input contains ContainerStatus:

rg -n '"io.k8s.api.core.v1.ContainerStatus"' \
  gen-apidocs/config/v1_36/swagger.json

The complete definition is present.

4. Confirm that the generated Pod page references the type:

rg -n 'ContainerStatus array' \
  gen-apidocs/build/markdown/core/pod-v1.md

This finds containerStatuses, initContainerStatuses, and ephemeralContainerStatuses.

5. Search for a generated ContainerStatus section:

rg -n '^## ContainerStatus ' \
  gen-apidocs/build/markdown/core/pod-v1.md

This produces no output and exits with status 1.

6. Check for a standalone definition page:

find gen-apidocs/build/markdown \
  -iname '*container-status*'

This also produces no output.

Actual behavior

The generated Pod status fields contain an unlinked type:

ContainerStatus array

No ContainerStatus definition is emitted anywhere in the Markdown output.

Expected behavior

ContainerStatus should be generated and reachable from the Pod API reference, either as a section in pod-v1.md or as a linked standalone definition.

Environment

• Repository: kubernetes-sigs/reference-docs
• Branch: master
• Backend: markdown
• Kubernetes release: 1.36.0
• Commit: <output of git rev-parse HEAD>

Related issues

• ContainerStatus not defined in Pod defn kubernetes/website#56427
• Fix ContainerStatus section in Pod API reference kubernetes/website#56463

The website issue reports the user-visible symptom, and #56463 attempted to address the generated page directly. This issue tracks the behavior reproduced using the current gen-apidocs Markdown backend.

I'm interested in working on a fix and adding a regression test.

[qiujiaro]

Additional impact

This does not appear to be specific to ContainerStatus.

While investigating the definition classification behavior, I found several other definitions that are also omitted by the same class of inline-definition naming rules, including:

• RollingUpdateDaemonSet
• DeploymentStrategy
• RollingUpdateDeployment
• PodResourceClaimStatus
• VolumeMountStatus
• VolumeStatus
• PodGroupResourceClaimStatus

These definitions match generic inline naming patterns such as ${resource}Status, ${resource}Strategy, or RollingUpdate${resource}, but they are not necessarily definitions that should disappear from the generated Markdown reference.

A classification fix restores these definitions in addition to ContainerStatus, suggesting that the missing ContainerStatus documentation is one instance of a broader definition-classification issue rather than a Pod-specific rendering problem.