Ansible and GitHub Actions to run HPL

tutorial4/README.md

@@ -23,6 +23,7 @@
     1. [Reuse `providers.tf` and `main.tf` Terraform Configurations](#reuse-providerstf-and-maintf-terraform-configurations)
     1. [Create `.circleci/config.yml` File and `push` Project to GitHub](#create-circleciconfigyml-file-and-push-project-to-github)
     1. [Create CircleCI Account and Add Project](#create-circleci-account-and-add-project)
+    1. [How to use Ansible and GitHub Actions to run HPL](#how-to-use-ansible-and-github-actions-to-run-hpl)
 1. [Slurm Scheduler and Workload Manager](#slurm-scheduler-and-workload-manager)
     1. [Prerequisites](#prerequisites)
     1. [Head Node Configuration (Server)](#head-node-configuration-server)
@@ -1057,6 +1058,119 @@ In this section of the tutorials you're going to be expanding on the OpenStack i
 >
 > Consider how you could streamline this process even further using preconfigured instance snapshots, as well as  Ansible after your instances have been deployed.
 
+# How to use Ansible and GitHub Actions to run HPL
+
+To run the High-Performance Linpack (HPL) benchmark using Ansible and GitHub Actions, you can follow these steps:
+
+## **Step 1: Set up a GitHub Repo**
+1. Create a Github Repository or you can navigate to an existing Repository.
+
+2. In your Repo, navigate to **Settings** → **Security** → **Secrets and variables** → **Actions**.
+
+3. Click on **New repository secret**, for the title fill in "SSH_PRIVATE_KEY" and for the secrete, fill in the private key you use to connect to the cluster.
+
+<p align="center"><img alt="Creating Github Actions secretes" src="./resources/setting_up_secrets.png" width=900 /></p>
+
+
+## **Step 2: Create a Bash script, Ansible playbook and an Inventory file**
+ Click on **<>Code** in the navigation bar on top of the page.
+
+### Bash script ###
+1. Create a file called : `ansible/run_hpl.sh`
+
+2. Example of file contents: 
+```bash
+#!/bin/bash
+
+# Navigate to the directory that contains your hpl binary file
+cd /home/rocky/hpl/bin/compile_BLAS_MPI/
+
+# Run the HPL benchmark with srun
+srun -n16 ./xhpl
+```
+### Ansible playbook ###
+1. Create a file called `ansible/playbook.yml`
+
+2. Example of file contents: 
+```yaml
+- name: Run HPL benchmark
+  hosts: all
+  tasks:
+    - name: Copy the run_hpl.sh script to remote machine
+      copy:
+        src: run_hpl.sh  # Path to the script in the repo
+        dest: /home/rocky/run_hpl.sh  # Destination path on the remote machine
+        mode: '0755'  # Make the script executable
+
+    - name: Run HPL benchmark
+      shell: |
+        source /home/rocky/.profile
+        /home/rocky/run_hpl.sh
+      become: yes
+```
+### Ansible Inventory File ###
+1. Create a file called `ansible/inventory`
+
+2. Example of file contents:
+```yaml
+[headnode]
+# Only the head node's IP
+154.114.57.146 ansible_user=rocky
+```
+
+## **Step 3: Create a Github Actions Workflow**
+1. Click on **<>Code** in the navigation bar on top of the page.
+
+2. Create a file called:  `.github/workflows/run_hpl.yml`
+
+3. Example of file contents:
+```yaml
+name: Run Ansible Playbook
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  ansible:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - name: Set up SSH
+      run: |
+        # Ensure the .ssh directory exists
+        mkdir -p ~/.ssh
+        chmod 700 ~/.ssh
+
+        # Write the private key to the correct location
+        echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
+        chmod 600 ~/.ssh/id_rsa
+
+        # Add known hosts to the .ssh directory
+        echo "${{ secrets.KNOWN_HOSTS }}" > ~/.ssh/known_hosts
+        chmod 644 ~/.ssh/known_hosts
+
+    - name: Test SSH Connection
+      run: |
+        ssh -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no rocky@154.114.57.146 "echo Connected!"
+
+    - name: Run Ansible Playbook
+      run: ansible-playbook ansible/playbook.yml -i ansible/inventory
+```
+5. **Commit changes** and push.
+
+## **Final Remarks**
+
+After pushing the workflow file, the hpl benchmark will run on all nodes if slurm and openmpi are configured correctly. To confirm if the benchmark is running you can check your cluster monitoring software (Graphana) or do a classic htop/btop on the compute nodes.
+
+The github action workflow is triggered on push commands, this means that if any code is pushed to the Repo, the hpl benchmark will run.
+
+--------------------------------------------------------------------------------------------------------------------------------------
+
 # Slurm Scheduler and Workload Manager
 
 The Slurm Workload Manager (formerly known as Simple Linux Utility for Resource Management), is a free and open-source job scheduler for Linux, used by many of the world's supercomputers/computer clusters. It allows you to manage the resources of a cluster by deciding how users get access for some duration of time so they can perform work. To find out more, please visit the [Slurm Website](https://slurm.schedmd.com/documentation.html).
@@ -1305,3 +1419,6 @@ Using a batch script similar to the one above, run the benchmark. You may modify
 
 > [!NOTE]
 > Please be ready to present the `gromacs_log` files for the **1.5M_water** benchmark to the instructors.
+
+
+[def]: ./resources/circleci_successful_deploy.png"