Merge pull request #2477 from madeline-underwood/buildkite

Buildkite_JA to review

Author: jasonrandrews

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

@@ -1,26 +1,22 @@
 ---
-title: Build multi-architecture Docker images with Buildkite on Google Axion
-
-draft: true
-cascade:
-    draft: true
+title: Create multi-architecture Docker images with Buildkite on Google Axion
 
 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 Google Axion processors.
+who_is_this_for: This is an introductory topic for developers who want to build and run multi-architecture Docker images with Buildkite on Arm-based Google Cloud C4A virtual machines (VM) powered by Google Axion processors.
 
 learning_objectives:
-- Provision an Arm-based virtual machine on Google Cloud running SUSE Linux Enterprise Server or Ubuntu
+- Provision an Arm-based VM on Google Cloud running either 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 a multi-architecture Docker image and push it to Docker Hub
-- Run the application to ensure it works as expected
+- Start the application and verify that it runs correctly
 
 prerequisites:
-  - 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
+  - A [Google Cloud Platform (GCP) account](https://cloud.google.com/free?utm_source=google&hl=en) with billing enabled
+  - Basic Linux system administration skills, including how to create users, install packages, and manage services
+  - Familiarity with [Docker](https://docs.docker.com/get-started/) and container concepts
+  - A [GitHub account](https://github.com/join) to host your application repository
 
 author: Jason Andrews
 

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

@@ -1,20 +1,26 @@
 ---
-title: Get started with Buildkite on Google Axion C4A instances
+title: Discover Buildkite on Google Axion C4A instances
 
 weight: 2
 layout: "learningpathall"
 ---
 
-## Google Axion C4A instances on Google Cloud
+## Get started 
 
-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.
+This section introduces two core technologies you'll use in this Learning Path: the Buildkite continuous integration and delivery (CI/CD) platform and Google Axion C4A Arm virtual machines (VMs). You'll see how these tools help you build, test, and deploy software efficiently on Arm-based cloud infrastructure. If you want to dive deeper, check out the links to further resources.
 
-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.
+## Buildkite for CI/CD on Arm
 
-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 is a flexible and scalable continuous integration and delivery (CI/CD) platform that enables 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. 
 
-## Buildkite for CI/CD on Arm
+To get started, review the [Buildkite documentation](https://buildkite.com/docs) for setup instructions, pipeline configuration, and agent management.
+
+## Google Axion C4A Arm VMs for efficient cloud workloads
+
+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. 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.
+
+Learn more in this Google blog [Introducing Google Axion Processors, our new Arm-based CPUs](https://cloud.google.com/blog/products/compute/introducing-googles-new-arm-based-cpu).
 
-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.
+## What's next?
 
-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).
+You've now learned about the two main technologies you'll use in this Learning Path. You're ready to start building, testing, and deploying on Arm-based cloud infrastructure with confidence. Keep going, you're making great progress!

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

@@ -1,30 +1,33 @@
 ---
-title: Set-up Buildkite
+title: Set up and connect Buildkite agent on a Google Axion C4A Arm VM
 weight: 5
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-# Set up a Buildkite agent
+## What you'll do in this section
 
-After installing the Buildkite agent binary on a Google Axion C4A Arm VM, you can set up and configure a Buildkite agent and queue.
+In this section, you'll configure and connect a Buildkite agent on a Google Axion C4A Arm virtual machine (VM). You'll generate an agent token, set up the agent configuration, create a Buildkite queue, and verify that your agent is online and ready to run CI/CD jobs on Arm infrastructure.
 
-## 1. Create an Agent Token
+## 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, 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.
+To create an agent token, follow these steps:
 
-![Buildkite Dashboard alt-text#center](images/agent-token.png "Create Buildkite agent Token")
+- Sign in to your Buildkite account. You can use your GitHub credentials if you prefer.
+- In the left menu, select **Organization settings**.
+- Select **Agents**.
+- Select **Create agent token**.
+- Enter a descriptive name for the token, such as `buildkite-arm`.
+- Select **Create token**.
+- Copy the token and store it securely as you won’t be able to view it again after you leave the page.
 
+![Buildkite Dashboard alt-text#center](images/agent-token.png "Create Buildkite agent token")
 
-## 2. Configure Buildkite Agent
+
+## Configure the Buildkite agent
 
 Create the configuration directory and file on your local system with the commands below:
 
@@ -35,10 +38,10 @@ tags="queue=buildkite-queue1"
 EOF
 ```
 
-Replace `YOUR_AGENT_TOKEN` with the token you generated from your Buildkite Agents page.  
+Replace `YOUR_AGENT_TOKEN` with the token that 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.
+{{% notice Tip %}}
+You might 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
 ```
@@ -63,34 +66,37 @@ token="YOUR-GENERATED-TOKEN-VALUE"
 tags="queue=buildkite-queue1"
 ```
 
-## 3. Create a Queue in Buildkite
+## Create a queue in Buildkite
 
 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
+- Go to your Buildkite organization, select **Queues**, and then select **Create queue**.
+- Enter a name for the queue, for example `buildkite-queue1`.
+- Select **Save** to create the queue.
+
+This step connects your agent to the correct queue, ensuring jobs are routed to your Arm-based Buildkite agent.
 
 {{% notice Note %}}
 Make sure the queue name matches the `tags` field in the agent configuration.
 {{% /notice %}}
 
-![Buildkite Dashboard alt-text#center](images/queue.png "Create Buildkite Queue")
+![Buildkite Dashboard alt-text#center](images/queue.png "Create the Buildkite queue")
 
-## 4. Verify the agent in the Buildkite UI
+## Verify the agent in the Buildkite UI
 
 First, start the agent on your local computer: 
 
 ```console
 sudo /root/.buildkite-agent/bin/buildkite-agent start --build-path="/var/lib/buildkite-agent/builds"
 ```
 
-Then, confirm it is visible in the Buildkite UI:
+Then, confirm the agent is visible in the Buildkite UI, by doing the following:
 
-Go Buildkite and select Agents
+- In the Buildkite dashboard, select **Agents** from the left menu. This page lists all registered agents for your organization. 
+- Look for your new agent in the list and verify that its status is **online** and that it is assigned to the correct queue.
 
 Confirm that the agent is online and connected to the queue `buildkite-queue1`.
 
-![Buildkite Dashboard alt-text#center](images/agent.png "Verify Agent")
+![Buildkite Dashboard alt-text#center](images/agent.png "Verify the agent")
 
-The Buildkite agent is ready, you can proceed to use Buildkite for building multi-arch images. 
+Congratulations! Your Buildkite agent is now set up and connected to your queue. You can now start using Buildkite to build multi-architecture images on your Arm-based VM. This setup enables you to run CI/CD pipelines optimized for Arm platforms, and take advantage of the performance and scalability of Arm servers.

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

@@ -1,13 +1,13 @@
 ---
-title: Install Buildkite
+title: Install Buildkite on a Google Axion C4A Arm VM
 weight: 4
 
 ### FIXED, DO NOT MODIFY
 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.
+## Get started with installing the Buildkite agent
+This section walks you through installing the Buildkite agent on a Google Axion C4A Arm VM, enabling it to connect to your Buildkite account and run the CI/CD pipelines.
 
 {{< tabpane code=true >}}
   {{< tab header="Ubuntu" language="bash">}}
@@ -20,19 +20,20 @@ sudo zypper install -y curl unzip
   {{< /tab >}}
 {{< /tabpane >}}
 
-### Download and Install Buildkite Agent
+## Download and install the Buildkite agent
+
+Use this one-line command to download and run the Buildkite installer:
 
 ```console
 sudo bash -c "$(curl -sL https://raw.githubusercontent.com/buildkite/agent/main/install.sh)" 
 ```
-
-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 
+- Downloads the latest version of the agent, for example `v3.109.1`  
+- Installs the Buildkite agent into the home directory of the root user at `/root/.buildkite-agent`  
+- Creates a default config file (`buildkite-agent.cfg`) where you’ll later add your agent token 
+
+You should see this output:
 
 ```output
  
@@ -66,31 +67,31 @@ For docs, help and support:
 Happy building! <3
 ```
 
-### Verify installation
-This command checks the version of the Buildkite agent and confirms it is installed successfully.
+## Verify installation
+
+Now verify the installation by checking the Buildkite agent version. This confirms that the agent is installed and ready to use:
 
 ```console
 sudo /root/.buildkite-agent/bin/buildkite-agent --version
 ```
-You should see output similar to:
+
+The expected output is similar to:
 
 ```output
 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 the [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 [Buildkite agent GitHub 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.
+The [Arm Ecosystem Dashboard](https://developer.arm.com/ecosystem-dashboard/) recommends Buildkite Agent version v3.43.0 or later for Arm platforms.
 {{% /notice %}}
 
-### Install Docker and Docker Buildx
-
-Buildkite will use Docker to build and push images. 
+## Install Docker
 
-First, refresh the package repositories and install the required packages including git, Python3-pip, and Docker:
+Buildkite uses Docker to build and push images.
 
-Next, enable and start the Docker service to ensure it runs automatically when your VM starts:
+This step ensures Docker is always available for your CI/CD pipelines.
 
 {{< tabpane code=true >}}
   {{< tab header="Ubuntu" language="bash">}}
@@ -105,14 +106,6 @@ sudo usermod -aG docker $USER ; newgrp docker
   {{< /tab >}}
 {{< /tabpane >}}
 
-
-SUSE Linux requires some extra steps to start Docker, you can skip this for Ubuntu:
-
-```console
-sudo systemctl enable docker
-sudo systemctl start docker
-```
-
 Verify the Docker installation by checking the version and running a test container:
 
 ```console
@@ -146,11 +139,16 @@ For more examples and ideas, visit:
 
 ##  Install Docker Buildx
 
-Docker Buildx is a plugin that allows building multi-architecture images, for example `arm64` and `amd64`. 
+Docker Buildx is a plugin that allows the building of multi-architecture images, for example `arm64` and `amd64`. 
+If you're using SUSE Linux, you need to install Docker Buildx manually. On Ubuntu, Docker Buildx is included by default, so you can skip this step.
+
+For more information or troubleshooting details, see the [Docker Buildx documentation](https://docs.docker.com/build/buildx/).
+
+## Download Docker Buildx
 
-For SUSE Linux, you need to install Docker Buildx. This is not necessary on Ubuntu.
+If you need to download Docker Buildx, follow these steps.
 
-Download the binary and move it to the Docker CLI plugin directory:
+Start by downloading the Docker Buildx binary and move it to the Docker CLI plugin directory. This enables advanced multi-architecture builds on your Arm VM:
 
 ```console
 wget https://github.com/docker/buildx/releases/download/v0.26.1/buildx-v0.26.1.linux-arm64
@@ -159,4 +157,26 @@ sudo mkdir -p /usr/libexec/docker/cli-plugins
 sudo mv buildx-v0.26.1.linux-arm64 /usr/libexec/docker/cli-plugins/docker-buildx
 ```
 
-Now that the Buildkite installation is complete, you can set up the Buildkite agent.
+After installing, verify that Docker Buildx is available:
+
+```console
+docker buildx version
+```
+
+The expected output is similar to:
+
+```output
+github.com/docker/buildx v0.26.1
+```
+
+If you see the version information, Docker Buildx is installed correctly and ready for use.
+
+{{% notice Note %}}
+If you encounter a "permission denied" error, ensure your user is in the `docker` group and that the plugin file is executable.
+{{% /notice %}}
+
+You can now use Docker Buildx to build and push multi-architecture images, which is especially useful for Arm-based CI/CD pipelines.
+
+## What you've accomplished
+
+Great job! You’ve installed Docker, Docker Buildx, and the Buildkite agent on your Arm VM. Next, you’ll set up and connect your Buildkite agent to your account.