From b288e37f7d66453955d4b1c65e57e9962b595983 Mon Sep 17 00:00:00 2001
From: Federico Di Pierro <nierro92@gmail.com>
Date: Fri, 10 May 2024 16:22:14 +0200
Subject: [PATCH] update(docs): updated readme with more informations.

Signed-off-by: Federico Di Pierro <nierro92@gmail.com>
---
 README.md  | 78 +++++++++++++++++++++++++++++++++++++++---------------
 action.yml |  2 +-
 2 files changed, 58 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 765ea3e..617f021 100644
--- a/README.md
+++ b/README.md
@@ -11,46 +11,82 @@ You can find list of machines being used [here](./ansible-playbooks/group_vars/a
 ## Prerequisites
 
 * Install [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
-* Install [Ignite](https://ignite.readthedocs.io/en/stable/installation/) from `therealbobo` fork (use `main` branch): https://github.com/therealbobo/ignite
+* Install [Ignite](https://ignite.readthedocs.io/en/stable/installation/) from `therealbobo` fork (use `main` branch): https://github.com/therealbobo/ignite; just issue `make` and then `sudo make install` to install everything needed under `/usr/local/`.
+* Install ignite CNI plugins by following this guide: https://ignite.readthedocs.io/en/stable/installation/#cni-plugins:
+```bash
+export CNI_VERSION=v0.9.1
+export ARCH=$([ $(uname -m) = "x86_64" ] && echo amd64 || echo arm64)
+sudo mkdir -p /opt/cni/bin
+curl -sSL https://github.com/containernetworking/plugins/releases/download/${CNI_VERSION}/cni-plugins-linux-${ARCH}-${CNI_VERSION}.tgz | sudo tar -xz -C /opt/cni/bin
+```
 
-## Configure repository
+## Configure
 
-Configure an ssh key pair into the `/group_vars/all/vars.yml` file 👇
+It is advised to avoid directly modifying [`vars.yml`](ansible-playbooks/group_vars/all/vars.yml) file;  
+instead one can create a local vars.yml file to override keys from the default vars.  
 
+The only mandatory thing to be configured is an ssh key pair:
 ```yml
-#####################
-# SSH configuration #
-#####################
-
 #Path to the generated SSH private key file
 ssh_key_path: "" # <-- Replace here with the key path
 ssh_key_name: "" # <-- Replace here with the key name
-
-#Path to the private key
-prv_key_path: "{{ssh_key_path}}/{{ssh_key_name}}"
-
-#path to the public key used to ssh to the machines, if this key does not exist then a new one is generated with the same name
-pub_key_path: "{{ssh_key_path}}/{{ssh_key_name}}.pub"
 ```
-
-You need to provide the path to the key pair (`ssh_key_path`) and the name of the key pair (`ssh_key_name`)
-
-## Run tests
+## Run
 
 From the `ansible-playbooks` directory you can run tests on all machines by typing:
 
 ```bash
-ansible-playbook main-playbook.yml --ask-become 
+ansible-playbook main-playbook.yml --ask-become --extra-vars "@/path/to/local/vars.yaml"
 ```
 
 To rerun tests:
 
 ```bash
-ansible-playbook scap-open.yml --ask-become 
+ansible-playbook scap-open.yml --ask-become --extra-vars "@/path/to/local/vars.yaml"
 ```
 
-## Clean-up all machines
+To cleanup all machines
 
 ```bash
-ansible-playbook clean-up.yml --ask-become
+ansible-playbook clean-up.yml --ask-become --extra-vars "@/path/to/local/vars.yaml"
+```
+
+## CI Usage
+
+To better suit the CI usage, a [Github composite action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) has been developed.  
+Therefore, running kernel-testing in your Github workflow is as easy as adding this step:
+```
+- uses: falcosecurity/kernel-testing@main
+  # Give it an id to be able to later use its outputs
+  id: kernel_tests
+  with:
+    # libs version to be tested, eg: master.
+    # Default: 'master'
+    libsversion: master
+    
+    # libs repo to be tested, eg: falcosecurity/libs.
+    # Default: 'falcosecurity/libs'
+    libsrepo: falcosecurity/libs
+    
+    # Whether to generate matrixes as matrix artifact.
+    # Default: false
+    build_matrix: 'true'
+```
+Then you can use action outputs to retrieve artifacts:
 ```
+- uses: actions/upload-artifact@latest
+  with:
+    name: ansible_output
+    path: ${{ steps.kernel_tests.outputs.ansible_output }}
+        
+- uses: actions/upload-artifact@latest
+  with:
+    name: matrix
+    path: ${{ steps.kernel_tests.outputs.matrix_output }}
+```
+
+As an example, see [libs reusable workflow](https://github.com/falcosecurity/libs/blob/master/.github/workflows/reusable_kernel_tests.yaml).
+
+> __NOTE:__ Since we don't use annotated tags, one cannot use eg: falcosecurity/kernel-testing@v0, but only either exact tag name or master.
+
+> __NOTE:__ Of course, you'll need to run your tests on virtualization-enabled nodes.
diff --git a/action.yml b/action.yml
index 470a248..783d068 100644
--- a/action.yml
+++ b/action.yml
@@ -11,7 +11,7 @@ inputs:
     required: false
     default: 'falcosecurity/libs'
   build_matrix:  
-    description: 'Whether to generate matrixes as matrix_$architecture artifact'
+    description: 'Whether to generate matrixes as matrix artifact'
     required: false
     default: 'false'