first pass of storefront on GKE

Author: anupras-mohapatra-arm

content/learning-paths/servers-and-cloud-computing/storefront-ai-assistant-gke-axion/_index.md

@@ -1,13 +1,9 @@
 ---
-title: Build a mixed-placement AI shopping assistant on GKE with Axion
-
-draft: true
-cascade:
-    draft: true
+title: Build a mixed-placement AI shopping assistant on Google Kubernetes Engine with Axion-based compute
 
 minutes_to_complete: 120
 description: Deploy and validate an Online Boutique storefront on GKE, add an AI shopping assistant, and compare N4A and C4A placement for the assistant tier.
-who_is_this_for: This is an advanced topic for cloud developers, platform engineers, and site reliability engineers who run applications on Google Kubernetes Engine and want to place application tiers on the Axion-based machine series that fits each workload.
+who_is_this_for: This is an advanced topic for cloud developers, platform engineers, and site reliability engineers who run applications on Google Kubernetes Engine (GKE) and want to place application tiers on the Axion-based machine series that fits each workload.
 
 learning_objectives:
     - Create and validate an Online Boutique storefront on an N4A node pool
@@ -18,7 +14,7 @@ learning_objectives:
 prerequisites:
     - A [Google Cloud account](https://console.cloud.google.com/) with billing enabled
     - Access to a [GKE Standard cluster with Arm node pools](https://cloud.google.com/kubernetes-engine/docs/how-to/create-arm-clusters-nodes), including N4A and C4A node pools
-    - Basic familiarity with Docker, Kubernetes, Kustomize, and Google Kubernetes Engine
+    - Basic familiarity with Docker, Kubernetes, Kustomize, and GKE
 
 author:
    - Rani Chowdary Mandepudi

content/learning-paths/servers-and-cloud-computing/storefront-ai-assistant-gke-axion/background.md

@@ -9,27 +9,29 @@ layout: "learningpathall"
 
 Modern AI applications often contain more than one workload shape. For example, a storefront is steady, service-oriented, and always on. An AI assistant is burstier and more latency-sensitive because it runs only when users ask for help.
 
-This Learning Path uses that split in a live Online Boutique storefront on Google Kubernetes Engine (GKE). The storefront starts on N4A nodes powered by Google Axion processors and Arm Neoverse N3. You add the missing `shoppingassistantservice`, run it on N4A first, and then move only that assistant tier to C4A nodes powered by Google Axion and Arm Neoverse V2.
+You'll use this split in a live Online Boutique storefront on Google Kubernetes Engine (GKE). The storefront starts on N4A nodes powered by Google Axion processors and Arm Neoverse N3. You'll add the missing `shoppingassistantservice`, run it on N4A first, and then move only that assistant tier to C4A nodes powered by Google Axion and Arm Neoverse V2.
 
-The goal isn't to prove that one Axion-based machine series replaces the other. You use N4A for the steady storefront tier and evaluate C4A for the AI reasoning tier so you can decide which machine series fits each workload.
+The goal isn't to prove that one Axion-based machine series replaces the other. You'll use N4A for the steady storefront tier and evaluate C4A for the AI reasoning tier so you can decide which machine series fits each workload.
 
 ![Architecture diagram showing the existing multi-architecture storefront image workflow and the final GKE placement on Axion. Core storefront services run on N4A, while the shopping assistant, Ollama sidecar, and Gemma model run together on C4A and call the live cart and catalog services.#center](images/mixed-placement-agentic-storefront-on-axion.webp "Mixed-placement agentic storefront on Axion")
 
-The diagram shows the final mixed-placement pattern you build toward. Its left side summarizes the multi-architecture image publishing process used for the existing storefront images; you don't repeat that process here. The assistant image you build later targets only `linux/arm64` because both destination node pools are Arm-based. The right side shows the final placement: core services remain on N4A while the assistant, its Ollama sidecar, and the Gemma model move together to C4A.
+The diagram shows the final mixed-placement pattern you'll build toward. Its left side summarizes the multi-architecture image publishing process used for the existing storefront images; you don't repeat that process here. The assistant image you'll build later targets only `linux/arm64` because both destination node pools are Arm-based. The right side shows the final placement: core services remain on N4A while the assistant, its Ollama sidecar, and the Gemma model move together to C4A.
 
 ## How the storefront already runs on Arm
 
 The storefront baseline uses container images that can run on Arm nodes. A common way to publish portable container images is to use a multi-architecture image, which is one image reference that contains variants for more than one CPU architecture, such as `linux/amd64` and `linux/arm64`.
 
-When Kubernetes schedules a pod that uses a multi-architecture image on an Arm node, the container runtime pulls the Arm-compatible variant from the same image reference. That is why the storefront can already run on Axion nodes before you build the assistant image.
+When Kubernetes schedules a pod that uses a multi-architecture image on an Arm node, the container runtime pulls the Arm-compatible variant from the same image reference. That's why the storefront can already run on Axion nodes before you build the assistant image.
 
-This Learning Path starts with Arm-compatible storefront images already available. To learn the full build-and-publish workflow for multi-architecture images on GKE, see [Migrate x86 workloads to Arm on Google Kubernetes Engine with Axion processors](/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/).
+You'll start with Arm-compatible storefront images already available. To learn the full build-and-publish workflow for multi-architecture images on GKE, see [Migrate x86 workloads to Arm on Google Kubernetes Engine with Axion processors](/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/).
 
-One image reference can therefore contain an Arm-compatible variant. You confirm the storefront image reference from the source tree after you set up your tools and cluster access.
+One image reference can therefore contain an Arm-compatible variant. You'll confirm the storefront image reference from the source tree after you set up your tools and cluster access.
 
 ## How assistant requests flow
 
-The `shoppingassistantservice` is the AI layer for the application. It runs as its own Kubernetes service and handles requests sent through the storefront frontend. When a shopper uses the assistant, the request follows this path:
+The `shoppingassistantservice` is the AI layer for the application. It runs as its own Kubernetes service and handles requests sent through the storefront frontend.
+
+When a shopper uses the assistant, the request follows this path:
 
 1. The browser sends the request to `frontend`.
 2. `frontend` forwards the request to `shoppingassistantservice`.
@@ -43,5 +45,8 @@ The `search_catalog` and `get_product_details` tools query the live catalog. The
 
 This design keeps the placement comparison focused. You don't add a separate vector database, retrieval pipeline, or hosted large language model API. When you move the assistant pod, you move the assistant logic and local reasoning runtime together as one AI tier.
 
+## What you've learned and what's next
+
+You've now understood the architecture of the storefront application and its AI assistant.
 
-In the next section, you'll set up environment variables, connect to the GKE cluster, and clone the source tree that contains the assistant implementation.
+Next, you'll set up environment variables, connect to the GKE cluster, and clone the source tree that contains the assistant implementation.

content/learning-paths/servers-and-cloud-computing/storefront-ai-assistant-gke-axion/build-assistant-image.md

@@ -7,7 +7,7 @@ layout: "learningpathall"
 
 ## Build one Arm image for both Axion placements
 
-Both the N4A and C4A node pools in this Learning Path use Arm-based Google Axion processors. You only need one `linux/arm64` assistant image, and that image can run in either placement.
+You need only one `linux/arm64` assistant image for both the N4A and C4A pools, and that image can run in either placement.
 
 {{% notice Note %}}
 This is an Arm-targeted build for Axion, not a full multi-architecture build. A multi-architecture image is useful when the same tag must support non-Arm environments such as `linux/amd64`.
@@ -46,10 +46,10 @@ List the tags for the assistant image:
 gcloud artifacts docker tags list "${ASSISTANT_IMAGE_REPO}"
 ```
 
-The output should include the `lab-v1` tag.
+The output includes the `lab-v1` tag.
 
-## What you've accomplished
+## What you've accomplished and what's next
 
-You've built and published an Arm image for the shopping assistant. Kubernetes can now pull this image when you deploy the assistant on N4A.
+You've now built and published an Arm image for the shopping assistant. Kubernetes can now pull this image when you deploy the assistant on N4A.
 
 Next, you'll create the N4A overlay and add the assistant to the running storefront.

content/learning-paths/servers-and-cloud-computing/storefront-ai-assistant-gke-axion/deploy-assistant-n4a.md

@@ -18,7 +18,7 @@ export FRONTEND_IP="$(kubectl get service frontend-external \
 export APP_URL="http://${FRONTEND_IP}"
 ```
 
-The `storefront-n4a` overlay already places every deployment on N4A. Extend it with the assistant component and the image you pushed. The existing `node-selector.yaml` patch then applies the same placement to the assistant deployment.
+The `storefront-n4a` overlay already places every deployment on N4A. Extend it with the assistant component and the image you pushed. The existing `node-selector.yaml` patch then applies the same placement to the assistant deployment:
 
 ```bash
 cat <<EOF > kustomize/overlays/storefront-n4a/kustomization.yaml
@@ -49,7 +49,7 @@ sed -n '1,120p' kustomize/overlays/storefront-n4a/node-selector.yaml
 kubectl kustomize kustomize/overlays/storefront-n4a | sed -n '1,240p'
 ```
 
-Do not apply the overlay if the rendered manifest has an empty image name, image tag, or node-pool value.
+Don't apply the overlay if the rendered manifest has an empty image name, image tag, or node-pool value.
 
 ## Apply the overlay
 
@@ -62,7 +62,7 @@ kubectl rollout status deployment/shoppingassistantservice --timeout=1200s
 ```
 
 {{% notice Note %}}
-`kubectl apply -k` reapplies the full rendered application state. It is normal to see existing deployments reported as `configured`. The `shopping-assistant` component patches `frontend`, so a frontend rollout is expected.
+`kubectl apply -k` reapplies the full rendered application state. It's normal to see existing deployments reported as `configured`. The `shopping-assistant` component patches `frontend`, so a frontend rollout is expected.
 {{% /notice %}}
 
 ## Confirm pod placement
@@ -121,7 +121,7 @@ for i in {1..12}; do
 done
 ```
 
-The JSON response should include a non-empty assistant message. The exact product names can vary, but the response should be grounded in the live product catalog.
+The JSON response includes a non-empty assistant message. The exact product names can vary, but the response is grounded in the live product catalog.
 
 ## Try the browser flow
 
@@ -138,8 +138,8 @@ What is in my cart now?
 
 The assistant should recommend a catalog item, ask for confirmation before changing the cart, and then show the cart contents.
 
-## What you've accomplished
+## What you've accomplished and what's next
 
-You've deployed the assistant on N4A and validated it through the same storefront path that a shopper uses.
+You've now deployed the assistant on N4A and validated it through the same storefront path that a shopper uses.
 
 Next, you'll observe the assistant as a live workload and capture the N4A benchmark baseline.

content/learning-paths/servers-and-cloud-computing/storefront-ai-assistant-gke-axion/move-assistant-c4a.md

@@ -84,7 +84,7 @@ sed -n '1,140p' kustomize/overlays/assistant-c4a/shoppingassistant-c4a.yaml
 kubectl kustomize kustomize/overlays/assistant-c4a | sed -n '1,240p'
 ```
 
-Do not continue if `newName`, `newTag`, or either node-pool value is blank.
+Don't continue if `newName`, `newTag`, or either node-pool value is blank.
 
 {{% notice Note %}}
 The first patch keeps the storefront on N4A by default. The second patch overrides only `shoppingassistantservice` and moves that deployment to C4A.
@@ -107,7 +107,7 @@ kubectl get pods -o wide | grep -E 'frontend|shoppingassistantservice'
 kubectl get nodes -L cloud.google.com/gke-nodepool,node.kubernetes.io/instance-type,kubernetes.io/arch
 ```
 
-The frontend should remain on N4A, and `shoppingassistantservice` should now run on C4A.
+The frontend remains on N4A, and `shoppingassistantservice` now runs on C4A.
 
 ## Warm the assistant on C4A
 
@@ -129,7 +129,7 @@ for i in {1..12}; do
 done
 ```
 
-The response should contain a non-empty message.
+The response contains a non-empty message.
 
 ## Run the fixed C4A benchmark
 
@@ -158,7 +158,7 @@ Print the C4A summary line:
 grep 'SUMMARY_JSON' workshop/fixed-c4a-summary.log
 ```
 
-The summary should show successful requests and the assistant running on the C4A node pool. Do not compare the runs if the summary line is missing or reports a different node pool.
+The summary shows successful requests and the assistant running on the C4A node pool. Don't compare the runs if the summary line is missing or reports a different node pool.
 
 ## Compare the two runs
 
@@ -187,7 +187,7 @@ Your numbers can vary by prompt mix, model warmup state, node pressure, and clus
 Assistant CPU values come from sampled Kubernetes telemetry. Short bursts can be underrepresented, especially on faster runs. Treat request success, benchmark duration, and latency as the primary comparison signals.
 {{% /notice %}}
 
-## Explain the result
+## Understand the result
 
 You changed one architectural variable: the placement of the assistant. The storefront tier, prompts, model, traffic shape, and benchmark script stayed the same.
 
@@ -201,12 +201,12 @@ That sequence is the core architectural point. A modern application can contain
 
 Both Axion machine series run `arm64`, so the same assistant image moves between the Neoverse N3-based N4A pool and the Neoverse V2-based C4A pool. You can evaluate placement without maintaining a second image or build pipeline.
 
-For this application, the useful pattern is not replacing one machine series with another. It is placing each workload tier where its behavior fits best.
+For this application, the useful pattern isn't replacing one machine series with another. It's placing each workload tier where its behavior fits best.
 
-If your N4A and C4A results are close, or if N4A looks better for a particular run, that is still useful information. The decision should come from the workload behavior you observe, not from assuming one Axion-based machine series is always the right answer.
+If your N4A and C4A results are close, or if N4A looks better for a particular run, that's still useful information. The decision should come from the workload behavior you observe, not from assuming one Axion-based machine series is always the right answer.
 
 ## What you've accomplished
 
 You've built, observed, and compared a mixed-placement storefront application on Axion. You kept the storefront on N4A, moved only the assistant tier to C4A, and used the same benchmark to compare both placements.
 
-You are now ready to use the same overlay and benchmark pattern to evaluate which Axion-based machine series matches each tier's workload behavior.
+You're now ready to use the same overlay and benchmark pattern to evaluate which Axion-based machine series matches each tier's workload behavior.

content/learning-paths/servers-and-cloud-computing/storefront-ai-assistant-gke-axion/observe-benchmark-n4a.md

@@ -29,7 +29,7 @@ python3 -m py_compile workshop/fixed_batch_trial.py
 python3 -m py_compile workshop/compare_summaries.py
 ```
 
-If `kubectl top` is not available yet, make sure metrics collection is enabled in the cluster before you rely on CPU telemetry.
+If `kubectl top` isn't available yet, make sure metrics collection is enabled in the cluster before you rely on CPU telemetry.
 
 ## Open three terminals
 
@@ -45,18 +45,11 @@ export FRONTEND_IP="$(kubectl get service frontend-external \
   -o jsonpath='{.status.loadBalancer.ingress[0].ip}')"
 export APP_URL="http://${FRONTEND_IP}"
 ```
-
-Use this terminal map:
-
-| Terminal | Purpose |
-|----------|---------|
-| Terminal 1 | Telemetry collector |
-| Terminal 2 | Dashboard web server |
-| Terminal 3 | Live traffic and fixed benchmarks |
+Use the first terminal for collecting telemetry, the second terminal for the dashboard web server, and the third terminal for live traffic and fixed benchmarks. 
 
 ## Start telemetry collection
 
-Run this in Terminal 1. The `rm` command clears previous live telemetry samples for the dashboard:
+Run the following command in the first terminal. The `rm` command clears previous live telemetry samples for the dashboard:
 
 ```bash
 cd "${REPO}" || exit 1
@@ -71,7 +64,7 @@ Leave this command running.
 
 ## Start the dashboard
 
-Run this in Terminal 2. The `rm` command clears previous live request data for the dashboard:
+Run the following command in the second terminal. The `rm` command clears previous live request data for the dashboard:
 
 ```bash
 cd "${REPO}" || exit 1
@@ -87,7 +80,7 @@ If port `5000` is already in use, choose another available port, such as `5001`.
 
 ## Confirm assistant health
 
-Run this in Terminal 3:
+Run the following command in the third terminal to confirm the health of the assistant:
 
 ```bash
 cd "${REPO}" || exit 1
@@ -103,7 +96,7 @@ kubectl get pods -o wide | grep -E 'frontend|shoppingassistantservice'
 
 ## Generate a short live burst
 
-Start a short request burst so the dashboard shows activity:
+Start a short request burst in the third terminal so the dashboard shows activity:
 
 ```bash
 rm -f workshop/request-live.pid
@@ -142,7 +135,7 @@ Stopping the live burst keeps the N4A and C4A benchmark runs comparable.
 
 ## Run the fixed N4A benchmark
 
-Run the fixed batch while the assistant is still on N4A:
+Run the fixed batch in the third terminal while the assistant is still on N4A:
 
 ```bash
 python3 workshop/fixed_batch_trial.py \
@@ -161,18 +154,18 @@ python3 workshop/fixed_batch_trial.py \
   tee workshop/fixed-n4a-summary.log
 ```
 
-The command can keep running after the last request lines appear. It is still sampling telemetry and waiting for the assistant to settle back toward idle.
+The command can keep running after the last request lines appear. It's still sampling telemetry and waiting for the assistant to settle back toward idle.
 
 Print the summary line:
 
 ```bash
 grep 'SUMMARY_JSON' workshop/fixed-n4a-summary.log
 ```
 
-The summary should show successful requests and the assistant running on the N4A node pool. Do not continue if the summary line is missing or reports a different node pool.
+The summary shows successful requests and the assistant running on the N4A node pool. Don't continue if the summary line is missing or reports a different node pool.
 
-## What you've accomplished
+## What you've accomplished and what's next
 
-You've observed the assistant as a live workload and captured the N4A benchmark baseline.
+You've now observed the assistant as a live workload and captured the N4A benchmark baseline.
 
 Next, you'll move only the assistant tier to C4A and run the same benchmark again.