Merge pull request #2516 from jasonrandrews/review

first review of nginx on AKS Learning Path

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/multiarch_nginx_on_aks/_index.md

@@ -1,20 +1,20 @@
 ---
-title: Add Arm nodes to your Azure Kubernetes Services cluster using a multi-architecture nginx container image 
+title: Build hybrid AKS clusters with Arm nodes and nginx
 
 draft: true
 cascade:
     draft: true
 
 minutes_to_complete: 60
 
-who_is_this_for: This Learning Path is for developers who want to compare the performance of x64 and arm64 deployments by running nginx on a hybrid Azure Kubernetes Service (AKS) cluster using nginx's multi-architecture container image.  Once you've seen how easy it is to add arm64 nodes to an existing cluster, you'll be ready to explore arm64-based nodes for other workloads in your environment.
-
+who_is_this_for: This Learning Path is for developers who want to understand nginx performance on x64 and arm64 deployments by running a hybrid Azure Kubernetes Service (AKS) cluster. 
 
 learning_objectives:
-  - Create a hybrid AKS cluster with x64 and arm64 nodes.
-  - Deploy nginx's multi-architecture container image, pods, and services to the AKS cluster. 
-  - Smoke test nginx from each architecture in the cluster to verify proper installation.
-  - Performance test against each architecture in the cluster to better understand performance.
+  - Create a hybrid AKS cluster with x64 and arm64 nodes
+  - Deploy nginx's multi-architecture container image, pods, and services to the AKS cluster
+  - Smoke test nginx from each architecture in the cluster to verify proper installation
+  - Test the performance of each architecture in the cluster
+  - Apply the same process to other kubernetes workloads
 
 
 prerequisites:
@@ -35,7 +35,6 @@ armips:
 
 operatingsystems:
     - Linux
-    - macOS
 
 tools_software_languages:
     - nginx

content/learning-paths/servers-and-cloud-computing/multiarch_nginx_on_aks/apply-configuration.md

@@ -6,23 +6,23 @@ weight: 70
 layout: learningpathall
 ---
 
-## Apply configuration updates
+## Install btop monitoring tool on nginx pods
 
-Now that you have all your nginx deployments running across Intel and ARM architectures, you can monitor performance across each architecture using wrk to generate load and btop to monitor system performance.
+Now that you have all your nginx deployments running across Intel and Arm architectures, you can monitor performance across each architecture using wrk to generate load and btop to monitor system performance.
 
 {{% notice Note %}}
-This tutorial uses wrk to generate load, which is readily available on apt and brew package managers.  [wrk2](https://github.com/giltene/wrk2) is a modern fork of wrk with additional features.  wrk was chosen for this tutorial due to its ease of install, but if you prefer to install and use wrk2 (or other http load generators) for your testing, feel free to do so.
+This tutorial uses [wrk](https://github.com/wg/wrk) to generate load, which is readily available on apt and brew package managers. [wrk2](https://github.com/giltene/wrk2) is a modern fork of wrk with additional features. wrk was chosen for this tutorial due to its ease of installation, but if you prefer to install and use wrk2 (or other http load generators) for your testing, feel free to do so.
 {{% /notice %}}
 
-### Apply performance configuration
+### Install btop and apply optimized configuration
 
 The `nginx_util.sh` script includes a `put config` command that will:
 
 - Apply a performance-optimized nginx configuration to all pods
 - Install btop monitoring tool on all pods for system monitoring
 - Restart pods with the new configuration
 
-1. Run the following command to apply the configuration updates:
+Run the following command to apply the configuration updates:
 
 ```bash
 ./nginx_util.sh put btop
@@ -41,9 +41,9 @@ Installing btop on nginx-intel-deployment-6f5bff9667-zdrqc...
 ✅ btop installed on all pods!
 ```
 
-### Verify configuration updates
+### Check pod restart status
 
-2. Check that all pods have restarted with the new configuration:
+Check that all pods have restarted with the new configuration:
 
 ```bash
 kubectl get pods -n nginx
@@ -52,57 +52,72 @@ kubectl get pods -n nginx
 You should see all pods with recent restart times.
 
 {{% notice Note %}}
-Because pods are ephemeral, btop will need to be reinstalled if the pods are deleted or restarted.  If you get an error saying btop is not found, simply rerun the `./nginx_util.sh put btop` command to reinstall it.
+Because pods are ephemeral, btop will need to be reinstalled if the pods are deleted or restarted. If you get an error saying btop is not found, rerun the `./nginx_util.sh put btop` command to reinstall it.
 {{% /notice %}}
 
 
-### Monitor pod performance
+### Set up real-time performance monitoring
 
-You can now login to any pod and use btop to monitor system performance.  There are many variables which may affect an individual workload's performance, btop (like top), is a great first step in understanding those variables.
+You can now log in to any pod and use btop to monitor system performance. There are many variables that can affect an individual workload's performance, and btop (like top) is a great first step in understanding those variables.
 
 {{% notice Note %}}
-When performing load generation tests from your laptop, local system and network settings may interfere with proper load generation between your machine and the remote cluster services.  To mitigate these issues, its suggested to install the nginx_util.sh (or whichever tool you wish to use) on a [remote Azure instance](https://learn.arm.com/learning-paths/servers-and-cloud-computing/csp/azure/) in the same region and zone as your K8s cluster (us-west-2 if you follow these tutorial instructions exactly) for best results.  If you aren't seeing at least 70K+ requests/s to either K8s service endpoint, switching to a better located/tuned system is advised.
+When performing load generation tests from your laptop, local system and network settings may interfere with proper load generation between your machine and the remote cluster services. To mitigate these issues, it's suggested to install the `nginx_util.sh` script on a [remote Azure instance](https://learn.arm.com/learning-paths/servers-and-cloud-computing/csp/azure/) in the same region and zone as your K8s cluster for best results. If you aren't seeing at least 70K+ requests/s to either K8s service endpoint, switching to a better located system is advised.
 {{% /notice %}}
 
-Bringing up two btop terminals, one for each pod, is a convenient way to view performance in realtime. To bring up btop on both Arm and Intel pods:
+Running two btop terminals, one for each pod, is a convenient way to view performance in real time. 
 
-1. Open a new terminal window or tab.
-2. Within the terminal, run the `login arm` command from the nginx utility script to enter the pod: 
+To bring up btop on both Arm and Intel pods:
+
+1. Open two new terminal windows
+2. In one terminal, run `login arm` from the nginx utility script to enter the pod 
+3. In the second terminal, run `login intel` from the nginx utility script to enter the pod 
+4. Once inside each pod, run btop to see real-time system monitoring
+
+The commands are shown below.
+
+For the Arm terminal:
 
 ```bash
-# Login to AMD pod (replace with intel or arm as needed)
 ./nginx_util.sh login arm
 ```
 
-3. Once inside the pod, run btop to see real-time system monitoring:
+For the Intel terminal:
+
+```bash
+./nginx_util.sh login intel
+```
+
+In both terminals run:
 
 ```bash
 btop --utf-force
 ```
-4. Repeat, from Step 1, but this time, using the `login intel` command.
 
-You should now see something similar to below, that is, one terminal for each Arm and Intel, running btop:
+You should now see something similar to the image below, with one terminal for each Arm and Intel pod running btop:
 
 ![Project Overview](images/btop_idle.png)
 
-To visualize performance with btop against the Arm and Intel pods via the load balancer service endpoints, you can use the nginx_util.sh wrapper to generate the load two both simultaneoulsy:
+To visualize performance with btop against the Arm and Intel pods via the load balancer service endpoints, you can use the `nginx_util.sh` wrapper to generate load to both simultaneously:
 
 ```bash
 ./nginx_util.sh wrk both
 ```
 
-This runs wrk with predefined setting (1 thread, 50 simultaneous connections) to generate load to the K8s architecture-specific endpoints. While it runs (for a default of 30s), you can observe some performance characteristics from the btop outputs:
+This runs wrk with predefined settings (1 thread, 50 simultaneous connections) to generate load to the K8s architecture-specific endpoints. 
+
+While it runs (for a default of 30s), you can observe some performance characteristics from the btop outputs:
 
 ![Project Overview](images/under_load.png)
 
-Of particular interest is memory and CPU resource usage per pod.  For Intel, figure 1 shows memory usage for the process, with figure 2 showing total cpu usage.  Figures 3 and 4 show us the same metrics, but for Arm.
+Of particular interest is memory and CPU resource usage per pod. For Intel, red marker 1 shows memory usage for the process, and red marker 2 shows total CPU usage.  
+
+Red markers 3 and 4 show the same metrics for Arm.
 
 ![Project Overview](images/mem_and_cpu.png)
 
-In addition to the visual metrics, the script also returns runtime results including requests per second, and latencies:
+In addition to the visual metrics, the script also returns runtime results including requests per second and latencies:
 
 ```output
-azureuser@gcohen-locust-1:/tmp/1127$ ./nginx_util.sh wrk both
 Running wrk against both architectures in parallel...
 
 Intel: wrk -t1 -c50 -d30 http://172.193.227.195/
@@ -134,9 +149,9 @@ Transfer/sec:     26.24MB
 Both tests completed
 ```
 
-### Experimenting with wrk
+### Customize load testing parameters
 
-The nginx_util.sh script shows the results of the load generation, as well as the command lines used to generate them.  
+The `nginx_util.sh` script shows the results of the load generation, as well as the command lines used to generate them.  
 
 ```output
 ...
@@ -146,21 +161,23 @@ ARM: wrk -t1 -c50 -d30 http://20.252.73.72/
 ```
 
 
-Feel free to experiment increasing/decreasing client threads, connections, and durations to better understand the performance characteristics under different scenarios.  
+Feel free to experiment with by increasing and decreasing client threads, connections, and durations to better understand the performance characteristics under different scenarios.
 
-For example, to generate load using 500 connections across 4 threads to the Arm service for five minutes (300s), you could use the following commandline:
+For example, to generate load using 500 connections across 4 threads to the Arm service for 5 minutes (300s), you can use the following command:
 
 ```bash
 wrk -t4 -c500 -d300 http://20.252.73.72/
 ``` 
 
-As mentioned earlier, unless your local system is tuned to handle load generation, you may find better traffic generation results by running on a VM. If aren't seeing at least 70K+ requests/s to either K8s service endpoint when running `wrk`, switching to a better located/tuned system is advised.
-
 ## Next Steps
 
-You learned in this learning path how to run a sample nginx workload on a dual-architecture (Arm and Intel) Azure Kubernetes Service.  Once setup, you learned how to generate load with the wrk utility, and monitor runtime metrics with btop.  If you wish to continue experimenting with this learning path, some ideas you may wish to explore include:
+You have learned how to run a sample nginx workload on a dual-architecture (Arm and Intel) Azure Kubernetes Service.
+
+You learned how to generate load with the wrk utility and monitor runtime metrics with btop.  
+
+Here are some ideas for further exploration: 
 
 * What do the performance curves look like between the two architectures as a function of load?
 * How do larger instance types scale versus smaller ones?
 
-Most importantly, you now possess the knowledge needed to begin experimenting with your own workloads on Arm-based AKS nodes to identify performance and efficiency opportunities unique to your own environments.
+You now have the knowledge to experiment with your own workloads on Arm-based AKS nodes to identify performance and efficiency opportunities unique to your own environments.

content/learning-paths/servers-and-cloud-computing/multiarch_nginx_on_aks/create-test-utility.md

@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Test utility script
 
-You'll create a utility script to test and manage your nginx services across all architectures. This script will be used throughout the tutorial to test services, apply configurations, and access pods.
+In this section, you'll create a utility script to test and manage your nginx services across both architectures. The script will be used throughout the Learning Path to test services, apply configurations, and access pods.
 
 ### Script functionality
 
@@ -18,18 +18,19 @@ The `nginx_util.sh` script provides three main functions:
 - **`put btop`** - Install btop monitoring tool on all pods
 - **`login intel|arm`** - Interactive bash access to architecture-specific pods
 
-The script conveniently bundles test and logging commands into a single place, making it easy to test, troubleshoot, and view services. You'll use it throughout the tutorial to test services, apply configurations, and access pods across all architectures.
+The script conveniently bundles test and logging commands into a single place, making it easy to test, troubleshoot, and view services. 
 
-
-### Create the utility script
+### Download the utility script
 
 {{% notice Note %}}
-The following utility `nginx_util.sh` is provided for convenience. 
+The following utility `nginx_util.sh` is provided for your convenience. 
 
 It's a wrapper for kubectl and other commands, utilizing [curl](https://curl.se/).  Make sure you have curl installed before running.
+
+You can click on the link below to review the code before downloading. 
 {{% /notice %}}
 
-Copy and paste the following command into a terminal to download and create the `nginx_util.sh` script:
+Copy and paste the following commands into a terminal to download and create the `nginx_util.sh` script:
 
 ```bash
 curl -o nginx_util.sh https://raw.githubusercontent.com/geremyCohen/nginxOnAKS/refs/heads/main/nginx_util.sh
@@ -42,9 +43,10 @@ In the folder you ran the curl command, you should now see the `nginx_util.sh` s
 ./nginx_util.sh
 ```
 
-The output should include usage instructions:
+The output presents the usage instructions:
+
 ```output
 Invalid first argument. Use 'curl', 'wrk', 'put', or 'login'.
 ```
 
-With it working, you're now ready to deploy nginx to the Intel nodes in the cluster.
+You're now ready to deploy nginx to the Intel nodes in the cluster.

content/learning-paths/servers-and-cloud-computing/multiarch_nginx_on_aks/deploy-arm.md

@@ -1,20 +1,20 @@
 ---
-title: Deploy nginx ARM to the cluster
+title: Deploy nginx on Arm 
 weight: 50
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Add ARM deployment and service
+## Add the Arm deployment and service
 
-In this section, you'll add nginx on ARM nodes to your existing cluster, completing your multi-architecture Intel/ARM environment for comprehensive performance comparison.
+In this section, you'll add nginx on Arm to your existing cluster, completing your multi-architecture Intel/Arm environment for comprehensive performance comparison.
 
 When applied, the **arm_nginx.yaml** file creates the following K8s objects:
-   - **Deployment** (`nginx-arm-deployment`) - Pulls the multi-architecture nginx image from DockerHub, launches a pod on the ARM node, and mounts the shared ConfigMap as `/etc/nginx/nginx.conf`
+   - **Deployment** (`nginx-arm-deployment`) - Pulls the multi-architecture nginx image from DockerHub, launches a pod on the Arm node, and mounts the shared ConfigMap as `/etc/nginx/nginx.conf`
    - **Service** (`nginx-arm-svc`) - Load balancer targeting pods with both `app: nginx-multiarch` and `arch: arm` labels
 
-Copy and paste the following commands into a terminal to download and apply the ARM deployment and service:
+Copy and paste the following commands into a terminal to download and apply the Arm deployment and service:
 
 ```bash
 curl -o arm_nginx.yaml https://raw.githubusercontent.com/geremyCohen/nginxOnAKS/refs/heads/main/arm_nginx.yaml
@@ -30,17 +30,17 @@ service/nginx-arm-svc created
 
 ### Examining the deployment configuration
 
-Taking a closer look at the `arm_nginx.yaml` deployment file, you'll see settings optimized for ARM architecture:
+Taking a closer look at the `arm_nginx.yaml` deployment file, you'll see settings optimized for the Arm architecture:
 
-* The `nodeSelector` `kubernetes.io/arch: arm64`. This ensures that the deployment only runs on ARM nodes, utilizing the arm64 version of the nginx container image.
+The `nodeSelector` value of `kubernetes.io/arch: arm64` ensures that the deployment only runs on Arm nodes, utilizing the `arm64` version of the nginx container image.
 
 ```yaml
     spec:
       nodeSelector:
         kubernetes.io/arch: arm64
 ```
 
-* The service selector uses both `app: nginx-multiarch` and `arch: arm` labels to target only ARM pods. This dual-label approach allows for both architecture-specific and multi-architecture service routing.
+The service selector uses both `app: nginx-multiarch` and `arch: arm` labels to target only Arm pods. This dual-label approach allows for both architecture-specific and multi-architecture service routing.
 
 ```yaml
   selector:
@@ -50,7 +50,7 @@ Taking a closer look at the `arm_nginx.yaml` deployment file, you'll see setting
 
 ### Verify the deployment
 
-1. Get the status of nodes, pods and services by running:
+Get the status of nodes, pods and services by running:
 
 ```bash
 kubectl get nodes,pods,svc -nnginx 
@@ -78,16 +78,18 @@ You can also verify the shared ConfigMap is available:
 kubectl get configmap -nnginx
 ```
 
+The output is similar to:
+
 ```output
 NAME               DATA   AGE
 nginx-config       1      10m
 ```
 
-When the pods show `Running` and the service shows a valid `External IP`, you're ready to test the nginx ARM service.
+When the pods show `Running` and the service shows a valid `External IP`, you're ready to test the nginx Arm service.
 
-### Test the nginx web service on ARM
+### Test the nginx web service on Arm
 
-2. Run the following to make an HTTP request to the ARM nginx service using the script you created earlier:
+Run the following command to make an HTTP request to the Arm nginx service using the script you created earlier:
 
 ```bash
 ./nginx_util.sh curl arm
@@ -107,7 +109,7 @@ Response:
 Served by: nginx-arm-deployment-5bf8df95db-wznff
 ```
 
-If you see output similar to above, you have successfully added ARM nodes to your cluster running nginx.
+If you see similar output, you have successfully added Arm nodes to your cluster running nginx.
 
 ### Compare both architectures