Merge pull request #3491 from anupras-mohapatra-arm/servers-and-cloud-computing

Storefront AI assistant on GKE editorial review

Author: pareenaverma

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

@@ -1,29 +1,74 @@
 ---
-title: Build a mixed-placement AI shopping assistant on GKE with Axion
-
-draft: true
-cascade:
-    draft: true
+title: Deploy 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.
+description: Deploy and validate an Online Boutique storefront on GKE on Arm, 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 (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
+    - Deploy and validate an Online Boutique storefront on an N4A node pool
     - Build and push a `linux/arm64` container image, then add the AI shopping assistant to the storefront
     - Use Kustomize overlays to run the assistant on N4A first, then move it to C4A
     - Capture and compare benchmark summaries for the same assistant workload on N4A and C4A
 
 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
+    - 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, with the Kubernetes Metrics API enabled
+    - Permissions to get cluster credentials, deploy Kubernetes workloads and services, read pod logs and metrics, and create or use an Artifact Registry Docker repository
+    - Cloud Shell or a Linux or macOS administrative workstation with Docker Buildx, `gcloud`, `kubectl`, `git`, `curl`, Python 3.10 or later, and `jq`
+    - Basic familiarity with Docker, Kubernetes, Kustomize, and GKE
+
+# START generated_summary_faq
+generated_summary_faq:
+  template_version: summary-faq-v3
+  generated_at: '2026-07-13T19:30:38Z'
+  generator: ai
+  ai_assisted: true
+  ai_review_required: true
+  model: gpt-5
+  prompt_template: summary-faq-v3
+  source_hash: cdd45953e2784d3a6b0894fac600b6b03048b514493d6526709908f3049595cc
+  summary_generated_at: '2026-07-13T19:30:38Z'
+  summary_source_hash: cdd45953e2784d3a6b0894fac600b6b03048b514493d6526709908f3049595cc
+  faq_generated_at: '2026-07-13T19:30:38Z'
+  faq_source_hash: cdd45953e2784d3a6b0894fac600b6b03048b514493d6526709908f3049595cc
+  summary: >-
+    You'll deploy the Online Boutique storefront on Google Kubernetes
+    Engine using Arm-based Axion nodes, validate a baseline on N4A, and add a gRPC-driven AI shopping
+    assistant. You'll build and push a single `linux/arm64` container image to Artifact Registry, then
+    use Kustomize overlays to run the assistant on N4A before moving only that tier to C4A. After
+    reviewing the assistant’s source code and runtime dependencies, you'll confirm scheduling on the intended
+    node pool and capture benchmark summaries to compare the same assistant workload across N4A
+    and C4A. You'll finish with a mixed-placement deployment where the steady storefront remains
+    on N4A and the burstier assistant runs on the selected pool.
+  faqs:
+  - question: How do I verify the cluster has both N4A and C4A node pools before I start?
+    answer: >-
+      Use `kubectl` to list nodes and confirm that both pools are present. The workflow assumes
+      an `arm64` GKE Standard cluster with separate N4A and C4A pools.
+  - question: What result should I expect after I apply the baseline overlay?
+    answer: >-
+      The storefront runs on N4A, and `shoppingassistantservice` isn't present. This is intentional
+      because you'll build and deploy the assistant in later steps.
+  - question: I've run this path before. What should I remove before I recreate the baseline?
+    answer: >-
+      Delete any existing assistant deployment, related service, and service account so the baseline reflects a
+      storefront without the assistant. 
+  - question: Do I need different container images for N4A and C4A when I deploy the assistant?
+    answer: >-
+      No. You'll build one `linux/arm64` image targeted for Axion that'll run in either placement.
+  - question: How do I confirm the assistant is scheduled on the intended node pool when I switch
+      from N4A to C4A?
+    answer: >-
+      Check the node assigned to the assistant pod and verify it matches the target pool after
+      applying the appropriate Kustomize overlay. Inspect pod logs and service reachability to
+      confirm the tier is healthy before capturing benchmarks.
+# END generated_summary_faq
 
 author:
    - Rani Chowdary Mandepudi
 
-generate_summary_faq: true
+generate_summary_faq: false
 rerun_summary: false
 rerun_faqs: false
 
@@ -78,3 +123,4 @@ weight: 1                       # _index.md always has weight of 1 to order corr
 layout: "learningpathall"       # All files under learning paths have this same wrapper
 learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
 ---
+

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

@@ -9,27 +9,28 @@ 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. It 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 diagram also 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. You'll confirm the storefront image reference from the source tree after you set up your tools and cluster access.
 
-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.
 
 ## 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 +44,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 learned about 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

@@ -1,13 +1,13 @@
 ---
-title: Build and push the assistant image
+title: Build and push the assistant image to Artifact Registry
 description: Build the shopping assistant container image for arm64 and push it to Artifact Registry for deployment on Axion.
 weight: 6
 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`.
@@ -28,7 +28,7 @@ Confirm the reusable image path you configured during setup:
 echo "${ASSISTANT_IMAGE}"
 ```
 
-## Build and push the assistant image
+## Use buildx to build and push the assistant image
 
 Build the assistant image for `linux/arm64` and push it to Artifact Registry:
 
@@ -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

@@ -1,5 +1,5 @@
 ---
-title: Deploy the assistant on N4A
+title: Deploy the assistant on the Google N4A node pool
 description: Add the assistant component to the storefront and keep the application on the N4A node pool.
 weight: 7
 layout: "learningpathall"
@@ -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
@@ -99,7 +99,7 @@ The `server` container serves the assistant API. The `ollama` container prepares
 The first rollout can take a few minutes because the Ollama sidecar pulls the model when the pod starts. Early `/readyz` checks can return `503` until the model is available.
 {{% /notice %}}
 
-## Send a request in one assistant session
+## Send a request through one assistant session
 
 Open the assistant endpoint and save its HTTP session cookie in `/tmp/assistant.cookies`. The next request sends the same cookie back, just as a browser would. The assistant can then associate follow-up prompts and cart actions with the same short-lived session.
 
@@ -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
 
@@ -136,10 +136,10 @@ yes
 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.
+The assistant recommends a catalog item and asks for confirmation before changing the cart. It then shows the cart's 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.