New nav (#152)

* Reworked the navigation to reflect the learning path
* Reworked the architecture section

Author: nastena1606

docs/architecture.md

@@ -1,109 +1,71 @@
-# Design overview
+# Architecture
 
-The Percona Operator for MySQL automates deploying and operating
-open source MySQL clusters on Kubernetes.
+Percona Operator for MySQL automates deploying and operating Percona Server for MySQL clusters on Kubernetes. This document explains what components the Operator uses and how they work together to provide a highly available MySQL database. Also, read more about [How the Operator works](how-it-works.md).
 
-Containers deployed with the Operator include the following components:
+## Components
 
-* [Percona Server for MySQL :octicons-link-external-16:](https://www.percona.com/doc/percona-server/LATEST/index.html) - a free, fully compatible, enhanced, and open source drop-in replacement for any MySQL database,
+The [StatefulSet :octicons-link-external-16:](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) deployed with the Operator includes the following components:
 
-* [Percona XtraBackup :octicons-link-external-16:](https://www.percona.com/doc/percona-xtrabackup/8.0/index.html) - a hot backup utility for MySQL based servers that doesn’t lock your database during the backup,
+* [Percona Server for MySQL :octicons-link-external-16:](https://www.percona.com/doc/percona-server/LATEST/index.html) - a free, fully compatible, enhanced, and open source drop-in replacement for any MySQL database
 
-* [Orchestrator :octicons-link-external-16:](https://github.com/openark/orchestrator) - a replication topology manager for MySQL used when [asynchronous replication :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication-primary-secondary-replication.html) between MySQL instances [is turned on](operator.md#mysqlclustertype),
-
-* [HAProxy :octicons-link-external-16:](https://haproxy.org) - a load balancing and proxy service compatible with both [asynchronous replication :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication-primary-secondary-replication.html) and [group replication :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication.html)  between MySQL instances,
-
-* [MySQL Router :octicons-link-external-16:](https://dev.mysql.com/doc/mysql-router/8.0/en/) - a proxy solution which can be used instead of HAProxy when [group replication :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication.html) between MySQL instances [is turned on](operator.md#mysqlclustertype),
-
-* [Percona Toolkit :octicons-link-external-16:](https://docs.percona.com/percona-toolkit/) - a set of tools useful in debugging MySQL Pods.
+* [Percona XtraBackup :octicons-link-external-16:](https://www.percona.com/doc/percona-xtrabackup/8.0/index.html) - a hot backup utility for MySQL based servers that doesn’t lock your database during the backup
 
-The Operator architecture builds on Percona Server for MySQL. For asynchronous
-replication, it leverages Orchestrator to manage topology and failover,
-as illustrated below.
-
-![image](assets/images/replication.svg)
+* [Orchestrator :octicons-link-external-16:](https://github.com/openark/orchestrator) - a replication topology manager for MySQL used when [asynchronous replication :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication-primary-secondary-replication.html) between MySQL instances [is turned on](operator.md#mysqlclustertype),
 
-Being a regular MySQL Server instance, each node contains the same set
-of data synchronized across nodes. The recommended configuration is to
-have at least 3 nodes. In a basic setup with this amount of nodes,
-Percona Server for MySQL provides high availability, continuing to
-function if you take any of the nodes down.
+* [HAProxy :octicons-link-external-16:](https://haproxy.org) - a proxy and load balancing  service serving as the entry point to your database cluster. It is compatible with both [asynchronous replication :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication-primary-secondary-replication.html) and [group replication :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication.html)  between MySQL instances,
 
-## High availability
+* [MySQL Router :octicons-link-external-16:](https://dev.mysql.com/doc/mysql-router/8.0/en/) - a proxy solution which can be used instead of HAProxy for MySQL clusters with [group replication :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication.html) is turned on,
 
-To provide high availability, the Operator uses [node-affinity :octicons-link-external-16:](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity)
-to run Percona Server for MySQL instances on separate worker nodes when possible. If
-some node fails, Kubernetes reschedules the affected Pod on another node. With asynchronous
-replication, Orchestrator handles primary election and topology recovery. 
+* [Percona Toolkit :octicons-link-external-16:](https://docs.percona.com/percona-toolkit/) - a set of tools for debugging MySQL Pods.
 
-![image](assets/images/operator.svg)
+It can also include sidecar containers such as PMM Client or your custom ones. This depends on how you further fine-tune your cluster. Learn more about [sidecar containers](sidecar.md).
 
-With Group
-Replication, recovery is coordinated by the group membership protocol. 
 
-![image](assets/images/operator-GR.svg)
+## Replication types
 
-Clients connect
-via HAProxy or MySQL Router to reach a healthy writer/reader instance.
+Each MySQL node in your cluster contains a complete copy of your data, replicated across all nodes.
 
-## How the Operator works
+The Operator supports two replication types, each with different characteristics for performance, consistency, and availability. You [choose the replication type](operator.md#mysqlclustertype) when configuring your cluster.
 
-The Operator extends the Kubernetes API with a special `PerconaServerMySQL` object. It's a Go application that watches for events on these objects. Each `PerconaServerMySQL` object maps to one separate MySQL setup.
+### Asynchronous replication (Beta)
 
-When you create, change, or delete a `PerconaServerMySQL` object, the Operator automatically creates or updates the necessary Kubernetes resources, like Pods and StatefulSets, to ensure your database cluster matches the desired state.
+With asynchronous replication, writes complete on the primary instance without waiting for replicas. After a write completes, the primary records the change in its binary log, and replicas apply these changes independently.
 
-For storage, the Operator leverages Persistent Volumes (PVs) and PersistentVolumeClaims (PVCs) to ensure your data is durable. A *PersistentVolumeClaim* (PVC) is used to implement
-the automatic storage provisioning to pods. The Container Storage Interface (CSI) allows the storage to be re-mounted on a different node if a failure occurs.
+**Characteristics:**
 
-## Replication types and proxy solutions
+* **Performance** - Asynchronous replication provides faster write operations with lower latency.
+* **Read scaling** - You can distribute application read requests to different replica instances, improving read throughput.
+* **Consistency** - Eventual consistency: replicas may lag behind the primary instance, which can affect applications requiring real-time data. There is a risk that some transactions committed on the primary may be lost if it fails before replicas catch up.
+* **Write scaling** - Does not allow for horizontal write scaling; scaling writes relies on vertical scaling, which is increasing the resources (RAM, CPU) of the primary instance, rather than on adding more write nodes.
+* **Failover** - Orchestrator handles automatic primary election and replication topology recovery.
+* **Status** - Currently in Beta and not recommended for production use.
 
-The process in which data from a *primary* MySQL instance is copied and sent to
-other MySQL instances of the database cluster (so-called *replicas*) is known as
-*MySQL replication*.
+### Group replication
 
-The Operator [provides you a choice](operator.md#mysqlclustertype) between two
-replication types:
+With group replication, write transactions require consensus from the group before completing. Read transactions can execute on any instance, while writes only occur on the primary.
 
-* **Asynchronous replication** means that a write is completed on the
-    primary and is not influenced by the replicas themselves. After completion
-    of its changes, the primary populates the binary log with the data
-    modification or the actual statement. Then the replica executes each change
-    on its own database and obtains consistent set of data.
+**Characteristics:**
 
-* **Group Replication** means that a read transaction can be executed on any
-    instance, while write transactions happen only on primary. For a write transaction, MySQL tries to get consensus with the other
-    instances before returning it completed back to the client.
+* **Consistency** – Provides strong consistency, and when set to a high transaction consistency level, helps prevent stale reads.
+* **Read scaling** – Enables horizontal scaling of reads without stale reads when set with a high transaction consistency level.
+* **Performance** – Write operations are slower than asynchronous replication due to the group consensus mechanism.
+* **Failover** – Built-in native group membership protocol automatically handles member recovery and primary election.
+* **Limitations** – Group replication limits the cluster to a maximum of 9 MySQL instances per group. Large transactions can noticeably slow down the system, and especially large transactions may even trigger a replication member fault if the transaction message cannot be copied between group members within a 5-second network window.
+* **Status** – General Availability (GA) and recommended for production use.
 
-Both replication types have their pros and cons.
+!!! note
 
-*Asynchronous replication* is faster. Also, you can distribute read
-requests of your application to different instances. On the other hand, it can
-be less reliable in terms of consistency: replicas may lag behind the primary
-instance, impacting any applications that depend on real-time data. Also, some
-transaction committed on the primary instance may not be available on replicas
-if the primary fails. Finally, asynchronous replication doesn't allow you
-scaling write requests horizontally, leaving vertical scaling (primary
-instance RAM and CPU increase) as the only available option.
+    MySQL documentation may also use the terms "source/replica" instead of "primary/replica".
 
-*Group replication* allows horizontal scaling of reads, preventing stale reads when set with high transaction consistency level, but it is slower. Group replication has some
-[specific limitations :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication-limitations.html).
-Particularly, the number of MySQL instances in a single replication group can't
-exceed 9. Also, extra large transactions can cause noticeable system slowdown,
-and in some cases even can cause the [replication member fault :octicons-link-external-16:](https://dev.mysql.com/doc/refman/8.0/en/group-replication-limitations.html#group-replication-limitations-transaction-size)
-when transaction message cannot be copied between group members over the
-network within a 5-second window.
+## Proxy solutions
 
-!!! note
+The proxy you use depends on your replication type and requirements:
 
-    MySQL documentation may also use the terms "source/replica" instead of
-    "primary/replica".
+* **HAProxy** - Works with both asynchronous replication and group replication. Provides load balancing, health checks, and connection pooling.
 
-Proxy solution used by the Operator for the database cluster depends on the
-replication type used in the cluster. [HAProxy](haproxy-conf.md) can be used
-with both replication types, while [MySQL Router](router-conf.md) can be used
-with Group Replication.
+* **MySQL Router** - Available only for group replication. Offers intelligent routing, connection pooling, and read-write splitting capabilities.
 
-### Replication and proxy comparison
+### Replication type and proxy comparison
 
 | Feature | Asynchronous replication + HAProxy | Group Replication + HAProxy/MySQL Router |
 | --- | --- | --- |
@@ -116,15 +78,47 @@ with Group Replication.
 | Max nodes | Higher (practical limits) | 9 per group |
 | Proxy | HAProxy | HAProxy or MySQL Router |
 
-Tip: Choose Group Replication for stronger consistency and read scaling; choose
-asynchronous replication for lower write latency and simpler topology.
+**Tip:** Choose Group Replication for stronger consistency and read scaling; choose asynchronous replication for lower write latency and simpler topology when it reaches GA status.
 
 You can change the replication type if needed. Refer to the [Change replication type](change-replication-type.md) guide for step-by-step instructions. Note that replication type change is not supported on a running cluster.
 
-### What to read next
+## High availability
+
+The Operator provides high availability through multiple layers of protection:
+
+### Pod distribution
+
+The Operator uses [node affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) to distribute Percona Server for MySQL instances across separate worker nodes when possible. This prevents a single node failure from taking down multiple database instances.
+
+### Automatic recovery
+
+If a node fails, Kubernetes automatically reschedules the affected Pod on another healthy node. Inside your cluster, automatic recovery is handled as follows:
+
+* In **asynchronous replication** clusters, the Orchestrator detects the failure, promotes a healthy replica to primary, and updates the replication topology.
+   
+   ![image](assets/images/operator.svg)
+
+
+* In **group replication** clusters, the native group membership protocol automatically handles member removal, primary election, and topology recovery.
+
+   ![image](assets/images/operator-GR.svg)
+
+### Client connectivity
+
+Clients connect through HAProxy or MySQL Router, which automatically route traffic to healthy MySQL instances. These proxies detect failures and redirect connections away from failed nodes, ensuring your applications always connect to available database instances.
+
+For configuration details, see:
 
-* [Operator configuration and Custom Resources](operator.md)
 * [HAProxy configuration](haproxy-conf.md)
 * [MySQL Router configuration](router-conf.md)
-* [Backups](backups.md)
-* [Updating and upgrades](update.md)
+
+
+## What to read next
+
+Now that you understand the architecture, explore these topics:
+
+* [Operator configuration and Custom Resources](operator.md) - Learn how to configure your cluster
+* [Backups](backups.md) - Understand backup and restore operations
+* [Scaling](scaling.md) - Scale your cluster horizontally or vertically
+* [High availability configuration](constraints.md) - Configure anti-affinity and pod distribution
+* [Updating and upgrades](update.md) - Keep your cluster up to date

docs/constraints.md

@@ -1,4 +1,4 @@
-# Binding Distribution for MySQL components to Specific Kubernetes Nodes
+# Control Pod scheduling on specific Kubernetes nodes with affinity, anti‑affinity and tolerations
 
 The Operator automatically assigns Pods to nodes with sufficient resources for balanced distribution across the cluster. You can configure Pods to be scheduled on specific nodes. For example, for improved performance on the SSD
 equipped machine or for cost optimization by choosing the nodes in the same availability zone.

docs/how-it-works.md

@@ -0,0 +1,22 @@
+# How the Operator works
+
+The Percona Operator for MySQL acts as your assistant in managing databases on Kubernetes. It extends the Kubernetes API with a custom `PerconaServerMySQL` resource. Think of it as a blueprint that defines how you want your MySQL database to look and behave.
+
+Whenever you create or update a `PerconaServerMySQL` Custom Resource, the Operator steps in and handles the hard work for you. It automatically does the following:
+
+1. Creates and manages the necessary Kubernetes resources (StatefulSets, Services, Pods)
+2. Ensures your cluster matches the desired state you've defined
+3. Monitors the cluster health and automatically recovers from failures
+4. Coordinates upgrades and scaling operations
+
+These operations ensure that your actual database environment always matches your request.
+
+Each MySQL node in your cluster contains a complete copy of your data, synchronized across all nodes. 
+
+![image](assets/images/replication.svg)
+
+The recommended configuration is to use at least 3 nodes. Such setup provides high availability — if any node fails, the cluster continues operating normally. Read more about [high-availability](architecture.md#high-availability) 
+
+To keep your data safe and persistent, the Operator uses Kubernetes storage systems called Persistent Volumes (PVs) and PersistentVolumeClaims (PVCs). When you request storage for your database, a PVC automatically finds and attaches available storage for you. If a node fails, the Kubernetes storage system can move your data to another node, making sure your database remains available and your data stays protected.
+
+Ready to get started? Continue to the [quickstart guide](quickstart.md) to deploy your first cluster, or explore the [architecture overview](architecture.md) to understand the inner workings of the Operator. For hands-on steps and best practices, check out [What next?](what-next.md).

docs/quickstart.md

@@ -2,12 +2,12 @@
 
 Ready to get started with the Percona Operator for MySQL? In this section, you will learn some basic operations, such as:
 
--	Install and deploy an Operator
--	Connect to MySQL instance in your database cluster
--	Insert sample data to the database
--	Set up and make a logical backup
--	Monitor the database health with Percona Monitoring and Management (PMM)
+- Install and deploy an Operator
+- Connect to MySQL instance in your database cluster
+- Insert sample data to the database
+- Set up and make a logical backup
+- Monitor the database health with Percona Monitoring and Management (PMM)
 
 ## Next steps
- 
+
 [Install the Operator :material-arrow-right:](kubectl.md){.md-button}