docs: reorganize Doris Operator Kubernetes docs

Author: Al-assad

docs/install/deploy-on-kubernetes/doris-operator/architecture.md

@@ -0,0 +1,70 @@
+---
+{
+    "title": "Doris Operator Architecture",
+    "sidebar_label": "Architecture",
+    "language": "en",
+    "description": "Describes the Doris Operator control plane, data plane, Reconcile model, and control paths for compute-storage integrated and compute-storage decoupled clusters.",
+    "keywords": ["Doris Operator architecture", "Kubernetes Operator", "Reconcile", "DorisCluster", "DorisDisaggregatedCluster"]
+}
+---
+
+Doris Operator follows the standard Kubernetes Operator pattern. Users declare the desired state through CRDs, and the Operator continuously observes actual state and reconciles the difference by creating, updating, or deleting Kubernetes resources.
+
+This document focuses on the overall architecture. For field definitions and deployment procedures, see the corresponding installation and configuration documents.
+
+## Architecture layers
+
+Doris Operator can be viewed as two layers: the control plane and the data plane.
+
+![Doris Operator architecture layers](/images/doris-operator/mermaid/02-architecture-layers.png)
+
+The control plane reads Doris custom resources and executes the Reconcile flow. The data plane is made of native Kubernetes resources that actually run Doris components.
+
+## Reconcile model
+
+The Reconcile loop is the core of Doris Operator. Whenever a Doris custom resource is created or updated, or when related resources change status, the Operator recalculates the difference between desired state and actual state, then performs the necessary operations.
+
+A typical flow is:
+
+1. Read the Doris custom resource.
+2. Check whether the resource is being deleted.
+3. Parse component, storage, authentication, and access configuration.
+4. Create or update the corresponding `StatefulSet`, `Service`, PVC, and related resources.
+5. Aggregate component state and write it into CR `status`.
+6. If the cluster is not ready, wait for the next Reconcile loop.
+
+![Doris Operator reconcile model](/images/doris-operator/mermaid/03-architecture-reconcile-model.png)
+
+## Control path for compute-storage integrated clusters
+
+`DorisCluster` is used for compute-storage integrated deployments. A single resource can include FE, BE, CN, and Broker configuration.
+
+![Control path for compute-storage integrated clusters](/images/doris-operator/mermaid/04-architecture-integrated-control-path.png)
+
+In this path, the main Reconciler is responsible for reading the CR, ordering component actions, cleaning up invalid resources, and aggregating status. Component controllers create and inspect resources for their own components.
+
+## Control path for compute-storage decoupled clusters
+
+`DorisDisaggregatedCluster` is used for compute-storage decoupled deployments. A single resource contains MetaService, FE, and one or more ComputeGroups.
+
+![Control path for compute-storage decoupled clusters](/images/doris-operator/mermaid/05-architecture-decoupled-control-path.png)
+
+Compared with compute-storage integrated mode, this path involves more Doris metadata-level actions. For example, when scaling down a ComputeGroup, the Operator may need to perform decommission or drop actions first, and then update Kubernetes resources.
+
+## Webhook and validation
+
+Doris Operator can optionally enable a Webhook to apply defaults and reject obviously invalid configurations before they enter the Reconcile flow.
+
+Common checks include:
+
+- Whether FE replica and election-related settings are compatible.
+- Whether resource field formats satisfy CRD constraints.
+- Whether component configuration matches models supported by the Operator.
+
+Whether Webhook is enabled depends on the deployment method and environment. Even without Webhook, CRD schema validation and Reconcile status feedback still provide baseline constraints.
+
+## Status aggregation
+
+The Operator does not only create resources. It also writes component state back into the Doris custom resource. You can use `kubectl get` or `kubectl describe` to see whether components are available, scaling, waiting for scheduling, or failing.
+
+For compute-storage integrated clusters, status is aggregated by FE, BE, CN, and Broker. For compute-storage decoupled clusters, status is aggregated by MetaService, FE, and ComputeGroups, with an additional overall health summary.

docs/install/deploy-on-kubernetes/doris-operator/doris-operator-overview.md

@@ -1,31 +1,43 @@
 ---
 {
-    "title": "Pre-deployment Preparation",
+    "title": "Doris Operator Concepts and Capabilities",
     "language": "en",
-    "description": "Manage Apache Doris clusters on Kubernetes with Doris Operator."
+    "description": "Concepts, architecture, resource model, lifecycle, and troubleshooting guidance for Doris Operator."
 }
 ---
 
 import GettingStartedCard from '@site/src/components/getting-started-card/getting-started-card';
 
-Doris Operator is a tool for natively deploying and managing Apache Doris clusters on Kubernetes. Read the overview first, then choose the installation guide that matches your cloud provider.
+Doris Operator is the control plane for deploying and managing Apache Doris on Kubernetes. Read these documents first to understand what the Operator manages, how it works, and how to locate problems through resource status.
 
 <div className="cards-grid">
 <GettingStartedCard
     title="Doris Operator Overview"
-    description="Learn what Doris Operator can do and how it manages Doris on Kubernetes"
+    description="Learn what Doris Operator manages, when to use it, and its capability boundaries"
     link="doris-operator-overview"
 />
 
 <GettingStartedCard
-    title="Deploy on Alibaba Cloud"
-    description="Install Doris Operator on Alibaba Cloud Container Service for Kubernetes (ACK)"
-    link="on-alibaba"
+    title="Architecture"
+    description="Understand the control plane, data plane, and Reconcile model"
+    link="architecture"
 />
 
 <GettingStartedCard
-    title="Deploy on AWS"
-    description="Install Doris Operator on Amazon Elastic Kubernetes Service (EKS)"
-    link="on-aws"
+    title="Resource Model"
+    description="See how Doris custom resources map to StatefulSet, Service, PVC, and other resources"
+    link="resource-model"
+/>
+
+<GettingStartedCard
+    title="Lifecycle Management"
+    description="Understand creation, scaling, configuration changes, and deletion behavior"
+    link="lifecycle"
+/>
+
+<GettingStartedCard
+    title="Status and Troubleshooting"
+    description="Check status fields and follow the recommended troubleshooting path"
+    link="status-and-troubleshooting"
 />
 </div>

docs/install/deploy-on-kubernetes/doris-operator/intro.mdx

@@ -0,0 +1,149 @@
+---
+{
+    "title": "Doris Operator Lifecycle Management",
+    "sidebar_label": "Lifecycle Management",
+    "language": "en",
+    "description": "Explains the main behavior of Doris Operator during cluster creation, scaling, configuration changes, rolling updates, and deletion.",
+    "keywords": ["Doris Operator lifecycle", "scale out", "scale in", "rolling update", "configuration change", "DorisCluster", "DorisDisaggregatedCluster"]
+}
+---
+
+Doris Operator manages Doris clusters through the Reconcile loop. After a Doris custom resource is changed, the Operator updates underlying Kubernetes resources according to the new desired state and, when needed, performs Doris metadata-level actions.
+
+This document explains the operational semantics behind those changes.
+
+## Cluster creation
+
+When you create a `DorisCluster` or `DorisDisaggregatedCluster`, the Operator creates the underlying Kubernetes resources according to the component configuration in the resource.
+
+For compute-storage integrated clusters, FE is usually created first:
+
+![Cluster creation flow for DorisCluster](/images/doris-operator/mermaid/11-lifecycle-doriscluster-creation.png)
+
+For compute-storage decoupled clusters, MetaService is created first:
+
+![Cluster creation flow for DorisDisaggregatedCluster](/images/doris-operator/mermaid/12-lifecycle-decoupled-cluster-creation.png)
+
+If dependencies are not ready, the Operator keeps waiting and retries in later Reconcile loops.
+
+## Scale out
+
+Scaling out is usually done by increasing a component's `replicas` field. For example:
+
+```yaml
+spec:
+  beSpec:
+    replicas: 5
+```
+
+After the Operator detects the change, it updates the corresponding `StatefulSet`. Kubernetes creates the new Pods, and the Operator continues checking readiness and updating CR `status`.
+
+For compute-storage decoupled clusters, scaling out a ComputeGroup is done in the same way:
+
+```yaml
+spec:
+  computeGroups:
+    - uniqueId: adhoc-query
+      replicas: 5
+```
+
+Pay attention to:
+
+- Whether the cluster has enough CPU, memory, and storage.
+- Whether new Pods can be scheduled.
+- Whether PVCs can be bound.
+- Whether new nodes can register with the Doris cluster.
+
+## Scale in
+
+Scale-in is riskier than scale-out because it may affect data replicas, metadata quorum, node roles, or service capacity.
+
+:::caution Caution
+Before scaling in a production cluster, confirm Doris replica status, business traffic, and rollback options.
+:::
+
+### Compute-storage integrated clusters
+
+Scale-in risks differ by component:
+
+| Component | Main concern |
+| --- | --- |
+| FE | Follower and Observer roles can affect metadata quorum |
+| BE | Replica migration and data availability must be considered |
+| CN | No data replicas, but scale-in affects compute capacity and cache |
+| Broker | Check whether external access tasks still depend on it |
+
+For FE, the replica count cannot be lower than the number of election nodes. For scale-in in this mode, evaluate cluster topology and Doris-level risk separately.
+
+### Compute-storage decoupled clusters
+
+When scaling in a ComputeGroup, Doris metadata-level actions may be required. The behavior depends on `enableDecommission`:
+
+| Configuration | Behavior |
+| --- | --- |
+| `enableDecommission: true` | Run decommission before scale-in and wait for safe removal |
+| `enableDecommission: false` | Directly drop the corresponding node |
+
+![ComputeGroup scale-in flow](/images/doris-operator/mermaid/13-lifecycle-computegroup-scale-in.png)
+
+Before scaling in, confirm current data distribution and business traffic.
+
+## Configuration changes
+
+Doris startup configuration is usually mounted through `ConfigMap`. Whether a change requires a restart depends on the configuration type and Operator settings.
+
+For compute-storage integrated clusters:
+
+```yaml
+spec:
+  enableRestartWhenConfigChange: true
+```
+
+When this is enabled, core ConfigMap changes can trigger a rolling restart.
+
+Check the following when changing configuration:
+
+- Whether ConfigMap keys match component requirements, such as `fe.conf`.
+- Whether configured directories match PVC mount paths.
+- Whether ports, FQDN, and authentication settings match the Kubernetes network model.
+- Whether the change takes effect only after component restart.
+
+## Rolling updates
+
+Changing component images, some Pod template fields, or configuration hashes can trigger a StatefulSet rolling update.
+
+Recommended practice:
+
+- Perform the update during off-peak hours.
+- Make sure the cluster has no unresolved failures first.
+- Confirm client retry behavior.
+- Follow Doris version upgrade documentation for upgrade order.
+
+## Cluster deletion
+
+After the Doris custom resource is deleted, the Operator enters cleanup flow and removes Kubernetes resources that it manages.
+
+Before deletion, confirm:
+
+- Whether PVCs should be retained.
+- Whether object storage, FoundationDB, or other external dependencies are shared.
+- Whether data and metadata backups are needed.
+- Whether clients are still connected.
+
+:::caution Caution
+Deleting the CR can remove the corresponding Kubernetes resources. Confirm cleanup scope and backup strategy before proceeding.
+:::
+
+## Observing lifecycle operations
+
+Lifecycle completion should be judged using CR `status`, Kubernetes resource state, and Doris component state together.
+
+```shell
+kubectl get dcr -n ${namespace}
+kubectl describe dcr ${cluster_name} -n ${namespace}
+kubectl get ddc -n ${namespace}
+kubectl describe ddc ${cluster_name} -n ${namespace}
+kubectl get pod,sts,svc,pvc -n ${namespace}
+```
+
+If status does not converge for a long time, continue with Operator logs and Kubernetes Events to determine whether the problem is in scheduling, storage binding, configuration mounting, node registration, or Doris metadata operations.

docs/install/deploy-on-kubernetes/doris-operator/lifecycle.md

@@ -0,0 +1,25 @@
+---
+{
+    "title": "Preparation",
+    "language": "en",
+    "description": "Environment preparation and deployment recommendations before deploying Doris with Doris Operator on cloud Kubernetes services."
+}
+---
+
+import GettingStartedCard from '@site/src/components/getting-started-card/getting-started-card';
+
+Before deploying Apache Doris with Doris Operator, check the Kubernetes service, node system parameters, image registry, storage, and privilege requirements for your cloud environment.
+
+<div className="cards-grid">
+<GettingStartedCard
+    title="Alibaba Cloud Container Service Deployment Recommendations"
+    description="Prepare ACK or ACS before deploying Doris with Doris Operator"
+    link="on-alibaba"
+/>
+
+<GettingStartedCard
+    title="AWS EKS Deployment Recommendations"
+    description="Prepare Amazon EKS before deploying Doris with Doris Operator"
+    link="on-aws"
+/>
+</div>