CircleCI Arm Native Workflows on AWS Graviton2 (EC2)

Signed-off-by: odidev <[email protected]>

Author: odidev

content/learning-paths/servers-and-cloud-computing/circleci-on-aws/_index.md

@@ -0,0 +1,68 @@
+---
+title: CircleCI Arm Native Workflows on AWS Graviton2 (EC2)
+    
+minutes_to_complete: 45
+
+who_is_this_for: This learning path is intended for software developers and DevOps engineers looking to set up and run CircleCI Arm native workflows on Linux Arm64 VMs, specifically on AWS EC2 Graviton2 instances (Neoverse N1), using self-hosted runners.
+
+learning_objectives:
+  - Provision an AWS EC2 Graviton2 Arm64 virtual machine
+  - Install and configure CircleCI self-hosted machine runners on Arm64
+  - Verify the runner by running a simple workflow and test computation
+  - Define and execute CircleCI job using a machine executor
+  - Check CPU architecture and execute a basic script to confirm if the runner is operational
+  - Display CPU information and validate outputs from the sample computation
+
+prerequisites:
+  - An [AWS account](https://aws.amazon.com/free/) with billing enabled
+  - Basic familiarity with Linux command line
+  - Basic understanding of CircleCI concepts such as 
+    [workflows](https://circleci.com/docs/guides/orchestrate/workflows/), 
+    [jobs](https://circleci.com/docs/guides/orchestrate/jobs-steps/),
+    [resource classes](https://circleci.com/docs/guides/execution-managed/resource-class-overview/), and 
+    [runners](https://circleci.com/docs/guides/execution-runner/runner-overview/)
+
+
+author: Pareena Verma
+
+##### Tags
+skilllevels: Introductory
+subjects: CI-CD
+cloud_service_providers: AWS
+
+armips:
+  - Neoverse
+
+tools_software_languages:
+  - CircleCI
+  - Bash/Shell scripting
+  - Git
+
+
+operatingsystems:
+  - Linux
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+further_reading:
+  - resource:
+      title: AWS EC2 Documentation
+      link: https://docs.aws.amazon.com/ec2/index.html
+      type: documentation
+
+  - resource:
+      title: CircleCI Self-Hosted Runner Documentation
+      link:  https://circleci.com/docs/guides/execution-runner/install-machine-runner-3-on-linux/
+      type: documentation
+
+  - resource:
+      title: CircleCI CLI Documentation
+      link: https://circleci.com/docs/guides/toolkit/local-cli/
+      type: documentation
+
+
+weight: 1
+layout: "learningpathall"
+learning_path_main_page: "yes"
+---

content/learning-paths/servers-and-cloud-computing/circleci-on-aws/_next-steps.md

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # Set to always be larger than the content in this path to be at the end of the navigation.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---

content/learning-paths/servers-and-cloud-computing/circleci-on-aws/background.md

@@ -0,0 +1,27 @@
+---
+title: Getting Started with CircleCI on AWS Graviton2 (Arm Neoverse-N1)
+
+weight: 2
+
+layout: "learningpathall"
+---
+
+
+## AWS Graviton2 Arm Instances on Amazon EC2
+
+**AWS Graviton2** is a family of Arm-based processors designed by AWS and built on **Arm Neoverse-N1 cores**. These instances deliver exceptional price-to-performance efficiency, making them ideal for compute-intensive workloads such as CI/CD pipelines, microservices, containerized applications, and data processing tasks.
+
+Graviton2-powered EC2 instances provide high performance and energy efficiency compared to traditional x86-based instances while maintaining compatibility with popular Linux distributions and open-source software stacks.
+
+To learn more about AWS Graviton processors, refer to the [AWS Graviton2 Processor Overview](https://aws.amazon.com/ec2/graviton/).
+
+## CircleCI
+
+**CircleCI** is a leading cloud-based **Continuous Integration and Continuous Delivery (CI/CD)** platform that automates the **building, testing, and deployment** of software projects.
+
+It seamlessly integrates with popular version control systems such as **GitHub**, **Bitbucket**, and **GitLab**, allowing developers to define automation workflows through a `.circleci/config.yml` file written in **YAML syntax**.
+
+CircleCI supports multiple execution environments, including **Docker**, **Linux**, **macOS**, and **Windows**, while providing advanced capabilities like **parallel job execution**, **build caching**, and **matrix builds** for optimized performance.
+
+It is widely adopted by development teams to **accelerate build cycles, enforce code quality, automate testing, and streamline application delivery**.  
+To learn more, visit the [official CircleCI website](https://circleci.com/) and explore its [documentation](https://circleci.com/docs/).

content/learning-paths/servers-and-cloud-computing/circleci-on-aws/circleci-runner-installation.md

@@ -0,0 +1,93 @@
+---
+title: Install CircleCI Machine Runner on AWS Graviton2
+weight: 6
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Install CircleCI Machine Runner on AWS Graviton2
+
+This guide provides step-by-step instructions to install and configure the **CircleCI Machine Runner** on an **AWS Graviton2 (Neoverse N1) instance**.  
+With this setup, your self-hosted **Arm64 environment** can efficiently execute CircleCI jobs directly on the Graviton2 architecture, enabling faster builds and improved performance for ARM-based workloads.
+
+
+### Add CircleCI Package Repository
+For **Debian/Ubuntu-based systems** running on **AWS Graviton2 (Arm64)**, first add the official CircleCI repository.  
+This ensures you can install the CircleCI Runner package directly using `apt`.
+
+```console
+curl -s https://packagecloud.io/install/repositories/circleci/runner/script.deb.sh?any=true | sudo bash
+```
+
+- The `curl` command downloads and executes the repository setup script from CircleCI’s official package server.  
+- It configures the repository on your system, allowing `apt` to fetch and install the CircleCI runner package.  
+- After successful execution, the CircleCI repository will be added under `/etc/apt/sources.list.d/`.
+
+### Configure the Runner Token
+- Each self-hosted runner requires a unique authentication token generated from your Resource Class in the CircleCI Dashboard.  
+- Copy the token from the CircleCI web interface.  
+- Export the token as an environment variable and update the runner configuration file as shown:
+
+```console
+export RUNNER_AUTH_TOKEN="YOUR_AUTH_TOKEN"
+sudo sed -i "s/<< AUTH_TOKEN >>/$RUNNER_AUTH_TOKEN/g" /etc/circleci-runner/circleci-runner-config.yaml
+```
+
+### Install the CircleCI Runner
+Install the pre-built CircleCI runner package:
+
+```console
+sudo apt-get install -y circleci-runner
+```
+ 
+- Installs the latest CircleCI Machine Runner compatible with your Arm64 instance.  
+- Runner binary and configuration files are located in `/usr/bin/` and `/etc/circleci-runner/`.
+
+### Configure the Runner Authentication Token
+Update the CircleCI runner configuration with your authentication token. This token is generated from the Resource Class you created in the CircleCI Dashboard.
+
+```console
+export RUNNER_AUTH_TOKEN="YOUR_AUTH_TOKEN"
+sudo sed -i "s/<< AUTH_TOKEN >>/$RUNNER_AUTH_TOKEN/g" /etc/circleci-runner/circleci-runner-config.yaml
+```
+
+### Enable and Start the CircleCI Runner
+Set the CircleCI runner service to start automatically and verify it is running:
+
+```console
+sudo systemctl enable circleci-runner
+sudo systemctl start circleci-runner
+sudo systemctl status circleci-runner
+```
+
+If the status shows active (running), your runner is successfully installed and connected to CircleCI.
+
+```output
+● circleci-runner.service - Run the CircleCI self-hosted runner agent
+     Loaded: loaded (/usr/lib/systemd/system/circleci-runner.service; enabled; preset: enabled)
+     Active: active (running) since Fri 2025-10-17 05:33:20 UTC; 51min ago
+   Main PID: 2226 (circleci-runner)
+      Tasks: 9 (limit: 18717)
+     Memory: 53.0M (peak: 66.9M)
+        CPU: 1.249s
+     CGroup: /system.slice/circleci-runner.service
+             └─2226 /usr/bin/circleci-runner machine -c /etc/circleci-runner/circleci-runner-config.yaml
+
+Oct 17 05:41:28 ip-172-31-34-224 circleci-runner[2226]: 05:41:28 7b67e 24.210ms worker loop: claim:  app.backoff_ms=5000 app.>
+Oct 17 06:00:08 ip-172-31-34-224 circleci-runner[2226]: 06:00:08 a8093 22.942ms POST /api/v3/runner/claim app.loop_name=claim>
+Oct 17 06:00:08 ip-172-31-34-224 circleci-runner[2226]: 06:00:08 a8093 23.028ms claim app.loop_name=claim:  mode=agent result>
+Oct 17 06:00:08 ip-172-31-34-224 circleci-runner[2226]: 06:00:08 a8093 23.064ms worker loop: claim:  app.backoff_ms=5000 app.>
+Oct 17 06:04:49 ip-172-31-34-224 circleci-runner[2226]: 06:04:49 73039 19.847ms POST /api/v3/runner/claim app.loop_name=claim>
+Oct 17 06:04:49 ip-172-31-34-224 circleci-runner[2226]: 06:04:49 73039 19.936ms claim app.loop_name=claim:  mode=agent result>
+Oct 17 06:04:49 ip-172-31-34-224 circleci-runner[2226]: 06:04:49 73039 19.971ms worker loop: claim:  app.backoff_ms=5000 app.>
+Oct 17 06:19:13 ip-172-31-34-224 circleci-runner[2226]: 06:19:13 c34c1 22.392ms POST /api/v3/runner/claim app.loop_name=claim>
+Oct 17 06:19:13 ip-172-31-34-224 circleci-runner[2226]: 06:19:13 c34c1 22.479ms claim app.loop_name=claim:  mode=agent result>
+Oct 17 06:19:13 ip-172-31-34-224 circleci-runner[2226]: 06:19:13 c34c1 22.514ms worker loop: claim:  app.backoff_ms=5000 app.>
+```
+
+This confirms that the CircleCI Runner is actively connected to your CircleCI account and ready to accept jobs.
+
+Also, you can verify it from the dashboard:
+
+![Self-Hosted Runners alt-text#center](images/runner.png "Figure 1: Self-Hosted Runners ")

content/learning-paths/servers-and-cloud-computing/circleci-on-aws/circlecli-installation.md

@@ -0,0 +1,44 @@
+---
+title: Install CircleCI CLI
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Install CircleCI CLI on AWS Graviton2 (Neoverse N1) Instance
+This guide explains installing the **CircleCI Command Line Interface (CLI)** on an **AWS Graviton2 (Neoverse N1) Arm64 EC2 instance**.  
+The CLI enables you to interact with CircleCI directly from your terminal — for validating configuration files, managing pipelines, and operating self-hosted runners on your EC2 instance.
+
+### Install Required Packages
+Before installing the CircleCI CLI, ensure your system has the necessary tools for downloading and extracting files.
+
+```console
+sudo apt update && sudo apt install -y curl tar gzip coreutils gpg git
+```
+### Download and Extract the CircleCI CLI
+
+Next, download the CircleCI CLI binary for **Linux arm64** and extract it.
+
+```console
+curl -fLSs https://github.com/CircleCI-Public/circleci-cli/releases/download/v0.1.33494/circleci-cli_0.1.33494_linux_arm64.tar.gz | tar xz
+sudo mv circleci-cli_0.1.33494_linux_arm64/circleci /usr/local/bin/
+```
+- The `curl` command fetches the official **CircleCI CLI archive** from GitHub.  
+- The `| tar xz` command extracts the compressed binary in a single step.  
+- After extraction, a new folder named **`circleci-cli_0.1.33494_linux_arm64`** appears in your current directory.
+
+### Verify the Installation
+
+To ensure that the CLI is installed successfully, check its version:
+
+```console
+circleci version
+```
+You should see an output similar to:
+
+```output
+0.1.33494+7cc6570 (release)
+```
+
+If this version number appears, the CircleCI CLI installation on your AWS Graviton2 instance was successful!