Update docs

docs/.vitepress/config.mts

@@ -43,15 +43,29 @@ const config = defineConfig({
           { text: 'Architecture', link: '/guide/deployment/architecture' },
           { text: 'Resources and scaling', link: '/guide/deployment/resources-scaling' },
           { text: 'Helm chart', link: '/guide/deployment/helm-chart' },
+          { text: 'CI/CD', link: '/guide/deployment/ci-cd' },
         ]
       },
       {
-        text: '🧩 Advanced',
+        text: '💡 Advanced',
         collapsed: false,
         items: [
           { text: 'High availability', link: '/guide/advanced/high-availability' },
+          { text: 'Monitoring', link: '/guide/advanced/monitoring' },
+          { text: 'Log management', link: '/guide/advanced/log-management' },
+          { text: 'ARM64 architecture', link: '/guide/advanced/arm64-architecture' },
+          { text: 'Read-only filesystem', link: '/guide/advanced/read-only-filesystem' },
+          { text: 'Amazon S3 Media storage', link: '/guide/advanced/amazon-s3-media-storage' },
+          { text: 'Spot / preemptible instances', link: '/guide/advanced/spot-preemptible-instances' },
         ]
       },
+      {
+        text: '🧩 Modules',
+        collapsed: false,
+        items: [
+          { text: 'Selection', link: '/guide/modules/selection' }
+        ]
+      }
     ],
     editLink: {
       pattern: 'https://github.com/ClickAndMortar/magento-kubernetes/edit/main/docs/:path',

docs/guide/advanced/high-availability.md

@@ -3,3 +3,95 @@ title: High availability
 ---
 
 # High availability
+
+Magento / Adobe Commerce availability depends on the availability of all it's external services (database, cache, search, etc.), and the underlying infrastructure (Kubernetes cluster, nodes, etc.).
+
+High availability is the ability of a system to remain operational even when some of its components fail.
+
+In this page, we will cover all the aspects of high availability for Magento / Adobe Commerce on Kubernetes.
+
+> [!NOTE]
+> In the below explanations, we will be considering that your Kubernetes cluster is deployed on a cloud provider (AWS, GCP, Azure, etc.), and that it's managed by the cloud provider (EKS, GKE, AKS, etc.).
+
+## Kubernetes Cluster and Nodes
+
+The first step to ensure high availability is to have a highly available Kubernetes cluster.
+
+A highly available Kubernetes cluster is a cluster that can tolerate the failure of one or more nodes, and still remain operational.
+
+To achieve this, you need to deploy your Kubernetes cluster across multiple availability zones (AZs), and have at least one master node in each AZ.
+
+This way, if one AZ goes down, the other AZs can take over the workload.
+
+```mermaid
+%%{init: {"flowchart": {"htmlLabels": false}} }%%
+graph TB
+    subgraph AZ2["Availability Zone 2"]
+        direction LR
+        N4[Node 2]
+        N5[Node 4]
+        N6[Node 6]
+    end
+    subgraph AZ1["Availability Zone 1"]
+        direction LR
+        N1[Node 1]
+        N2[Node 3]
+        N3[Node 5]
+    end
+```
+
+Furthermore, you should have **at least 2 nodes in each AZ**, to ensure that the cluster can still operate if one node goes down, or during an upgrade.
+
+## Load Balancing
+
+Kubernetes Services act as a round-robin load balancer for the Pods of a Deployment.
+
+When a Pod goes down (not ready), the `Service` will automatically redirect the traffic to another `Pod`.
+
+Concerning the trafic coming from the Internet, you should use a cloud provider's Load Balancer (layer 7 or layer 4) to distribute the traffic across the nodes of your Kubernetes cluster (see [the architecture page](/guide/deployment/architecture#networking)).
+
+```mermaid
+%%{init: {"flowchart": {"htmlLabels": false}} }%%
+graph TB
+    R["HTTP Request"]
+    LB[Load Balancer]
+    subgraph AZ2["Availability Zone 2"]
+        direction LR
+        N4[Node 2]
+        N5[Node 4]
+        N6[Node 6]
+    end
+    subgraph AZ1["Availability Zone 1"]
+        direction LR
+        N1[Node 1]
+        N2[Node 3]
+        N3[Node 5]
+    end
+    R --> LB
+    LB --> N1
+    LB --> N2
+    LB --> N3
+    LB --> N4
+    LB --> N5
+    LB --> N6
+```
+
+Using a Load Balancer both helps distribute the traffic across the nodes, and ensures that the traffic is redirected to the healthy nodes, to ensure high availability.
+
+## Web server Pods
+
+As mentioned in the [resources and scaling page](/guide/deployment/resources-scaling##workload-placement), `Pods` should be distributed across the nodes and AZs of the Kubernetes cluster.
+
+Additionally, we should define:
+
+* A `PodDisruptionBudget` to ensure that at least a given number of `Pods` is available at all times
+* A readiness and liveness probe to ensure that the `Pod` is healthy and ready to receive traffic, and to restart it if needed (stale)
+
+> [!IMPORTANT]
+> When defining a readiness probe for your PHP FPM container, you shouldn't rely Magento's `health_check.php` endpoint, as it depends on external services to be available.
+
+## Database (MySQL)
+
+## Cache (Redis)
+
+## Search (Elasticsearch / OpenSearch)

docs/guide/build/optimization.md

@@ -45,14 +45,18 @@ $ find vendor/ -type d \( -iname 'test' -o -iname 'tests' \) -exec du -s {} + |
 
 We have over **200MB** of test files in our `vendor` directory. We can remove them by adding the following line to our `Dockerfile`.
 
+We an also completely remove the `dev` directory (which is almost **80MB**), but as it is versioned, the easy way is to avoid copying it in the first place, adding it to the `.dockerignore` file.
+
 As mentionned before, removing them in a new `RUN` instruction will not reduce the size of the image, as the files will still be present in the previous layer.
 
 Hence, we need to remove them in the same layer as the `composer install` command:
 
 ```dockerfile
 RUN composer install --no-dev --no-interaction --no-progress --no-suggest \
     # Remove test directories
-    && find vendor/ -type d \( -iname 'test' -o -iname 'tests' \) -exec rm -rf {} +
+    && find vendor/ -type d \( -iname 'test' -o -iname 'tests' \) -exec rm -rf {} + \
+    # Remove dev directory \
+    && rm -rf dev
 ```
 
 > [!WARNING]

docs/guide/deployment/resources-scaling.md

@@ -135,6 +135,9 @@ spec:
                     <label-key>: <label-value>
 ```
 
+> [!TIP]
+> To ensure high availability, you should also have an anti-affinity rule based on the `failure-domain.beta.kubernetes.io/zone` label, to ensure that Pods are not scheduled on the same Availability Zone.
+
 ## Horizontal scaling
 
 We want to achieve two main goals with horizontal scaling:
@@ -193,3 +196,16 @@ You should keep your `minReplicas` as low as possible, to save resources and cos
 From our experience, a good CPU utilization percentage to start with is **70%**, which is high enough to prevent over-provisioning, but low enough to ensure that the `Pods` can handle traffic spikes, by scaling up before the CPU usage reaches 100%.
 
 As always, you should monitor your `Pods` and `Nodes` to ensure that the autoscaling is working as expected, and adjust the configuration if needed.
+
+## Cluster sizing
+
+When sizing your Kubernetes cluster, you should take into account the resources needed by your workloads, as well as the capacity of your Nodes.
+
+In order to be scale horizontally in a cost-effective way, you should aim to have a cluster with relatively small Nodes, **between 4 and 8 CPU cores**.
+
+On cloud providers, instances cost is generally proportional to the number of CPU cores and available memory, so having a cluster with small Nodes won't be more expensive than having a cluster with large Nodes.
+
+You should keep in mind that system processes and `DaemonSets` will consume some CPU and memory on each Node, betwwen 0.5 and 1 CPU cores, so you should take that into account when sizing your Nodes:
+
+* If nodes are too large, you may end up with underutilized resources
+* If nodes are too small, you will proportionally have less resources for your Pods

docs/guide/introduction.md

@@ -12,7 +12,7 @@ The following topics will be covered:
 
 * Making your Magento / Adobe Commerce project Kubernetes-ready / cloud-native
 * Building the Docker image
-* Deploying to Kubernetes
+* Deploying to Kubernetes with zero downtime (ZDD)
 * Advanced topics
   * Continuous Integration / Continuous Deployment (CI/CD)
   * Scaling

docs/guide/modules/selection.md

@@ -0,0 +1,11 @@
+---
+title: Modules selection
+---
+
+# Modules selection
+
+| Module                                 | Description                                                                       | Link                                                              |
+|----------------------------------------|-----------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| `zepgram/magento-dotenv`               | Use [Symfony Dotenv](https://symfony.com/components/Dotenv) component             | [GitHub](https://github.com/zepgram/magento-dotenv)               |
+| `zepgram/module-disable-search-engine` | Disable search-engine, i.e. when relying only on an external service like Algolia | [GitHub](https://github.com/zepgram/module-disable-search-engine) |
+| `magento2-sonarqube`                   | Magento 2 Sonarqube rules                                                         | [GitHub](https://github.com/zepgram/magento2-sonarqube)           |