[
https://issues.apache.org/jira/browse/FLINK-39571?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Dennis-Mircea Ciupitu updated FLINK-39571:
------------------------------------------
Affects Version/s: (was: kubernetes-operator-1.14.0)
> 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
> 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)
