Merge pull request #2521 from jasonrandrews/review

jasonrandrews · web-flow · commit 656b58720517 · 2025-11-07T17:02:05.000-06:00
review online boutique app on GKE
diff --git a/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/_index.md b/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/_index.md
@@ -1,25 +1,25 @@
 ---
 title: From x86 to Arm on GKE - Build, Deploy, and Migrate with Google Axion
+
 draft: true
 cascade:
     draft: true
 
 minutes_to_complete: 90
 
-who_is_this_for: This learning path is for cloud, platform, and SRE engineers operating Kubernetes on Google Cloud who need a prescriptive path to build multi‑architecture images and migrate services from x86 to Arm (Google Axion) using production‑grade practices.
+who_is_this_for: This is an advanced topic for cloud, platform, and site reliability engineers operating Kubernetes on Google Cloud who need a prescriptive path to build multi-architecture images and migrate services from x86 to Arm using Google Axion processors.
 
 learning_objectives:
-    - Prepare Dockerfiles for multi-architecture builds (minimal, safe edits so services compile and run on amd64 & arm64).
-    - Create a dual-architecture GKE Standard cluster with two node pools, amd64 and arm64 (Axion-based C4A).
-    - Build and publish multi-architecture images to Artifact Registry using Docker Buildx (Kubernetes driver) - BuildKit pods run natively on both pools (no QEMU or extra build VMs).
-    - Deploy to amd64 first, then migrate to arm64 using Kustomize overlays and progressive rollout.
-    - Optionally automate builds and rollouts end-to-end with Cloud Build and Skaffold.
+    - Prepare Dockerfiles for multi-architecture builds by adding arm64 support
+    - Create a dual-architecture GKE standard cluster with two node pools, amd64 and arm64
+    - Build and publish multi-architecture images to Artifact Registry using Docker Buildx without using QEMU to emulate Arm instructions
+    - Deploy a Kubernetes application amd64 first, then migrate to arm64 using Kustomize overlays and progressive rollout
+    - Optionally automate builds and rollouts with Cloud Build and Skaffold
     
 prerequisites:
-    - A [Google Cloud account](https://console.cloud.google.com/) with billing enabled. 
-    - Cloud Shell access (used as the control plane, includes gcloud, kubectl, and Docker Buildx).
-    - (Optional if not using Cloud Shell) A Linux/macOS workstation with Docker (Buildx enabled), kubectl, the Google Cloud CLI (gcloud), and Git.
-    - Basic familiarity with Docker, Kubernetes, and gcloud.
+    - A [Google Cloud account](https://console.cloud.google.com/) with billing enabled
+    - A local Linux or macOS computer or Cloud Shell access with Docker, Kubernetes CLI (kubectl), Google Cloud CLI (gcloud), and Git installed
+    - Basic familiarity with Docker, Kubernetes, and gcloud
 
 author: 
    - Rani Chowdary Mandepudi
@@ -43,7 +43,7 @@ further_reading:
         title: GKE documentation
         link: https://cloud.google.com/kubernetes-engine/docs
         type: documentation
-    -  resource:
+    - resource:
         title: Create Arm-based clusters and node pools 
         link: https://cloud.google.com/kubernetes-engine/docs/how-to/create-arm-clusters-nodes
         type: documentation
diff --git a/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/cloud-build.md b/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/cloud-build.md
@@ -1,28 +1,35 @@
 ---
-title:  Automate builds and rollout with Cloud Build & Skaffold
+title: Automate builds and rollout with Cloud Build and Skaffold
 weight: 6
 
 ### FIXED, DO NOT MODIFY
 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. In this page 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. 
 
-## What this pipeline does
-- Authenticates Docker to **Artifact Registry**.
-- Builds and pushes **amd64 + arm64** images with **Docker Buildx** (QEMU enabled in the runner).
-- Connects to your **GKE** cluster.
-- Applies the **amd64** Kustomize overlay, verifies pods, then applies the **arm64** overlay and verifies again.
-- Prints the **frontend-external** LoadBalancer IP at the end. 
+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.
 
+## What does this pipeline do?
+
+The pipeline performs the following steps:
+
+- Authenticates Docker to your Artifact Registry
+- Builds and pushes amd64 and arm64 images with Docker Buildx, with QEMU enabled in the runner
+- 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 earlier pages (GAR created, images path/tag decided, GKE cluster with amd64 + arm64 node pools, and Kustomize overlays present).
+Run this from the microservices-demo repo root in Cloud Shell. Ensure you completed the previous steps. 
 {{% /notice %}}
 
-## Grant IAM to the Cloud Build service account
+## Grant IAM permission to the Cloud Build service account
+
 Cloud Build runs as a per-project service account: `<PROJECT_NUMBER>@cloudbuild.gserviceaccount.com`. Grant it the minimal roles needed to build, push, log, and interact with GKE.
 
+Grant the required roles:
+
 ```bash
 # Uses env vars set earlier: PROJECT_ID, REGION, CLUSTER_NAME, GAR
 PROJECT_NUMBER="$(gcloud projects describe "${PROJECT_ID}" --format='value(projectNumber)')"
@@ -37,9 +44,11 @@ gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:
 gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${CLOUD_BUILD_SA}" --role="roles/logging.logWriter" --condition=None --quiet
 ```
 
-## Update skaffold.yaml for deploy-only
+## Update the Skaffold configuration
+
+Create a `skaffold.yaml` file for Cloud Build. This lets Cloud Build handle image builds and uses Skaffold only to apply the Kustomize overlays.
 
-This will let Cloud Build handle image builds and use Skaffold only to apply the Kustomize overlays.
+Create the configuration:
 
 ```yaml
 # From the repo root (microservices-demo)
@@ -97,9 +106,11 @@ YAML
 
 ```
 
-##  Create cloudbuild.yaml
+## Create a YAML file for Cloud Build 
+
+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.  ￼
 
-This pipeline installs `Docker + 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.
 
 ```yaml
 cat > cloudbuild.yaml <<'YAML'
@@ -239,7 +250,7 @@ In production, add one build step per microservice (or a loop) and enable cachin
 
 ## Run the pipeline
 
-From the repo root:
+Submit the build from the root of the repository: 
 
 ```bash
 gcloud builds submit --config=cloudbuild.yaml --substitutions=_CLUSTER="${CLUSTER_NAME}",_REGION="${REGION}",_REPO="${GAR}"
@@ -251,4 +262,4 @@ The final step prints in the build description:
 Open http://<EXTERNAL-IP> in your browser.
 ```
 
-Open that URL to load the storefront and confirm the full build - deploy - migrate flow is automated.
+Open the URL to load the storefront and confirm the full build, deploy, and migrate flow is automated.
diff --git a/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/gke-build-push.md b/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/gke-build-push.md
@@ -1,18 +1,22 @@
 ---
-title: Provision a Dual-Arch GKE Cluster and Publish Multi-Arch Images
+title: Provision a dual-architecture GKE cluster and publish images
 weight: 4
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-Now create a **GKE cluster** with **two node pools** (amd64 & 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 involved.
+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. 
 
-#### Networking (VPC-native / IP aliasing)
+Each architecture uses its own BuildKit pod, and no QEMU emulation is required.
 
-GKE uses **VPC-native (IP aliasing)** and requires **two secondary ranges** on the chosen subnet: one for **Pods** and one for **Services**.
-- **Default VPC:** Skip this step. GKE will create the secondary ranges automatically.
-- **Custom VPC/subnet:** Set variables and add/verify secondary ranges:
+## Networking configuration
+
+GKE uses VPC-native (IP aliasing) and requires two secondary ranges on the chosen subnet: one for Pods and one for Services.
+
+For the default VPC, GKE creates the secondary ranges automatically.
+
+Run the commands below in your terminal, adjusting the environment variables as needed for your account:
 
 ```bash
 # Set/confirm network variables (adjust to your environment)
@@ -29,13 +33,14 @@ gcloud compute networks subnets list --network "${NETWORK}" --regions "${REGION}
 # If missing, add two secondary ranges (example CIDRs; ensure no overlap)
 gcloud compute networks subnets update "${SUBNET}" --region "${REGION}" --add-secondary-ranges ${POD_RANGE_NAME}=10.8.0.0/14,${SVC_RANGE_NAME}=10.4.0.0/20
 ```
-This avoids users on default VPC accidentally setting NETWORK/SUBNET and passing the wrong flags later.
 
-### Create the GKE cluster
+This approach prevents users on the default VPC from accidentally setting NETWORK/SUBNET variables and passing incorrect flags later.
+
+## Create the GKE cluster
 
-Create a GKE Standard cluster with VPC-native (IP aliasing) enabled and no default node pool (you'll add amd64 and arm64 pools next). The command below works for both default and custom VPCs: if NETWORK, SUBNET, and the secondary range variables are unset, GKE uses the default VPC and manages ranges automatically.
+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.
 
-Create the cluster with no default node pool and add node pools explicitly.
+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)
@@ -46,7 +51,7 @@ export CLUSTER_NAME="${CLUSTER_NAME:-gke-multi-arch-cluster}"
 gcloud container clusters create "${CLUSTER_NAME}" --region "${REGION}" --enable-ip-alias --num-nodes "1" --machine-type "e2-standard-2" ${NETWORK:+--network "${NETWORK}"} ${SUBNET:+--subnetwork "${SUBNET}"} ${POD_RANGE_NAME:+--cluster-secondary-range-name "${POD_RANGE_NAME}"} ${SVC_RANGE_NAME:+--services-secondary-range-name "${SVC_RANGE_NAME}"}
 ```
 
-Create an x86 (amd64) pool and an Arm (arm64) pool. Use machine types available in your region (e.g., c4-standard-* for x86 and c4a-standard-* for Axion). 
+Now create an x86 (amd64) pool and an Arm (arm64) pool. Use machine types available in your region. The commands below use `c4-standard-*` for x86 and `c4a-standard-*` for Axion:
 
 ```bash
 # amd64 pool (x86)
@@ -67,14 +72,14 @@ kubectl config current-context
 kubectl get nodes -o wide
 kubectl get nodes -L kubernetes.io/arch
 ```
-You should see nodes for both architectures. In zonal clusters (or when a pool has --num-nodes=1 in a single zone), expect one amd64 and one arm64 node. In regional clusters, --num-nodes is per zone, with three zones you'll see three amd64 and three arm64 nodes.
 
-### Create the Buildx builder on GKE (native, one pod per arch)
+You should see nodes for both architectures. In zonal clusters (or when a pool has `--num-nodes=1` in a single zone), expect one amd64 and one arm64 node. In regional clusters, `--num-nodes` is per zone, so with three zones you'll see three amd64 and three arm64 nodes.
 
-Now run a BuildKit pod on an amd64 node and another on an arm64 node. Buildx will route each platform's build to the matching pod - native builds, no emulation.
+## Create the Buildx builder on GKE 
 
-```bash
+Now run a BuildKit pod on an amd64 node and another on an arm64 node. Buildx routes each platform's build to the matching pod. These are native builds with no QEMU emulation.
 
+```bash
 # Namespace for BuildKit pods
 kubectl create ns buildkit --dry-run=client -o yaml | kubectl apply -f -
 
@@ -87,14 +92,16 @@ docker buildx create --driver kubernetes --append --name gke-native --driver-opt
 # Bootstrap and verify pods
 docker buildx inspect gke-native --bootstrap
 kubectl -n buildkit get pods -o wide
-
 ```
-{{% notice Note %}}
-You will now have a multi-node Buildx builder named gke-native. Each BuildKit pod is pinned to a specific CPU arch via nodeselector.
-{{% /notice %}}
 
-### Build & push all services (multi-arch manifest lists)
-Build every service for linux/amd64 and linux/arm64 using the GKE-backed builder:
+You now have a multi-node Buildx builder named `gke-native`. Each BuildKit pod is pinned to a specific CPU architecture using node selectors.
+
+## Build and push all services
+
+You can now build all services for `linux/amd64` and `linux/arm64` using the GKE-backed builder.
+
+Run the commands:
+
 ```bash
 cat << 'EOF' > build-all-multiarch.sh
 #!/usr/bin/env bash
@@ -132,23 +139,28 @@ EOF
 chmod +x build-all-multiarch.sh
 ./build-all-multiarch.sh
 ```
-Each :v1 you push is a manifest list that points to two images (one per arch).
 
-### Verify manifest lists and per-arch pulls
+Each tag you push is a manifest list that points to two images, one per architecture.
+
+## Verify manifest lists and per-arch pulls
 
 List pushed images:
 
 ```bash
 gcloud artifacts docker images list "${GAR}"
 ```
 
-Inspect one tag (should show both platforms):
+Inspect one tag to confirm it shows both platforms:
+
 ```bash
 docker buildx imagetools inspect "${GAR}/adservice:v1"
 ```
 
-Expected Output:
-```
+The output is:
+
+```output
 Platform: linux/amd64
 Platform: linux/arm64
 ```
+
+You are now ready to prepare the application manifests and deploy the application.
diff --git a/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/gke-deploy.md b/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/gke-deploy.md
@@ -1,18 +1,20 @@
 ---
-title: Prepare Manifests and Deploy on GKE(migration to arm64) 
+title: Prepare manifests and deploy on GKE
 weight: 5
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-Point the app manifests at your Artifact Registry images, add Kustomize overlays to target node architecture, deploy to the x86 (amd64) pool, then migrate the same workloads to the Arm (arm64) pool.
+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.
 
-### Prepare deployment manifests
+## Prepare deployment manifests
 
-Replace public sample image references with your Artifact Registry path and **tag(:v1)**, then create Kustomize overlays to select nodes by architecture.
+Replace sample image references with your Artifact Registry path and tag, then create Kustomize overlays to select nodes by architecture.
 
-#### Point base manifests at your images
+### Point base manifests at your images
+
+Replace the image references with your references:
 
 ```bash
 # Replace the sample repo path with your GAR (from earlier: ${GAR})
@@ -27,13 +29,17 @@ find kustomize/base -name "*.yaml" -type f -exec \
 grep -r "${GAR}" kustomize/base/ || true
 ```
 
-#### Create node-selector overlays (amd64 and arm64)
+### Create node-selector overlays
+
+Create node-selector overlays for targeting specific architectures.
+
+First, create the directories:
 
 ```bash
 mkdir -p kustomize/overlays/amd64 kustomize/overlays/arm64
 ```
 
-**amd64 overlay**
+Create the amd64 overlay:
 
 ```bash
 cat << 'EOF' > kustomize/overlays/amd64/kustomization.yaml
@@ -53,7 +59,8 @@ cat << 'EOF' > kustomize/overlays/amd64/node-selector.yaml
 EOF
 ```
 
-**arm64 overlay**
+Create the arm64 overlay:
+
 ```bash
 cat << 'EOF' > kustomize/overlays/arm64/kustomization.yaml
 resources:
@@ -72,11 +79,13 @@ cat << 'EOF' > kustomize/overlays/arm64/node-selector.yaml
 EOF
 ```
 
-Result: the **base** references your images, and **overlays** control per-arch placement.
+You now have updated manifests that reference your container images and Kustomize overlays that target specific CPU architectures.
 
-### Deploy to the x86 (amd64) pool
+## Deploy to the x86 (amd64) pool
 
-Render the amd64 Kustomize overlay (adds nodeSelector: kubernetes.io/arch=amd64) and apply it to the cluster. Run from the repository root after updating base manifests to your ${GAR} and setting your kube-context to this cluster.
+Render the amd64 Kustomize overlay (adds `nodeSelector: kubernetes.io/arch=amd64`) and apply it to the cluster. 
+
+Run from the repository root after updating base manifests and setting your kube-context to this cluster:
 
 ```bash
 kubectl kustomize kustomize/overlays/amd64 | kubectl apply -f -
@@ -90,43 +99,44 @@ kubectl get pods -o wide
 kubectl get pods -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,STATUS:.status.phase --no-headers
 ```
 
-Pods should be scheduled on nodes labelled `kubernetes.io/arch=amd64`.
+Pods should be scheduled on nodes labeled `kubernetes.io/arch=amd64`.
 
-### Migrate to the Arm (arm64) pool
+## Migrate to the Arm (arm64) pool
 
 Apply the arm64 overlay to move workloads: 
 
 ```bash
 kubectl kustomize kustomize/overlays/arm64 | kubectl apply -f -
 ```
 
-Verify pods have shifted to arm64 nodes:
+Verify pods have moved to arm64 nodes:
 
 ```bash
 kubectl get pods -o wide
 ```
 
 You should see pods now running on nodes where `kubernetes.io/arch=arm64`.
 
-### Verify external access
+## Verify external access
 
 Get the LoadBalancer IP and open the storefront:
 
 ```bash
 kubectl get svc frontend-external 
 ```
 
-Expected columns include EXTERNAL-IP:
+The output is similar to:
 
-```
+```output
 NAME               TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)        AGE
 frontend-external  LoadBalancer   10.12.3.45     34.123.45.67     80:31380/TCP   3m
 ```
 
-Copy the EXTERNAL-IP value, and open it in a new browser tab:
-```
+Copy the EXTERNAL-IP value and open it in a new browser tab:
+
+```console
 http://<EXTERNAL-IP>
 ```
 
-The microservices storefront should load confirming that your application is accessible and functional on the Arm64 node pool. 
+The microservices storefront loads, confirming that your application is accessible and functional on the arm64 node pool.
 
diff --git a/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/multi-arch-images.md b/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/multi-arch-images.md
diff --git a/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/project-setup.md b/content/learning-paths/servers-and-cloud-computing/gke-multi-arch-axion/project-setup.md
