docs(core-concepts): write the S3, pod placement and pod disruption pages

[whg517]

Summary

First batch of stage 2 — filling in placeholder pages. Three pages, both language trees, six files. pod-placement.md and pod-disruptions.md were literally 0 bytes; s3.md was a single heading.

Everything here is taken from the operator source in the sibling repositories, not written from memory. Sources are named per page below.

Pages

core-concepts/resources/s3.md

From operator-go: pkg/apis/s3/v1alpha1 (the two CRDs and their defaults), pkg/s3/resolver.go (inline/reference resolution and endpoint assembly), pkg/s3/credentials.go (secret key names). Product example from hive-operator's ClusterConfigSpec.

Covers S3Connection and S3Bucket, the inline-or-reference rule with its actual error strings, the ACCESS_KEY/SECRET_KEY contract and the /kubedoop/secret/<volume>/ mount, TLS verification modes, and region.

pathStyle gets its own section. It defaults to false, which is right for AWS and wrong for MinIO and Ceph RGW, and nothing rejects the wrong value at admission — the resource applies, the pods start, and it fails on first object access.

core-concepts/operations/pod-disruptions.md

From commons/v1alpha1/pdb_types.go and cluster_types.go.

The operator writes a PDB per role by default, so the page leads with "you are already protected". Documents that enabled is a pointer whose unset state means true (a role naming the block only to raise maxUnavailable keeps its PDB), that maxUnavailable defaults per product rather than to a fixed number, that roleConfig is role-scoped and role groups cannot override it, and that a PDB constrains voluntary disruptions only.

core-concepts/operations/pod-placement.md

From commons/v1alpha1/config_types.go and the reconciler's affinity fold (config_fold.go, generic_reconciler.go).

The load-bearing point: config.affinity replaces the layer beneath it wholesale rather than merging per member. Pinning a group with a nodeAffinity therefore discards the podAntiAffinity the product ships to spread a quorum — and nothing fails when it does, since the spec is valid and every status condition stays green.

The page names the three layers in the reconciler's own words, quotes the AffinityOverridden warning event, gives the kubectl command to find it, and shows how to restate the discarded member.

Testing

• npm run verify exits 0 — 52 files linted with 0 errors, both locales built
• All six pages render in both locales (spot-checked pathStyle, AffinityOverridden, maxUnavailable in the build output)
• Relative links resolve — onBrokenLinks: 'throw' would have failed the build otherwise
• en/zh trees still mirror 1:1

Not included, and why

core-concepts/resources/database.md stays a placeholder. DatabaseConnection exists in operator-go (pkg/apis/database/v1alpha1), but grepping hive-operator, superset-operator, airflow-operator and dolphinscheduler-operator finds no operator consuming it, the credential key names are not defined anywhere the way S3's ACCESS_KEY/SECRET_KEY are, and there are no default ports per driver. Documenting it now would mean inventing the user-facing contract. Better as a placeholder until an operator adopts it.

Remaining stage 2 placeholders

10 pages left: authentication, logging, service-discovery, kubernetes, kubebuilder, develop-guideline, faq, release-notes, spark-k8s-operator, and database (blocked above). authentication and logging look similarly well-grounded — trino-operator uses AuthenticationClass with static/LDAP/OIDC backends, and hive-operator and trino-operator both use the logging spec.

🤖 Generated with Claude Code