diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/_index.md b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/_index.md new file mode 100644 index 0000000000..27856f5e7b --- /dev/null +++ b/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" +--- diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/_next-steps.md new file mode 100644 index 0000000000..c3db0de5a2 --- /dev/null +++ b/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. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/background.md b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/background.md new file mode 100644 index 0000000000..e4836e896c --- /dev/null +++ b/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/). diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/circleci-runner-installation.md b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/circleci-runner-installation.md new file mode 100644 index 0000000000..0492429de3 --- /dev/null +++ b/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 ") diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/circlecli-installation.md b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/circlecli-installation.md new file mode 100644 index 0000000000..2e1234c548 --- /dev/null +++ b/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! diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws1.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws1.png new file mode 100644 index 0000000000..04112848b0 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws1.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws2.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws2.png new file mode 100644 index 0000000000..776b35417d Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws2.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws3.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws3.png new file mode 100644 index 0000000000..07d0824930 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/aws3.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/computation.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/computation.png new file mode 100644 index 0000000000..9c5bd34391 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/computation.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/runner.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/runner.png new file mode 100644 index 0000000000..c14df5faa9 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/runner.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/runnerv1.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/runnerv1.png new file mode 100644 index 0000000000..511cfa241c Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/runnerv1.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner0.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner0.png new file mode 100644 index 0000000000..927a193982 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner0.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner1.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner1.png new file mode 100644 index 0000000000..bb587d2723 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner1.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner2.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner2.png new file mode 100644 index 0000000000..f85cc7a55a Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner2.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner3.png b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner3.png new file mode 100644 index 0000000000..b1362dab6c Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner3.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/instance.md b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/instance.md new file mode 100644 index 0000000000..cf6bf669d9 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/instance.md @@ -0,0 +1,38 @@ +--- +title: Create an AWS EC2 Arm64 Graviton2 Instance +weight: 3 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Overview + +In this section, you will learn how to provision an **AWS Graviton2 Arm64 EC2 instance** on **Amazon Web Services (AWS)** using the **m6g.xlarge** instance type (2 vCPUs, 8 GB memory) in the **AWS Management Console**. + +{{% notice Note %}} +For support on AWS setup, see the Learning Path [Getting started with AWS](https://learn.arm.com/learning-paths/servers-and-cloud-computing/csp/aws/). +{{% /notice %}} + +## Provision an AWS EC2 Arm64 Graviton2 Instance in the AWS Management Console + +To create a virtual machine based on the AWS Graviton2 Instance type: +- Navigate to the [AWS Management Console](https://aws.amazon.com/console/). +- Go to **EC2 > Instances** and select **Launch Instance**. +- Under **Instance configuration**: + - Enter an appropriate **Instance name**. + - Choose an **Amazon Machine Image (AMI)** such as **Ubuntu 24.04 ARM64**. + + ![AWS Management Console alt-text#center](images/aws1.png "Figure 1: Amazon Machine Image (AMI)") + + - Under **Instance type**, select a Graviton2-based type `m6g.xlarge`. + + ![AWS Management Console alt-text#center](images/aws2.png "Figure 2: Instance type") + + - Configure your **Key pair (login)** by either creating a new key pair or selecting an existing one to securely access your instance. + - In **Network settings**, ensure that **Allow HTTP traffic from the internet** and **Allow HTTPS traffic from the internet** are checked. + + ![AWS Management Console alt-text#center](images/aws3.png "Figure 3: Network settings") + + - Adjust **Storage** settings as needed — for most setups, 30 GB of gp3 (SSD) storage is sufficient. + - Click **Launch Instance** to create your EC2 virtual machine. diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/resource-class.md b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/resource-class.md new file mode 100644 index 0000000000..3e02ea50f4 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/resource-class.md @@ -0,0 +1,40 @@ +--- +title: Create Resource Class in CircleCI +weight: 5 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Create a Resource Class for Self-Hosted Runner in CircleCI +This guide describes creating a **Resource Class** in the **CircleCI Web Dashboard** for a **self-hosted runner**. +A Resource Class uniquely identifies the runner and links it to your CircleCI namespace, enabling jobs to run on your custom machine environment. + +### Steps + +1. **Go to the CircleCI Web Dashboard** + - From the left sidebar, navigate to **Self-Hosted Runners**. + - You’ll see a screen asking you to accept the **terms of use**. + - **Check the box** that says **“Yes, I agree to the terms”** to enable runners. + - Then click **Self-Hosted Runners** to continue setup. + +![Self-Hosted Runners alt-text#center](images/shrunner0.png "Figure 1: Self-Hosted Runners ") + +2. **Create a New Resource Class** + - Click **Create Resource Class**. + +![Self-Hosted Runners alt-text#center](images/shrunner1.png "Figure 2: Create Resource Class ") + +3. **Fill in the Details** + - **Namespace:** Your CircleCI username or organization (e.g., `circleci`) + - **Resource Class Name:** A descriptive name for your runner, such as `arm64` + +![Self-Hosted Runners alt-text#center](images/shrunner2.png "Figure 3: Details Resource Class & Namespace") + +4. **Save and Copy the Token** + - Once created, CircleCI will generate a **Resource Class Token**. + - Copy this token and store it securely — you will need it to register your runner on the AWS Arm VM. + +![Self-Hosted Runners alt-text#center](images/shrunner3.png "Figure 4: Resource Class Token") + +With your Resource Class and token ready, proceed to the next section to set up the CircleCI self-hosted runner. diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/validation.md b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/validation.md new file mode 100644 index 0000000000..385df18f9f --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/validation.md @@ -0,0 +1,109 @@ +--- +title: Verify CircleCI Arm64 Self-Hosted Runner +weight: 7 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Verify CircleCI Arm64 Self-Hosted Runner + +This guide demonstrates validating your **self-hosted CircleCI runner** on an **Arm64 machine** by executing a simple workflow and a test computation. This ensures your runner is correctly configured and ready to process jobs. + +### Create a Test Repository +Start by creating a GitHub repository dedicated to verifying your Arm64 runner: + +```console +git clone https://github.com/ hello.sh +chmod +x hello.sh +``` + +### Define the CircleCI Configuration +Create a `.circleci/config.yml` file to define the workflow that will run on your Arm64 runner: + +```yaml +version: 2.1 + +jobs: + test-Arm64: + machine: + enabled: true + resource_class: your-namespace/Arm64-linux # Replace with your actual resource class + steps: + - checkout + - run: + name: Verify Arm64 Runner + command: | + uname -m + lscpu | grep Architecture + ./hello.sh + - run: + name: Run sample computation + command: | + echo "Performing test on Arm64 runner" + echo "CPU Info:" + lscpu + echo "Success!" + +workflows: + test-workflow: + jobs: + - test-Arm64 +``` +- Defines a single job `test-Arm64` using a machine executor on a self-hosted Arm64 runner. +- Checks CPU architecture with `uname -m` and `lscpu` to verify the runner. +- Executes a simple script `hello.sh` to confirm the runner can run commands. +- Runs a sample computation step to display CPU info and print. + +### Commit and Push to GitHub +Once all files you created (`hello.sh`, `.circleci/config.yml`) are ready, push your project to GitHub so CircleCI can build and verify the Arm64 runner automatically. + +```console +git add . +git commit -m "Initial CircleCI Arm64 test" +git branch -M main +git push -u origin main +``` + +- **Add Changes**: Stage all modified and new files using `git add .`. +- **Commit Changes**: Commit the staged files with a descriptive message. +- **Set Main Branch**: Rename the current branch to `main`. +- **Add Remote Repository**: Link your local repository to GitHub. +- **Push Changes**: Push the committed changes to the `main` branch on GitHub. + +### Start CircleCI Runner and Execute Job +Ensure that your CircleCI runner is enabled and started. This will allow your self-hosted runner to pick up jobs from CircleCI. + +```console +sudo systemctl enable circleci-runner +sudo systemctl start circleci-runner +sudo systemctl status circleci-runner +``` +- **Enable CircleCI Runner**: Ensure the CircleCI runner is set to start automatically on boot. +- **Start and Check Status**: Start the CircleCI runner and verify it is running. + +After pushing your code to GitHub, open your **CircleCI Dashboard → Projects**, and confirm that your **test-Arm64 workflow** starts running using your **self-hosted runner**. + +If the setup is correct, you’ll see your job running under the resource class you created. + +### Output +Once the job starts running, CircleCI will: + +- Verify Arm64 Runner: + + ![Self-Hosted Runners alt-text#center](images/runnerv1.png "Figure 1: Self-Hosted Runners ") + +- Run sample computation: + + ![Self-Hosted Runners alt-text#center](images/computation.png "Figure 1: Self-Hosted Runners ") + +All CircleCI jobs have run successfully, the sample computation completed, and all outputs are visible in the CircleCI Dashboard.