Skip to content

Commit 57881eb

Browse files
ranimandepudiranimandepudi
committed
Add GKE Axion storefront AI assistant learning path
1 parent 0467204 commit 57881eb

12 files changed

Lines changed: 1213 additions & 0 deletions

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

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Build a mixed-placement AI shopping assistant on GKE with Axion
3+
4+
minutes_to_complete: 120
5+
description: Deploy an AI shopping assistant for an Online Boutique storefront on GKE and compare N4A and C4A placement for the assistant tier.
6+
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.
7+
8+
learning_objectives:
9+
- Explain why a storefront application and an AI assistant can have different workload profiles
10+
- Build and push a `linux/arm64` container image for the shopping assistant service
11+
- Use Kustomize overlays to run the assistant on N4A first, then move it to C4A
12+
- Capture and compare benchmark summaries for the same assistant workload on N4A and C4A
13+
14+
prerequisites:
15+
- A [Google Cloud account](https://console.cloud.google.com/) with billing enabled
16+
- Access to a [GKE Standard cluster with Arm node pools](https://cloud.google.com/kubernetes-engine/docs/how-to/create-arm-clusters-nodes), including an N4A node pool and a C4A node pool
17+
- Permission to create or use an [Artifact Registry Docker repository](https://cloud.google.com/artifact-registry/docs/docker/store-docker-container-images) in the same project
18+
- Access to Google Cloud Shell, or a local Linux or macOS terminal with `gcloud`, `kubectl`, `docker`, `git`, `jq`, and `python3`
19+
- Basic familiarity with Docker, Kubernetes, Kustomize, and Google Kubernetes Engine
20+
21+
author:
22+
- Rani Chowdary Mandepudi
23+
24+
generate_summary_faq: true
25+
rerun_summary: false
26+
rerun_faqs: false
27+
28+
### Tags
29+
skilllevels: Advanced
30+
subjects: Containers and Virtualization
31+
cloud_service_providers:
32+
- Google Cloud
33+
armips:
34+
- Neoverse
35+
operatingsystems:
36+
- Linux
37+
tools_software_languages:
38+
- Kubernetes
39+
- GKE
40+
- Docker
41+
- Kustomize
42+
- Python
43+
- Ollama
44+
45+
further_reading:
46+
- resource:
47+
title: Google Kubernetes Engine documentation
48+
link: https://cloud.google.com/kubernetes-engine/docs
49+
type: documentation
50+
- resource:
51+
title: Create standard clusters and node pools with Arm nodes
52+
link: https://cloud.google.com/kubernetes-engine/docs/how-to/create-arm-clusters-nodes
53+
type: documentation
54+
- resource:
55+
title: Google Axion processors
56+
link: https://cloud.google.com/products/axion
57+
type: documentation
58+
- resource:
59+
title: Kustomize documentation
60+
link: https://kubectl.docs.kubernetes.io/references/kustomize/
61+
type: documentation
62+
- resource:
63+
title: Ollama documentation
64+
link: https://ollama.com/
65+
type: documentation
66+
- resource:
67+
title: Migrate x86 workloads to Arm on Google Kubernetes Engine with Axion processors
68+
link: /learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/
69+
type: website
70+
71+
### FIXED, DO NOT MODIFY
72+
# ================================================================================
73+
weight: 1 # _index.md always has weight of 1 to order correctly
74+
layout: "learningpathall" # All files under learning paths have this same wrapper
75+
learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
76+
---
77+
78+
Deploy an Online Boutique storefront on Google Kubernetes Engine (GKE), add an AI shopping assistant, and compare the same assistant workload on N4A and C4A node pools powered by Google Axion processors.
79+
80+
You start with the storefront on N4A, build the missing `shoppingassistantservice` image for `linux/arm64`, validate the assistant on N4A, and then move only the assistant tier to C4A. You finish by running the same fixed benchmark in both placements so you can compare request success, latency, and Kubernetes CPU telemetry.

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
# ================================================================================
3+
# FIXED, DO NOT MODIFY THIS FILE
4+
# ================================================================================
5+
weight: 21 # Set to always be larger than the content in this path to be at the end of the navigation.
6+
title: "Next Steps" # Always the same, html page title.
7+
layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing.
8+
---

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

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: Understand mixed placement for a storefront AI assistant
3+
description: Learn why the storefront and assistant tiers use different Axion placements before you build and deploy the assistant.
4+
weight: 2
5+
layout: "learningpathall"
6+
---
7+
8+
## How the application is organized
9+
10+
Modern AI applications often contain more than one workload shape. A storefront tier is steady, service-oriented, and always on. An AI assistant tier is burstier and more latency-sensitive because it performs reasoning work only when users ask for help.
11+
12+
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. You add the missing `shoppingassistantservice`, run it on N4A first, and then move only that assistant tier to C4A.
13+
14+
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.
15+
16+
![Architecture diagram showing Cloud Shell and Kustomize deploying Online Boutique to GKE on Axion. Storefront microservices run on N4A, and the shopping assistant runs on C4A with access to cart, catalog, and a local Ollama Gemma model.#center](images/mixed-placement-agentic-storefront-on-axion.png "Mixed-placement agentic storefront on Axion")
17+
18+
The diagram shows the final mixed-placement pattern you build toward. The storefront images already run on Arm nodes, and the assistant image you build later is `linux/arm64` because both target node pools are Arm-based.
19+
20+
## How the storefront already runs on Arm
21+
22+
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`.
23+
24+
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.
25+
26+
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/).
27+
28+
Inspect a public multi-architecture image manifest:
29+
30+
```bash
31+
docker buildx imagetools inspect docker.io/library/python:3.12-slim
32+
```
33+
34+
The output is similar to:
35+
36+
```output
37+
Name: docker.io/library/python:3.12-slim
38+
MediaType: application/vnd.oci.image.index.v1+json
39+
40+
Manifests:
41+
Platform: linux/amd64
42+
Platform: linux/arm64/v8
43+
```
44+
45+
The exact digest values can differ. The important signal is that one image reference can include an Arm-compatible variant. You confirm the storefront image reference from the source tree in the setup step.
46+
47+
## How the assistant works
48+
49+
The `shoppingassistantservice` is the AI layer for the application. It runs as its own Kubernetes service and receives assistant requests from the storefront frontend.
50+
51+
The assistant uses live storefront services as tools:
52+
53+
- `search_catalog` queries `productcatalogservice`.
54+
- `get_product_details` fetches a specific product from the live catalog.
55+
- `get_cart` reads the current cart from `cartservice`.
56+
- `add_to_cart` updates the cart only after user confirmation.
57+
58+
The assistant sends grounded context to a local Ollama sidecar in the same pod. The sidecar runs the `gemma3:1b-it-qat` model for the reasoning step.
59+
60+
This design keeps the comparison focused. You don't add a separate vector database, retrieval pipeline, or hosted large language model API. You move the assistant logic and local reasoning runtime together as one AI tier.
61+
62+
## How requests flow through the storefront
63+
64+
When a shopper uses the assistant, the request follows this path:
65+
66+
1. The browser sends the request to `frontend`.
67+
2. `frontend` forwards the request to `shoppingassistantservice`.
68+
3. The assistant calls live services such as `productcatalogservice` and `cartservice`.
69+
4. The assistant sends grounded context to the local Ollama sidecar.
70+
5. The assistant returns the response through `frontend`.
71+
72+
The assistant is agentic because it does more than generate text. It uses application tools, keeps short-lived session state, and asks for confirmation before it calls `cartservice` to update the cart.
73+
74+
## What you've learned and what's next
75+
76+
You've learned why the storefront tier and AI assistant tier use different Axion placements. You also saw how Arm-compatible image variants make the existing storefront portable to Axion nodes.
77+
78+
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‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: Build and push the assistant image
3+
description: Build the shopping assistant container image for arm64 and push it to Artifact Registry for deployment on Axion.
4+
weight: 6
5+
layout: "learningpathall"
6+
---
7+
8+
## Build one Arm image for both Axion placements
9+
10+
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.
11+
12+
{{% notice Note %}}
13+
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`.
14+
{{% /notice %}}
15+
16+
If you opened a new terminal, return to the source tree and restore the required variables:
17+
18+
```bash
19+
cd "${HOME}/n4a-c4a/microservices-demo"
20+
21+
export PROJECT_ID="$(gcloud config get-value project)"
22+
export ARTIFACT_REGION="us-central1"
23+
export ARTIFACT_REPO="axion-workshop"
24+
```
25+
26+
## Define the image name
27+
28+
Create one reusable image path:
29+
30+
```bash
31+
export ASSISTANT_IMAGE_REPO="${ARTIFACT_REGION}-docker.pkg.dev/${PROJECT_ID}/${ARTIFACT_REPO}/shoppingassistantservice"
32+
export ASSISTANT_IMAGE_TAG="lab-v1"
33+
export ASSISTANT_IMAGE="${ASSISTANT_IMAGE_REPO}:${ASSISTANT_IMAGE_TAG}"
34+
35+
echo "${ASSISTANT_IMAGE}"
36+
```
37+
38+
## Verify Docker and Buildx
39+
40+
Confirm that Docker and Buildx are available:
41+
42+
```bash
43+
docker version
44+
docker buildx version
45+
```
46+
47+
If Docker is not running in your environment, start it before you continue.
48+
49+
## Configure Artifact Registry authentication
50+
51+
Configure Docker authentication for Artifact Registry:
52+
53+
```bash
54+
gcloud auth configure-docker "${ARTIFACT_REGION}-docker.pkg.dev" --quiet
55+
```
56+
57+
Cloud Shell might print a warning about existing credential helpers. You can continue if the command finishes successfully.
58+
59+
## Create a Buildx builder
60+
61+
Create or reuse a Buildx builder:
62+
63+
```bash
64+
if docker buildx inspect axion-builder >/dev/null 2>&1; then
65+
docker buildx use axion-builder
66+
else
67+
docker buildx create --name axion-builder --use
68+
fi
69+
70+
docker buildx inspect --bootstrap
71+
```
72+
73+
The output should show a working builder. Confirm that the `Platforms` line includes `linux/arm64` before you continue.
74+
75+
## Build and push the assistant image
76+
77+
Build the assistant image for `linux/arm64` and push it to Artifact Registry:
78+
79+
```bash
80+
docker buildx build --platform linux/arm64 -t "${ASSISTANT_IMAGE}" --push src/shoppingassistantservice
81+
```
82+
83+
The command packages the Flask assistant service, protobuf stubs, and Python dependencies. The important success signal is that the build finishes and pushes the image to your Artifact Registry path.
84+
85+
## Verify the pushed tag
86+
87+
List the tags for the assistant image:
88+
89+
```bash
90+
gcloud artifacts docker tags list "${ASSISTANT_IMAGE_REPO}"
91+
```
92+
93+
The output should include the `lab-v1` tag.
94+
95+
## What you've accomplished
96+
97+
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.
98+
99+
Next, you'll create the N4A overlay and add the assistant to the running storefront.

0 commit comments

Comments
 (0)