Update GKE multi-arch Axion documentation for clarity and accuracy

Author: madeline-underwood

content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Migrate x86 workloads to Arm on GKE with Google Axion
+title: Migrate x86 workloads to Arm on Google Kubernetes Engine with Axion processors 
 
 minutes_to_complete: 90
 
@@ -36,7 +36,7 @@ tools_software_languages:
 
 further_reading:
     - resource:
-        title: GKE documentation
+        title: Google Kubernetes Engine documentation
         link: https://cloud.google.com/kubernetes-engine/docs
         type: documentation
     - resource:

content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/background.md

@@ -10,21 +10,20 @@ layout: "learningpathall"
 
 ## Overview 
 
-This Learning Path shows you how to migrate a microservices application from x86 to Arm on GKE using multi-architecture container images. You'll work with Google's Online Boutique, a sample application built with multiple programming languages. The migration requires no code changes, making it a straightforward example of moving to Arm-based Google Axion processors.
+This Learning Path shows you how to migrate a microservices application from x86 to Arm on Google Kubernetes Engine (GKE) using multi-architecture container images. You'll work with Google's Online Boutique, a sample application built with multiple programming languages. The migration requires no code changes, making it a straightforward example of moving to Arm-based Google Axion processors.
 
 
 ## Why use Google Axion processors for GKE?
 
-Google Axion processors bring modern Arm-based compute to GKE, delivering strong price-performance and energy efficiency for cloud-native, scale-out services. With multi-architecture images and mixed node pools, you can migrate services from x86 to Arm gradually, with no major code changes.
+Google Axion processors bring modern Arm-based compute to GKE. You get strong price-performance and energy efficiency for cloud-native, scale-out services. With multi-architecture images and mixed node pools, you can migrate services from x86 to Arm gradually, with no major code changes.
 
-### What is Google Axion?
+## What is Google Axion?
 
 [Google Axion](https://cloud.google.com/blog/products/compute/introducing-googles-new-arm-based-cpu) is Google Cloud's Arm-based CPU family built on Arm Neoverse, for general-purpose, cloud-native services and CPU-based AI. You can deploy it for workloads like web apps and web servers, containerized microservices, open-source databases, in-memory caches, data analytics, media processing, and CPU-based AI inference and data processing. On GKE, you can leverage Axion through the C4A and N4A VM families, paired with Google's Titanium offloads to free CPU cycles for application work.
 
-### Why migrate to Arm on GKE?
+## Why migrate to Arm on GKE?
 There are three clear benefits to consider when considerring migrating to Arm on GKE:
 
-
 - Price-performance: you can run more workload per unit of cost, which is particularly valuable for scale-out services that need to handle increasing traffic efficiently.
 - Energy efficiency: you reduce power usage for always-on microservices, lowering both operational costs and environmental impact.
 - Compatibility: you can migrate containerized applications with build and deploy changes only—no code rewrites are required, making the transition straightforward.
@@ -43,7 +42,7 @@ You'll migrate the Online Boutique application from x86 to Arm step by step. You
 
 The migration process involves these steps:
 
-- Open Google Cloud Shell and set the environment variables.
+- Open Google Cloud Shell and set up the environment variables.
 - Enable required APIs, create an Artifact Registry repository, and authenticate Docker.
 - Create a GKE Standard cluster with an amd64 node pool and add an arm64 (Axion-based C4A) node pool.
 - Create a Buildx (Kubernetes driver) builder that targets both pools, then build and push multi-architecture images (amd64 and arm64) natively using BuildKit pods.

content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/cloud-build.md

@@ -6,9 +6,11 @@ weight: 7
 layout: learningpathall
 ---
 
-Google [**Cloud Build**](https://cloud.google.com/build/docs/set-up) is a managed CI/CD service that runs your containerized build and deploy steps in isolated runners. 
+## Automate the deployment with Cloud Build
 
-In this section, you'll automate the flow you performed manually: build multi-arch images, deploy to GKE on amd64, then migrate to arm64, and print the app's external IP.
+Google [Cloud Build](https://cloud.google.com/build/docs/set-up) is a managed CI/CD service that runs your containerized build and deploy steps in isolated runners. 
+
+In this section, you automate the flow you performed manually: build multi-arch images, deploy to GKE on amd64, then migrate to arm64, and print the app's external IP.
 
 ## What does this pipeline do?
 
@@ -19,9 +21,8 @@ The pipeline performs the following steps:
 - Connects to your GKE cluster
 - Applies the amd64 Kustomize overlay, verifies pods, then applies the arm64 overlay and verifies pods again
 - Prints the frontend-external LoadBalancer IP at the end
-
 {{% notice Tip %}}
-Run this from the microservices-demo repo root in Cloud Shell. Ensure you completed the previous steps. 
+Run this command from the `microservices-demo` repository root in Cloud Shell. Make sure you've completed the previous steps.
 {{% /notice %}}
 
 ## Grant IAM permission to the Cloud Build service account
@@ -110,7 +111,7 @@ YAML
 
 This pipeline installs Docker with Buildx in the runner, enables QEMU, builds two services as examples (extend as desired), connects to your cluster, deploys to amd64, verifies, migrates to arm64, verifies, and prints the external IP.  
 
-Run the commands to create the `cloudbuild.yaml` file.
+Run the commands to create the `cloudbuild.yaml` file:
 
 ```yaml
 cat > cloudbuild.yaml <<'YAML'
@@ -263,3 +264,33 @@ Open http://<EXTERNAL-IP> in your browser.
 ```
 
 Open the URL to load the storefront and confirm the full build, deploy, and migrate flow is automated.
+
+## What you've accomplished
+
+Congratulations! You've successfully automated the entire build, deploy, and migration workflow using Cloud Build and Skaffold. Your multi-architecture application runs natively on Arm-powered GKE nodes, and you can deploy updates automatically with a single command.
+
+You've learned how to:
+
+- Update Dockerfiles to support native builds on both amd64 and arm64 architectures
+- Create a dual-architecture GKE cluster with separate node pools for each platform
+- Build multi-architecture container images using Docker Buildx with native BuildKit pods
+- Deploy applications to amd64 nodes, then migrate them to arm64 nodes using Kustomize overlays
+- Automate the entire workflow with Cloud Build and Skaffold for continuous deployment
+
+## What's next
+
+Now that you have a working multi-architecture deployment pipeline, you can explore these next steps:
+
+- Optimize for Arm performance: profile your services on arm64 nodes to identify optimization opportunities. Arm Neoverse processors offer different performance characteristics than x86, so you might discover new ways to improve throughput or reduce latency.
+
+- Expand your migration: add build steps for the remaining Online Boutique services. You can extend the `cloudbuild.yaml` file to build all services, not just the two examples provided.
+
+- Implement progressive rollouts: use Skaffold profiles and Cloud Build triggers to set up canary deployments or blue-green deployments across architectures. This lets you test changes on a subset of traffic before rolling out to all users.
+
+- Monitor architecture-specific metrics: set up monitoring dashboards in Cloud Monitoring to compare performance, resource usage, and cost between amd64 and arm64 deployments. This data helps you make informed decisions about your migration strategy.
+
+- Explore cost optimization: review your GKE cluster costs and consider rightsizing your node pools. Arm-based C4A instances often provide better price-performance for cloud-native workloads, so you might reduce costs while maintaining or improving performance.
+
+
+
+

content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/gke-build-push.md

@@ -1,11 +1,13 @@
 ---
-title: Provision a dual-architecture GKE cluster and publish images
+title: Build and deploy multi-architecture images on GKE
 weight: 5
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
+## Create a cluster and build the multi-arch images
+
 You are ready to create a GKE cluster with two node pools (amd64 and arm64), then build and push multi-arch images natively on those node pools. 
 
 Each architecture uses its own BuildKit pod, and no QEMU emulation is required.
@@ -40,7 +42,7 @@ This approach prevents users on the default VPC from accidentally setting NETWOR
 
 Create a GKE Standard cluster with VPC-native (IP aliasing) enabled and no default node pool. You'll add amd64 and arm64 pools in the next step.
 
-The command below works for both default and custom VPCs. If the NETWORK, SUBNET, and secondary range variables are unset, GKE uses the default VPC and manages ranges automatically.
+The command below works for both default and custom VPCs. If the NETWORK, SUBNET, and secondary range variables are unset, GKE uses the default VPC and manages ranges automatically:
 
 ```bash
 # Cluster vars (reuses earlier PROJECT_ID/REGION/ZONE)

content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/gke-deploy.md

@@ -5,14 +5,14 @@ weight: 6
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
+## Prepare deployment manifests
 
-You'll now configure the application manifests to use your Artifact Registry images and create Kustomize overlays for different CPU architectures. This allows you to deploy the same application to both x86 and Arm node pools.
+You'll now configure the application manifests to use your Artifact Registry images and create Kustomize overlays for different CPU architectures. This allows you to deploy the same application to both x86 and Arm node pools by replacing sample image references with your Artifact Registry path and tag, then creating overlays to select nodes by architecture.
 
-## Prepare deployment manifests
 
-Replace sample image references with your Artifact Registry path and tag, then create Kustomize overlays to select nodes by architecture.
+## Update base manifests to use your images
 
-## Point base manifests at your images
+Replace the sample image references in the base manifests with your Artifact Registry path and tag:
 
 Replace the image references with your references:
 

content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/multi-arch-images.md

@@ -6,28 +6,35 @@ weight: 4
 layout: learningpathall
 ---
 
-With your environment set up, you're ready to modify the Online Boutique services to support multi-architecture builds.
+## Update Dockerfiles to support multi-architecture builds
 
-You will patch some Dockerfiles so they build cleanly for both architectures. In the next section, you will build and push images using a GKE-native Buildx builder.
+Now that your environment set up, you're now ready to modify the Online Boutique services to support multi-architecture builds.
+
+You will patch some Dockerfiles so they build cleanly for both architectures. 
 
 ## Services to edit
 
-Most services already build for both architectures.
+Most services in Online Boutique already build for both architectures without any changes.
 
-The four listed below need small changes:
+Four services need small updates:
 
 - emailservice
 - recommendationservice
 - loadgenerator
 - cartservice
 
-These edits don't change application behavior, they only ensure the right compiler headers and runtime libraries are present per architecture. This includes Python native wheels for email/recommendation/loadgen, and system `protoc` for the .NET cartservice.
+These edits ensure the correct compiler headers and runtime libraries are present for each architecture. The changes include:
+
+- Python native wheels for emailservice, recommendationservice, and loadgenerator
+- System `protoc` for the .NET cartservice
+
+These updates don't change application behavior.
 
 {{% notice Note %}}
 Production migrations begin with assessing cross-architecture compatibility for each service (base images, native extensions such as CGO/JNI, platform-specific packages, and CI build targets). This section demonstrates minor Dockerfile edits for four representative services. In the referenced Online Boutique release, the remaining services generally build for both **amd64** and **arm64** without modification.
 {{% /notice %}}
 
-### Update the emailservice Dockerfile
+## Update the emailservice Dockerfile
 
 You can review the [emailservice Dockerfile](https://raw.githubusercontent.com/GoogleCloudPlatform/microservices-demo/refs/heads/main/src/emailservice/Dockerfile) before replacing it.
 
@@ -73,21 +80,18 @@ EOF
 
 Here is a summary of the changes:
 
-- **BuildKit syntax** unlocks `--mount=type=cache` to speed rebuilds.
-- **TARGETPLATFORM** lets Buildx set linux/amd64 vs linux/arm64 explicitly.
-- **Dev vs runtime packages:** build stage compiles native wheels; final stage keeps only needed shared libs.
-- **`--prefer-binary`** avoids source builds when wheels exist (more reliable across arches).
-- **Removed extra `apk update`** since `apk add --no-cache` already avoids stale indexes & caches.
+- The updated Dockerfile uses BuildKit syntax to enable cache mounts, which speed up rebuilds. 
+- The `TARGETPLATFORM` argument allows Buildx to explicitly set the target architecture (either `linux/amd64` or `linux/arm64`). The build follows a two-stage approach: the builder stage compiles native wheels with necessary development packages, while the final runtime stage includes only the required shared libraries. 
+- The `--prefer-binary` flag helps avoid building from source when pre-built wheels are available, making builds more reliable across architectures. The update also removes the extra `apk update` command because `apk add --no-cache` already handles index updates without creating a cache.
 
-## Apply updates to the other three services
+## Apply updates to recommendationservice, loadgenerator, and cartservice
 
 Run the following sed commands to automatically patch the remaining Dockerfiles.
 
 ### Update the recommendationservice Dockerfile
+You can review the [recommendationservice Dockerfile](https://raw.githubusercontent.com/GoogleCloudPlatform/microservices-demo/refs/heads/main/src/recommendationservice/Dockerfile) before modifying it.
 
-You can review the [recommendationservice Dockerfile](https://raw.githubusercontent.com/GoogleCloudPlatform/microservices-demo/refs/heads/main/src/recommendationservice/Dockerfile) before modifying it. 
-
-Paste the command below to your terminal to update the file with the required multi-architecture changes.
+Run the following command to update the file with the required multi-architecture changes:
 
 ```bash
 sed -i \
@@ -101,17 +105,13 @@ sed -i \
   src/recommendationservice/Dockerfile
 ```
 
-Here is a summary of the changes:
-
-- Make the base image architecture-aware
-- Let native wheels build cleanly
-- Keep the runtime slim & predictable
+The three key changes are to make the base image architecture-aware, let native wheels build cleanly, and keep the runtime slim and predictable.
 
 ### Update loadgenerator Dockerfile
 
 You can review the [loadgenerator Dockerfile](https://raw.githubusercontent.com/GoogleCloudPlatform/microservices-demo/refs/heads/main/src/loadgenerator/Dockerfile) before modifying it. 
 
-Paste the command below to your terminal to run `sed` to update the file with the required multi-architecture changes.
+Run the following command to update the file with the required multi-architecture changes:
 
 ```bash
 FILE=src/loadgenerator/Dockerfile
@@ -135,17 +135,12 @@ sed -i -E \
   "$FILE"
 ```
 
-Here is a summary of the changes:
-
-- Make the base image architecture-aware
-- Fix native build/run deps
-- Keep runtime lean and no flags/app code changed
+The changes focus on three key areas. First, make the base image architecture-aware so it automatically selects the correct variant for your platform. Second, fix native build and runtime dependencies to ensure they match the target architecture. Third, keep the runtime environment lean—you don't need to change any flags or application code.
 
 ### Update cartservice Dockerfile
 
 You can review the [carkservice Dockerfile](https://raw.githubusercontent.com/GoogleCloudPlatform/microservices-demo/refs/heads/main/src/cartservice/src/Dockerfile) before replacing it. 
-
-Paste the command below to your terminal to update the file with the required multi-architecture changes.
+Run the following command to update the file with the required multi-architecture changes:
 
 ```bash
 FILE=src/cartservice/src/Dockerfile
@@ -164,14 +159,17 @@ sed -i \
 
 Here is a summary of the changes:
 
-- Install the system `protoc` command
-- Force MSBuild to use the supplied `protoc` command
-- No behavioral changes
+- Install the system `protoc` compiler in the builder image
+- Configure MSBuild to use the installed `protoc` instead of downloading one
+
+These changes don't affect application behavior.
 
 {{% notice Note %}}
-`ARG TARGETPLATFORM` + `FROM --platform=$TARGETPLATFORM` is not strictly required if you always build with --platform and your base image is multi-arch. Keeping it is good practice and makes intent explicit and does not change runtime behavior.
+Using `ARG TARGETPLATFORM` and `FROM --platform=$TARGETPLATFORM` isn't strictly required when you build with `--platform` and your base image supports multiple architectures. However, keeping these declarations makes your build intent explicit and doesn't change runtime behavior.
 
 {{% /notice %}}
 
-After making the Dockerfile modification, all services now support multi-architecture builds.
+After updating these Dockerfiles, all services support multi-architecture builds. You're ready to build and push images using a GKE-native Buildx builder. Great job!
+
+
 

content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/project-setup.md

@@ -10,9 +10,9 @@ layout: "learningpathall"
 
 ## Get started in Cloud Shell
 
-Use [Cloud Shell](https://cloud.google.com/shell/docs/using-cloud-shell) to set variables, enable APIs, create Artifact Registry, authenticate Docker, and clone the sample microservices demo.
+You can use [Cloud Shell](https://cloud.google.com/shell/docs/using-cloud-shell) to set variables, enable APIs, create Artifact Registry, authenticate Docker, and clone the sample microservices demo.
 
-Make sure `kubectl`, `gcloud`, `docker`, and `git` commands are installed.
+Make sure you have the following tools installed: `kubectl`, `gcloud`, `docker`, and `git`.
 
 {{% notice Note %}}
 You can use your local macOS or Linux computer instead of Cloud Shell. Make sure the required software is installed.
@@ -41,31 +41,31 @@ gcloud config set compute/zone "${ZONE}"
 
 You'll need the environment variables in any shell you use to work on the project.
 
-### Enable required Google Cloud APIs
+## Enable the required Google Cloud APIs
 
 Enable the required APIs so the project can create GKE clusters, push and pull container images in Artifact Registry, and use Cloud Build for CI/CD:
 
 ```bash
 gcloud services enable container.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com
 ```
 
-### Create an Artifact Registry (Docker) repository
+## Create an Artifact Registry (Docker) repository
 
 Create a Docker repository in Artifact Registry in this region for pushing and pulling your multi-architecture images:
 
 ```bash
 gcloud artifacts repositories create "${REPO}" --repository-format=docker --location="${REGION}" --description="Multi-arch images for microservices demo"
 ```
 
-### Authenticate Docker to Artifact Registry
+## Authenticate Docker to Artifact Registry
 
 Authenticate Docker to Artifact Registry so you can push and pull images:
 
 ```bash
 gcloud auth configure-docker "${REGION}-docker.pkg.dev"
 ```
 
-### Clone the Online Boutique sample microservices application
+## Clone the Online Boutique sample microservices application
 
 Clone the sample application repository: