Dennis-Mircea opened a new pull request, #1164:
URL: https://github.com/apache/flink-kubernetes-operator/pull/1164
> **Draft.** The restructure is complete and build-verified end to end, but
the Internals section is still being deepened. See [Draft status and known
gaps](#draft-status-and-known-gaps) and [Follow-ups](#follow-ups). Review of
the information architecture and of the finished sections is already valuable
now.
## What is the purpose of the change
The operator documentation has grown organically and its structure no longer
serves its readers:
- **Concepts is an evaluator trap.** It opens onto internal controller
deep-dives (160 to 325 line developer documents) instead of answering "what
does the operator bring me, why install it".
- **Custom Resource mixes concerns.** The CR structure and reference
material is interleaved with operator capabilities such as job management,
snapshots, and the autoscaler.
- **Operations is a grab-bag.** Install-time concerns (Helm, RBAC,
configuration) sit next to day-2 concerns (metrics, logging, debugging). Flink
core separates these into Deployment and Operations.
- **Two custom resources are barely documented** (`FlinkStateSnapshot`) **or
not at all** (`FlinkBlueGreenDeployment`).
- **There is no contributor tier**, so internal flows leak into user-facing
sections.
This PR restructures the documentation into **audience-layered altitudes**,
following the Flink core documentation convention: the section names, the Try
entry point, and the split of install-time (Deployment) from day-2 (Operations)
concerns all mirror how Flink core organizes its own documentation, so readers
moving between the two find the same structure.
| Altitude | Sections | Question answered
| Audience |
|----------------|--------------------------------------|-----------------------------------------------------------------|---------------------------|
| Why | Concepts | Why does this
exist, what does it buy me | Evaluators |
| How to use | Custom Resource, Managing Flink Jobs | How do I run and
manage Flink jobs with it | Flink users |
| How to operate | Deployment, Operations | How do I install
the operator and keep it healthy in production | DevOps and platform teams |
| How it works | Internals | How is it
implemented inside | Contributors
|
On top of the site layering, every capability is told three times, at three
depths: Concepts for the why, Managing for the how, Internals for the
implementation. For example, snapshots are covered as Concepts → Lifecycle
Management → Snapshots (why), Managing → Snapshot Management (how to use), and
Internals → Controllers (how the observer and reconciler implement it). Each
page links one level down, and every fact has exactly one home with cross-links
instead of duplication.
## The new information architecture
<img width="807" height="802" alt="pr-description-layering"
src="https://github.com/user-attachments/assets/5b4268fe-263d-4c21-85d6-6a710b6332fc";
/>
The numbered bands are the four altitudes from the table above, and the
colors carry through the figure: yellow for evaluating the operator, purple for
using it day to day, red for operating it in production, gray for contributing
to it. The right column shows the resulting sidebar navigation, framed in the
color of the band it renders. Reading top to bottom follows the typical reader
journey, from first contact through production operation to contribution, and
the navigation presents the sections in the same order.
All moved pages keep their old URLs through Hugo aliases, so external links
and search results keep working. The alias redirects render for the English
tree, matching how the site's aliases have always behaved for the Chinese one.
## Brief change log
**Information architecture**
- New top-level sections **Managing Flink Jobs**, **Deployment**, and a
rebuilt **Internals**. Operations is split into install-time (Deployment) and
day-2 (Operations) concerns, matching Flink core.
- Capability pages moved out of Custom Resource into Managing, configuration
and Helm material moved out of Operations into Deployment, with Hugo aliases
preserving every old URL.
**Landing and Try**
- The landing page is rewritten around a Try It Out / Explore the
Documentation / Deploy to Production / Get Help grid.
- The Quick Start is fully rewritten.
**Concepts**
- Overview rebuilt as a capability map with linked deliverables and
capability groups.
- New concept pages for Lifecycle Management, Autoscaling, and Zero-Downtime
Upgrades, plus a rewritten Architecture page and a Glossary.
- The old controller-flow deep-dives moved to Internals where they belong.
**Custom Resource**
- Focused on the CR contract: all four kinds (`FlinkDeployment`,
`FlinkSessionJob`, `FlinkStateSnapshot`, `FlinkBlueGreenDeployment`) now have
walkthrough examples, relationship and ownership rules, and spec-diffing
semantics in one place.
- New **Status and Lifecycle** page: the full status contract with a
lifecycle figure, every status block explained, and a table correlating
`lifecycleState`, `reconciliationStatus`, `jobStatus`, and
`jobManagerDeploymentStatus`.
**Managing Flink Jobs**
- **Job Management**: validation-gated starting, suspending and resuming,
upgrade modes with their snapshot pairing, self-healing (recovery, restarts,
rollbacks), and manual recovery.
- **Snapshot Management**: rebuilt around the `FlinkStateSnapshot` resource
with a state table, lifecycle figure, triggering modes, history, and disposal
semantics.
- **Blue/Green Deployments**: new page for the previously undocumented
`FlinkBlueGreenDeployment` resource, covering deployment states, spec-change
behavior, health monitoring, and abort semantics.
- **Autoscaler** and **Autotuning** heavily reworked and code-verified.
- All capability pages close with the same State / Metrics / Events /
Limitations sections, and limitations are written consequence-first with their
design rationale.
**Deployment**
- New section: deployment modes overview (including the scale subresource in
Standalone mode), Helm subtree (installation, RBAC, cert-manager), operator
configuration (with a new Blue/Green configuration section), security
(including Flink Web UI exposure), high availability (including JobResultStore
cleanup), compatibility, and plugins.
**Operations**
- New **Events** catalog and **State** page (what the operator persists and
where).
- Metrics and logging split into two focused pages, new Debugging subtree
(application profiling, resource exceptions).
**Internals** (work in progress)
- Collapsed 17 files (10 of them stubs) into five substantive pages:
Overview, Startup, Controllers, Webhook, Autoscaler.
- **Controllers** now carries the full depth of the old Concepts
controller-flow pages (observation, validation, reconciliation, status updates,
blue/green state machine), updated against the current implementation rather
than copied.
**Editorial conventions**
- All pages rewritten in an impersonal voice, no "you" or "we", with the
landing page as the single deliberate exception where the welcoming second
person matches the tone of the Flink core landing page.
- Consistent conventions applied throughout: American spelling, title-case
headings, uniform hint boxes, one link-labeling style, and aligned tables.
**Figures**
- New figure set for concepts, managing, and internals pages (architecture,
control loop, lifecycle, autoscaling, admission control, snapshot lifecycle, CR
status and lifecycle, blue/green states, startup layers), drawn in draw.io with
editable sources embedded in the SVGs.
- Legacy class-hierarchy figures kept, the original blue/green state machine
walkthrough restored for Internals.
**Chinese documentation**
- `content.zh` is now a verbatim 1:1 mirror of the English tree. The
previous zh tree had drifted into a mix of stale translations and English text.
A verbatim mirror keeps both trees building, makes the translation debt
explicit, and turns future translation work into a clean per-page diff.
**Code changes (documentation-supporting only)**
- `FlinkBlueGreenDeploymentConfigOptions` consolidated into
`KubernetesOperatorConfigOptions` with a documented `bluegreen` section, so the
Blue/Green options finally appear in the generated configuration reference.
`BlueGreenUtils` and the controller test updated accordingly.
- `CrdReferenceDoclet` exclusion list reduced to the classes that must be
excluded.
- Two user-facing "behaviour" spellings fixed in javadocs, with the
generated config tables and CRD descriptions regenerated. No CRD schema or
field changes.
## Verifying this change
- Build locally with `cd docs && docker run -v $(pwd):/src -p 1313:1313
jakejarvis/hugo-extended:latest server --buildDrafts --buildFuture --bind
0.0.0.0` and browse
`http://localhost:1313/flink/flink-kubernetes-operator-docs-main/`.
- Review the English tree only, `content.zh` mirrors it verbatim by policy.
- Suggested order: landing page → Concepts → Custom Resource → Managing →
Deployment → Operations → Internals, the same path a new user would take.
## Does this pull request potentially affect one of the following parts:
- Dependencies (does it add or upgrade a dependency): no
- The public API, i.e., is any changes to the `CustomResourceDescriptors`:
no
- Core observer or reconciler logic that is regularly executed: no
## Documentation
- Does this pull request introduce a new feature? no
- If yes, how is the feature documented? not applicable
## Draft status and known gaps
The PR stays in draft while the Internals section is completed:
- More Internals depth is planned overall (see follow-ups).
- Two figures await a refresh: the restored blue/green state machine still
shows a FAILING state that no longer exists in `FlinkBlueGreenDeploymentState`
(failed transitions abort back to the previous active state today), and the
RBAC figure content predates the restructure.
- Whether to split this into a commit-per-section PR series will be decided
with the community before undrafting.
**Scope cutoff.** The content documents the operator as merged to `main` at
the time of writing, the branch is rebased onto it. Open PRs that will change
documented behavior are deliberately not pre-documented and will be absorbed
once they land, for example:
- #1163 (FLINK-40195): configurable webhook certificate secret name, which
touches the webhook TLS and Helm pages.
- #1126 (FLINK-39791): honoring `defaultConfiguration.config.yaml` and
always mounting `config.yaml`, which touches the configuration and startup
pages.
## Follow-ups
Planned as a continuation of this work, intentionally out of scope here:
- Enrich **Try Flink Kubernetes Operator** with worked examples and
tutorials.
- Update the **Autotuning** page once the Autotuning Redesign FLIP lands,
its Limitations section doubles as the checklist.
- Possible new pages: **Production Readiness Checklist** and **Command
Cheatsheet**.
- More detail on existing pages, for example concurrency behavior for Flink
session clusters and further Blue/Green deployment coverage.
- More diagrams across the sections.
- More depth in **Internals**.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
