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 index cdec577f5b..14d087fff3 100644 --- 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 @@ -1,7 +1,11 @@ --- title: CircleCI Arm Native Workflows on AWS Graviton2 (EC2) -minutes_to_complete: 45 +minutes_to_complete: 30 + +draft: true +cascade: + draft: true draft: true cascade: @@ -10,24 +14,16 @@ cascade: 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 + - Create 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/) - + - A CircleCI account + - Basic understanding of CircleCI workflows, jobs and resource classes -author: Pareena Verma +author: Annie Tallund ##### Tags skilllevels: Introductory @@ -39,7 +35,7 @@ armips: tools_software_languages: - CircleCI - - Bash/Shell scripting + - Bash - Git @@ -51,8 +47,8 @@ operatingsystems: # ================================================================================ further_reading: - resource: - title: AWS EC2 Documentation - link: https://docs.aws.amazon.com/ec2/index.html + title: AWS EC2 Graviton Documentation + link: https://aws.amazon.com/ec2/graviton/ type: documentation - resource: 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 index e4836e896c..6fa0bd6efb 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: Getting Started with CircleCI on AWS Graviton2 (Arm Neoverse-N1) +title: Getting Started with CircleCI on AWS Graviton weight: 2 @@ -7,21 +7,21 @@ layout: "learningpathall" --- -## AWS Graviton2 Arm Instances on Amazon EC2 +## AWS Graviton 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. +AWS Graviton is a family of Arm-based processors designed by AWS and built on Arm Neoverse-N1 cores. These instances deliver price-to-performance efficiency, making them suitable 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/). +Graviton-powered EC2 instances provide high performance and energy efficiency while maintaining compatibility with popular Linux distributions and open-source software stacks. ## 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. +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 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**. +It is widely adopted by development teams to accelerate build cycles, enforce code quality, automate testing, and streamline application delivery. -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. +Continue to the next section to set up your Graviton instance that you will use to run CircleCI workloads. -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 index ad04b62737..d915585f13 100644 --- 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 @@ -8,30 +8,20 @@ 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. +This section provides step-by-step instructions to install and configure the CircleCI Machine Runner. With this setup, your self-hosted Arm64 environment can efficiently execute CircleCI jobs directly on the Graviton 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`. +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/`. +After successful execution, the CircleCI repository will be added under `/etc/apt/sources.list.d/`. Run the command to verify: -### 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 +```bash +ls /etc/apt/sources.list.d/ ``` ### Install the CircleCI Runner 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 index 2e1234c548..a907a9eed0 100644 --- 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 @@ -7,8 +7,7 @@ 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. +This guide explains installing the CircleCI Command Line Interface (CLI). 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. @@ -18,15 +17,15 @@ 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. +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 `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. +- After extraction, a new folder named `circleci-cli_0.1.33494_linux_arm64` appears in your current directory. ### Verify the Installation @@ -35,10 +34,10 @@ To ensure that the CLI is installed successfully, check its version: ```console circleci version ``` -You should see an output similar to: +The first time this runs, an interactive shell might open. For now, press `Ctrl+C` to abort. You should now 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! +If this version number appears, the CircleCI CLI installation on your AWS Graviton instance was successful! 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 deleted file mode 100644 index 927a193982..0000000000 Binary files a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner0.png and /dev/null 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 deleted file mode 100644 index bb587d2723..0000000000 Binary files a/content/learning-paths/servers-and-cloud-computing/circleci-on-aws/images/shrunner1.png and /dev/null 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 index cf6bf669d9..66aa970c2f 100644 --- 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 @@ -8,31 +8,37 @@ 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**. +In this section, you will learn how to set up an AWS Graviton Arm64 EC2 instance on Amazon Web Services (AWS) using the `m6g.large` instance type 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: +## Set up an instance in the AWS Management Console + +To create your virtual machine: - 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**. +- 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`. + - Under Instance type, select a Graviton-based type `m6g.large`. ![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. + - 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") + + {{% notice Network security %}} + Be careful with permissive network inbound rules, as they pose a security risk. Good practice is to configure the machine to only allow traffic from your IP. + {{% /notice %}} - - 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. + + - Adjust Storage settings as needed — for this setup, 30 GB of gp3 (SSD) storage is sufficient. + - Click Launch Instance to create your 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 index 3e02ea50f4..b54e3eb697 100644 --- 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 @@ -7,33 +7,26 @@ 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**. +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. +1. Log into your CircleCI account and navigate to your dashboard. -![Self-Hosted Runners alt-text#center](images/shrunner0.png "Figure 1: Self-Hosted Runners ") +2. If you don't have an organization set up already, create one for testing purposes. -2. **Create a New Resource Class** - - Click **Create Resource Class**. +3. From the left sidebar in the Organization view, navigate to Self-Hosted Runners. 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/shrunner1.png "Figure 2: Create Resource Class ") +4. Create a New Resource Class by clicking 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` +5. Fill in the Details + - Namespace: Your CircleCI username or organization (e.g., `circleci`) + - Resource class label: 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. +6. 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") 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 index 385df18f9f..af05f54f8e 100644 --- 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 @@ -8,13 +8,13 @@ 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. +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//aws-circleci/ cd aws-circleci ``` This repository serves as a sandbox to confirm that your CircleCI runner can pick up and run jobs for Arm64 workflows. @@ -28,7 +28,13 @@ 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: +The next step is to adding a `.circleci/config.yml` file to define the workflow that will run on your Arm64 runner. Start by creating the directory in your new repository. + +```bash +mkdir .circleci +``` + +Then enter the YAML content: ```yaml version: 2.1 @@ -37,7 +43,7 @@ jobs: test-Arm64: machine: enabled: true - resource_class: your-namespace/Arm64-linux # Replace with your actual resource class + resource_class: circleci/arm64 # Replace with your actual resource class steps: - checkout - run: @@ -59,39 +65,35 @@ workflows: jobs: - test-Arm64 ``` + +{{% notice Resource Class %}} +In the snippet above, you need to replace the `resource_class` variable with the name you defined in the previous section. +{{% /notice %}} + + +This snippet: - 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. +When the 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 + +```bash 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. +If you haven't already, you need to configure your GitHub credentials before pushing. Once that is done, run the following to upstream your changes: -```console -sudo systemctl enable circleci-runner -sudo systemctl start circleci-runner -sudo systemctl status circleci-runner +```bash +git branch -M main +git push -u origin main ``` -- **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**. +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.