Skip to content

first review of nginx on AKS Learning Path #2516

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 7, 2025
Merged

first review of nginx on AKS Learning Path #2516

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 7 additions & 8 deletions ...ent/learning-paths/servers-and-cloud-computing/multiarch_nginx_on_aks/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -35,7 +35,6 @@ armips:

operatingsystems:
- Linux
- macOS

tools_software_languages:
- nginx
Expand Down
79 changes: 48 additions & 31 deletions ...paths/servers-and-cloud-computing/multiarch_nginx_on_aks/apply-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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/
Expand Down Expand Up @@ -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
...
Expand All @@ -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.
18 changes: 10 additions & 8 deletions ...paths/servers-and-cloud-computing/multiarch_nginx_on_aks/create-test-utility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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.
28 changes: 15 additions & 13 deletions ...learning-paths/servers-and-cloud-computing/multiarch_nginx_on_aks/deploy-arm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down
Loading