[jira] [Resolved] (FLINK-39571) Improve Flink Kubernetes Operator documentation coverage

["Dennis-Mircea Ciupitu (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/FLINK-39571?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Dennis-Mircea Ciupitu resolved FLINK-39571.
-------------------------------------------
    Resolution: Fixed

> Improve Flink Kubernetes Operator documentation coverage
> --------------------------------------------------------
>
>                 Key: FLINK-39571
>                 URL: https://issues.apache.org/jira/browse/FLINK-39571
>             Project: Flink
>          Issue Type: Improvement
>          Components: Kubernetes Operator
>            Reporter: Dennis-Mircea Ciupitu
>            Assignee: Dennis-Mircea Ciupitu
>            Priority: Major
>              Labels: pull-request-available
>             Fix For: kubernetes-operator-1.16.0
>
>
> h2. Motivation
> The Flink Kubernetes Operator is production-ready and widely deployed, but its documentation has not kept pace, both in coverage and in structure:
>  * *Concepts is an internals trap:* The section opens with controller deep-dives aimed at contributors, instead of answering the evaluator's question: "what does the operator bring me, why should I install it?"
>  * *Custom Resource mixes concerns:* CR structure/spec/reference pages are interleaved with operator capabilities (job management, snapshots, autoscaler).
>  * *Operations is a grab-bag:* Install-time concerns (Helm, RBAC, configuration) sit next to day-2 concerns (metrics, upgrades, debugging), while Flink core deliberately separates Deployment from Operations.
>  * *Coverage gaps:* Two custom resources are barely documented (FlinkStateSnapshot) or not at all (FlinkBlueGreenDeployment), and operational topics critical for production (operator state, event taxonomy, high availability, debugging, security) require reading source code today.
> h2. Goal
> Restructure the operator documentation into a layered, navigable tree aligned with the Flink core documentation conventions, and fill the coverage gaps as part of the same effort. The guiding principles:
>  * *Three altitudes per capability:* _Concepts_ explain why a capability exists and what it buys you (no config keys), the management pages explain how to enable and configure it, _Internals_ explain how it works inside. Example vertical: Concepts > Autoscaling -> Managing Flink Jobs > Autoscaler -> Internals > Autoscaler Flow.
>  * *Clear separation* between CR structure (spec/status/reference) and the operator functionality applied on the CRs.
>  * *Flink core alignment* wherever an analogous concern exists (Deployment vs Operations split, Configuration/HA/Security under Deployment, Debugging under Operations, Concepts Glossary), with deliberate deviations where the operator differs (CR sections instead of Application Development, a kubectl/helm Command Cheatsheet instead of a CLI page).
>  * *No stubs:* a navigation entry only appears once real content exists behind it.
>  * *URL stability:* every moved or renamed page keeps its old paths via aliases.
> h2. Target structure
> * *Try Flink Kubernetes Operator*
> ** Quick Start
> * *Concepts*
> ** Overview
> ** Architecture
> ** Lifecycle Management
> ** Zero-Downtime Upgrades
> ** Autoscaling
> ** Glossary
> * *Custom Resource*
> ** Overview
> ** Pod Template
> ** Ingress
> ** Status and Lifecycle
> ** Reference
> * *Managing Flink Jobs*
> ** Job Management
> ** Snapshot Management
> ** Blue/Green Deployments
> ** Autoscaler
> ** Autotuning
> * *Deployment*
> ** Overview
> ** Compatibility
> ** Helm
> *** RBAC
> *** Cert Manager
> ** Configuration
> ** High Availability
> ** Plugins
> ** Command Cheatsheet
> ** Security (gated until written)
> * *Operations*
> ** Operator State
> ** Metrics
> ** Logging
> ** Events
> ** Debugging
> *** Resource Exceptions
> *** Application Profiling & Debugging
> ** Monitoring the Operator
> ** Upgrading the Operator
> * *Development*
> ** Guide
> ** Importing the Operator into an IDE (gated until written)
> ** Roadmap
> * *Internals*
> ** Overview
> ** Startup Flow
> ** Reconciliation Flow
> ** Autoscaler Flow
> ** Webhook Flow
> The sections form four visual groups, mirroring the Flink core navigation: learn (Try, Concepts), use the custom resources (Custom Resource, Managing Flink Jobs), run the operator (Deployment, Operations), contribute (Development, Internals).
> This absorbs and supersedes the originally proposed scope: the six new pages (state, events, high availability, security, debugging, plus monitoring) all exist in the tree above, now in their structurally correct homes, alongside new pages for the previously undocumented capabilities (FlinkStateSnapshot via Snapshot Management and Status and Lifecycle, FlinkBlueGreenDeployment via Zero-Downtime Upgrades and Blue/Green Deployments).



--
This message was sent by Atlassian Jira
(v8.20.10#820010)