Merge pull request #2429 from jasonrandrews/review

Tech review of Buildkite Learning Path

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/buildkite-gcp/_index.md

@@ -1,30 +1,26 @@
 ---
-title: Multi-Architecture Docker builds with Buildkite on Arm-based GCP C4A Axion VMs
+title: Build multi-architecture Docker images with Buildkite on Google Axion
 
 draft: true
 cascade:
     draft: true
 
 minutes_to_complete: 40
 
-who_is_this_for: This is an introductory guide for software developers learning to build and run multi-architecture Docker images with Buildkite on Arm-based Google Cloud C4A virtual machines powered by Axion processors.
-
+who_is_this_for: This is an introductory guide for software developers learning to build and run multi-architecture Docker images with Buildkite on Arm-based Google Cloud C4A virtual machines powered by Google Axion processors.
 
 learning_objectives:
-- Provision an Arm-based SUSE SLES virtual machine on Google Cloud (C4A with Axion processors)
-- Install and configure Docker, Buildx, and the Buildkite agent
+- Provision an Arm-based virtual machine on Google Cloud running SUSE Linux Enterprise Server or Ubuntu
+- Install and configure Docker, Docker Buildx, and the Buildkite agent
 - Write a Dockerfile to containerize a simple Flask-based Python application
-- Configure a Buildkite pipeline to build multi-architecture Docker images and push them to DockerHub
-- Run and validate the application to ensure it works as expected
-
+- Configure a Buildkite pipeline to build a multi-architecture Docker image and push it to Docker Hub
+- Run the application to ensure it works as expected
 
 prerequisites:
-  - A [Google Cloud Platform (GCP)](https://cloud.google.com/free?utm_source=google&hl=en) account with billing enabled (or another supported cloud provider like Azure or AWS)
-  - Basic knowledge of Linux system administration (creating users, installing packages, managing services)
-  - Familiarity with [Docker](https://docs.docker.com/get-started/) and container concepts
-  - A [GitHub](https://github.com/) account to host your application repository
-  - Familiarity with [Buildkite concepts](https://buildkite.com/docs/tutorials/getting-started) such as agents, pipelines, secrets, and queues
-
+  - A [Google Cloud Platform (GCP)](https://cloud.google.com/free?utm_source=google&hl=en) account with billing enabled
+  - Basic knowledge of Linux system administration such as creating users, installing packages, and managing services
+  - Familiarity with Docker and container concepts
+  - A GitHub account to host your application repository
 
 author: Jason Andrews
 
@@ -39,7 +35,7 @@ armips:
 tools_software_languages:
   - Buildkite
   - Docker
-  - Buildx
+  - Docker Buildx
 
 operatingsystems:
   - Linux

content/learning-paths/servers-and-cloud-computing/buildkite-gcp/background.md

@@ -1,20 +1,20 @@
 ---
-title: Get started with Buildkite on Google Axion C4A (Arm Neoverse V2)
+title: Get started with Buildkite on Google Axion C4A instances
 
 weight: 2
 layout: "learningpathall"
 ---
 
 ## Google Axion C4A instances on Google Cloud
 
-Google Axion C4A is a family of Arm-based virtual machines powered by Google’s custom Axion CPU, which is built on Arm Neoverse V2 cores. Designed for high performance and energy efficiency, these VMs are well-suited to modern cloud workloads such as CI/CD pipelines, microservices, media processing, and general-purpose applications.
+Google Axion C4A is a family of Arm-based virtual machines powered by Google's custom Axion CPU, which is built on Arm Neoverse V2 cores. Designed for high performance and energy efficiency, these VMs are well-suited for modern cloud workloads such as CI/CD pipelines, microservices, media processing, and general-purpose applications.
 
-The C4A series can provide a cost-efficient alternative to x86 VMs while leveraging the scalability and performance characteristics of the Arm64 (AArch64) architecture on Google Cloud.
+The C4A series can provide a cost-efficient alternative to x86 VMs while leveraging the scalability and performance characteristics of the Arm architecture on Google Cloud.
 
 To learn more about Google Axion, see the blog [Introducing Google Axion Processors, our new Arm-based CPUs](https://cloud.google.com/blog/products/compute/introducing-googles-new-arm-based-cpu).
 
 ## Buildkite for CI/CD on Arm
 
-[Buildkite](https://buildkite.com/) is a flexible and scalable continuous integration and delivery (CI/CD) platform that allows you to run pipelines on your own infrastructure. By deploying Buildkite agents on Google Axion C4A VMs, you can take advantage of Arm’s performance and cost efficiency to build, test, and deploy applications—including multi-architecture Docker images.
+Buildkite is a flexible and scalable continuous integration and delivery (CI/CD) platform that allows you to run pipelines on your own infrastructure. By deploying Buildkite agents on Google Axion C4A VMs, you can take advantage of Arm's performance and cost efficiency to build, test, and deploy applications, including multi-architecture Docker images.
 
 Buildkite integrates seamlessly with version control systems such as GitHub and supports advanced workflows for cloud migration, multi-arch builds, and testing microservices. Learn more in the [Buildkite documentation](https://buildkite.com/docs).

content/learning-paths/servers-and-cloud-computing/buildkite-gcp/buildkite-agent-setup.md

@@ -6,83 +6,91 @@ weight: 5
 layout: learningpathall
 ---
 
-# Buildkite Agent Setup 
-This guide describes the steps to configure a Buildkite agent and queue after installing the Buildkite agent binary on a Google Axion C4A Arm VM.
+# Set up a Buildkite agent
+
+After installing the Buildkite agent binary on a Google Axion C4A Arm VM, you can set up and configure a Buildkite agent and queue.
 
 ## 1. Create an Agent Token
 
 Before configuring the agent, you need an agent token from your Buildkite organization.
 
-1. Log in to your **Buildkite** account (you can login with GitHub), and go to your **Organization Settings**.  
-2. Click **Agents** in the left menu.
-3. Click **Create Agent Token**.  
-4. Enter a **name** for your token, e.g., `buildkite-arm`.  
-5. Click **Create Token**.  
-6. **Copy the token** immediately – you won’t be able to see it again after leaving the page.
+1. Log in to your Buildkite account (you can login with GitHub), and go to your Organization Settings
+2. Click Agents in the left menu
+3. Click Create Agent Token  
+4. Enter a name for your token, such as `buildkite-arm`
+5. Click Create Token
+6. Copy the token immediately, you won’t be able to see it again after leaving the page.
 
-![Buildkite Dashboard alt-text#center](images/agent-token.png "Figure 1: Create Buildkite agent Token")
+![Buildkite Dashboard alt-text#center](images/agent-token.png "Create Buildkite agent Token")
 
 
 ## 2. Configure Buildkite Agent
 
-Create the configuration directory and file on your local system:
+Create the configuration directory and file on your local system with the commands below:
 
 ```console
 sudo tee /root/.buildkite-agent/buildkite-agent.cfg > /dev/null <<EOF
 token="YOUR_AGENT_TOKEN"
 tags="queue=buildkite-queue1"
 EOF
 ```
-- Replace `YOUR_AGENT_TOKEN` with the token you generated from your **Buildkite Agents page**.  
-- `tags` in Buildkite are key-value labels that let you match pipeline steps to specific agents, ensuring jobs run only on agents with the required tag.
-- The `name` field is optional; if omitted, Buildkite will assign a default name.
+
+Replace `YOUR_AGENT_TOKEN` with the token you generated from your Buildkite Agents page.  
+
+{{% notice Note %}}
+You find it easier to copy the commands above into a text file named `config-agent.sh` and run the file.
+```console
+bash ./config-agent.sh
+```
+{{% /notice %}}
+
+In Buildkite `tags` are key-value labels that let you match pipeline steps to specific agents, ensuring jobs run only on agents with the required tag.
+
+The `name` field is optional; if omitted, Buildkite will assign a default name.
 
 
 Verify the configuration:
 
 ```console
 sudo cat /root/.buildkite-agent/buildkite-agent.cfg
 ```
+
 You should see output similar to:
 
 ```output
 # The token from your Buildkite "Agents" page
 token="YOUR-GENERATED-TOKEN-VALUE"
 tags="queue=buildkite-queue1"
-
-# The name of the agent
-name="%hostname-%spawn"
-
-# The number of agents to spawn in parallel (default is "1")
-# spawn=1
-
-# The priority of the agent (higher priorities are assigned work first)
-# priority=1
 ```
+
 ## 3. Create a Queue in Buildkite
 
-1. Go to your **Buildkite Organization → Queues → Create Queue**.  
-2. Name it: `buildkite-queue1`.  
-3. Save it.  
+Now that your agent is created, you can create a queue. 
+
+1. Go to your Buildkite Organization select Queues and then select Create Queue
+2. Name the queue, for example `buildkite-queue1`
+3. Save the queue
 
-{{% notice Note %}}Make sure the queue name matches the `tags` field in the agent configuration.{{% /notice %}}
+{{% notice Note %}}
+Make sure the queue name matches the `tags` field in the agent configuration.
+{{% /notice %}}
 
-![Buildkite Dashboard alt-text#center](images/queue.png "Figure 2: Create Buildkite Queue")
+![Buildkite Dashboard alt-text#center](images/queue.png "Create Buildkite Queue")
 
-## 4. Verify Agent in Buildkite UI
+## 4. Verify the agent in the Buildkite UI
 
-First, you need to run locally:
+First, start the agent on your local computer: 
 
 ```console
-sudo /root/.buildkite-agent/bin/buildkite-agent start
+sudo /root/.buildkite-agent/bin/buildkite-agent start --build-path="/var/lib/buildkite-agent/builds"
 ```
 
-Then, Verify by UI:
+Then, confirm it is visible in the Buildkite UI:
 
-Go to **Buildkite → Agents.**
+Go Buildkite and select Agents
 
-Confirm that the agent is online and connected to the queue buildkite-queue1.
+Confirm that the agent is online and connected to the queue `buildkite-queue1`.
 
-![Buildkite Dashboard alt-text#center](images/agent.png "Figure 3: Verify Agent")
+![Buildkite Dashboard alt-text#center](images/agent.png "Verify Agent")
 
-Buildkite-agent setup is complete, you can now proceed with the multi-arch build using Buildkite.
+The Buildkite agent is ready, you can proceed to use Buildkit for building multi-arch images. 

content/learning-paths/servers-and-cloud-computing/buildkite-gcp/installation.md

@@ -9,21 +9,29 @@ layout: learningpathall
 ## Install Buildkite on a Google Axion C4A Arm VM
 This section guides you through installing the Buildkite agent on a Google Axion C4A Arm VM, enabling it to connect to your Buildkite account and run CI/CD pipelines.
 
-```console
+{{< tabpane code=true >}}
+  {{< tab header="Ubuntu" language="bash">}}
+sudo apt update
+sudo apt install unzip -y
+  {{< /tab >}}
+  {{< tab header="SUSE Linux" language="bash">}}
 sudo zypper refresh
 sudo zypper install -y curl unzip
-```
+  {{< /tab >}}
+{{< /tabpane >}}
 
 ### Download and Install Buildkite Agent
 
 ```console
-sudo sh -c "$(curl -sL https://raw.githubusercontent.com/buildkite/agent/main/install.sh)" 
+sudo bash -c "$(curl -sL https://raw.githubusercontent.com/buildkite/agent/main/install.sh)" 
 ```
-This one-line command downloads and runs the official Buildkite installer.  
-It will:  
 
-- Grab the latest version of the agent (`v3.107.0`)  
-- Install it into **root’s home directory** (`/root/.buildkite-agent`)  
+This one-line command downloads and runs the Buildkite installer.  
+
+The installer performs the following steps:
+
+- Download the latest version of the agent, for example `v3.109.1`  
+- Install it into the home directory of the root user at `/root/.buildkite-agent`  
 - Create a default config file (`buildkite-agent.cfg`) where you’ll later add your agent token 
 
 ```output
@@ -37,21 +45,21 @@ It will:
                                                 __/ |
                                                |___/
 Finding latest release...
-Installing Version: v3.107.0
+Installing Version: v3.109.1
 Destination: /root/.buildkite-agent
-Downloading https://github.com/buildkite/agent/releases/download/v3.107.0/buildkite-agent-linux-arm64-3.107.0.tar.gz
+Downloading https://github.com/buildkite/agent/releases/download/v3.109.1/buildkite-agent-linux-arm64-3.109.1.tar.gz
 
 A default buildkite-agent.cfg has been created for you in /root/.buildkite-agent
 
-Don't forget to update the config with your agent token! You can find the token on your "Agents" page in Buildkite
+Don't forget to update the config with your agent token! You can find it token on your "Agents" page in Buildkite
 
 Successfully installed to /root/.buildkite-agent
 
 You can now start the agent!
 
   /root/.buildkite-agent/bin/buildkite-agent start
 
-For docs, help, and support:
+For docs, help and support:
 
   https://buildkite.com/docs/agent/v3
 
@@ -65,57 +73,90 @@ This command checks the version of the Buildkite agent and confirms it is instal
 sudo /root/.buildkite-agent/bin/buildkite-agent --version
 ```
 You should see output similar to:
+
 ```output
-buildkite-agent version 3.107.0+10853.4606e31391a3bad2a5ba62f421ef041c0e4f04ab
+buildkite-agent version 3.109.1+10971.5c28e309805a3d748068a3ff7f5c531f51f6f495
 ```
 
 {{% notice Note %}}
-The Buildkite Agent version 3.43.0 introduces Linux/Arm64 Docker image for the Buildkite Agent, making deployment and installation easier for Linux users on Arm. You can view [this release note](https://github.com/buildkite/agent/releases/tag/v3.43.0).
+The Buildkite Agent version 3.43.0 introduces Linux/Arm64 Docker image for the Buildkite Agent, making deployment and installation easier for Linux users on Arm. You can view the [release note](https://github.com/buildkite/agent/releases/tag/v3.43.0).
 
 The [Arm Ecosystem Dashboard](https://developer.arm.com/ecosystem-dashboard/) recommends Buildkite Agent version v3.43.0 as the minimum recommended on the Arm platforms.
 {{% /notice %}}
 
 ### Install Docker and Docker Buildx
-Buildkite will use Docker to build and push images. Let’s set it up.
 
-1. Refresh package repositories and install required packages
+Buildkite will use Docker to build and push images. 
 
-This updates your system’s software list and installs git, Python3-pip, and Docker:
+First, refresh the package repositories and install the required packages including git, Python3-pip, and Docker:
 
-```console
-sudo zypper refresh
+Next, enable and start the Docker service to ensure it runs automatically when your VM starts:
+
+{{< tabpane code=true >}}
+  {{< tab header="Ubuntu" language="bash">}}
+sudo apt update
+sudo apt install python-is-python3 python3-pip -y
+curl -fsSL get.docker.com -o get-docker.sh && sh get-docker.sh
+sudo usermod -aG docker $USER ; newgrp docker
+  {{< /tab >}}
+  {{< tab header="SUSE Linux" language="bash">}}
 sudo zypper install -y git python3 python3-pip docker
-```
+sudo usermod -aG docker $USER ; newgrp docker
+  {{< /tab >}}
+{{< /tabpane >}}
+
 
-2. Enable and Start Docker
+SUSE Linux requires some extra steps to start Docker, you can skip this for Ubuntu:
 
-This makes sure Docker runs automatically every time, when your VM starts:
 ```console
 sudo systemctl enable docker
 sudo systemctl start docker
 ```
-3. Verify Docker installation
+
+Verify the Docker installation by checking the version and running a test container:
 
 ```console
-docker --version
 docker run hello-world
 ```
 
+You will see the Docker message:
+
+```output
+Hello from Docker!
+This message shows that your installation appears to be working correctly.
+
+To generate this message, Docker took the following steps:
+ 1. The Docker client contacted the Docker daemon.
+ 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
+    (arm64v8)
+ 3. The Docker daemon created a new container from that image which runs the
+    executable that produces the output you are currently reading.
+ 4. The Docker daemon streamed that output to the Docker client, which sent it
+    to your terminal.
+
+To try something more ambitious, you can run an Ubuntu container with:
+ $ docker run -it ubuntu bash
+
+Share images, automate workflows, and more with a free Docker ID:
+ https://hub.docker.com/
+
+For more examples and ideas, visit:
+ https://docs.docker.com/get-started/
+```
+
 ##  Install Docker Buildx
-Docker Buildx is a plugin that allows building multi-architecture images (e.g., Arm64 and x86).
+
+Docker Buildx is a plugin that allows building multi-architecture images, for example `arm64` and `amd64`. 
+
+For SUSE Linux, you need to install Docker Buildx. This is not necessary on Ubuntu.
+
+Download the binary and move it to the Docker CLI plugin directory:
 
 ```console
 wget https://github.com/docker/buildx/releases/download/v0.26.1/buildx-v0.26.1.linux-arm64
 chmod +x buildx-v0.26.1.linux-arm64
-mv buildx-v0.26.1.linux-arm64 ~/.docker/cli-plugins/docker-buildx
-sudo mv ~/.docker/cli-plugins/docker-buildx /usr/libexec/docker/cli-plugins/docker-buildx
-sudo chmod +x /usr/libexec/docker/cli-plugins/docker-buildx
+sudo mkdir -p /usr/libexec/docker/cli-plugins
+sudo mv buildx-v0.26.1.linux-arm64 /usr/libexec/docker/cli-plugins/docker-buildx
 ```
-What this does:
-
-- Downloads the Buildx binary for **Arm64**
-- Makes it **executable**
-- Moves it into Docker’s CLI plugin directory for the current user (`~/.docker/cli-plugins/`)
-- Optionally, move it system-wide (`/usr/libexec/docker/cli-plugins/`) so all users can access it
 
-Now that the Buildkite installation is completed, you can set up the Buildkite agent.
+Now that the Buildkite installation is complete, you can set up the Buildkite agent.