From f8ca97001f5cfc46861704166a3332be02b20dbd Mon Sep 17 00:00:00 2001
From: Pedro Moura <pmoura@redhat.com>
Date: Jun 27 2022 06:56:45 +0000
Subject: added documentation about how to use ephemeral nodes to run tests


Signed-off-by: Pedro Moura <pmoura@redhat.com>

---

diff --git a/docs/ci.md b/docs/ci.md
index 56c9f03..150206f 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -7,3 +7,78 @@ We offer the following resources :
 
   * Openshift hosted jenkins (one per project/SIG), using usual authentication from FAS/ACO
   * bare-metal and/or Virtual Machines ephemeral nodes on which you can run some tests (including destructive ones), that will be automatically be reinstalled (for bare-metal) or discarded (for VMs)
+
+
+## Using bare-metal/Virtual Machines with Duffy client
+Duffy is the middle layer running ci.centos.org that manages the provisioning, maintenance and teardown / rebuild of the Nodes (physical hardware and VMs) that are used to run the tests in the CI Cluster.
+
+### Installing and configuring duffy client
+Use `pip` to install duffy client.
+
+```shell
+pip install --user duffy[client]
+```
+
+Duffy client needs the tenant's name and the tenant's API key to be able to request sessions from duffy server. If the tenant doesn't exist yet, it should be created in duffy server. Having the tenant's name and the tenant's API key, create the file `.config/duffy` with the following content. 
+
+```
+client:
+  url: https://duffy.ci.centos.org/api/v1
+  auth:
+    name: <tenant name>
+    key: <API key>
+```
+
+### Requesting a session
+Before creating a session, the name of the pool is required. Check the pool available executing the command.
+
+```shell
+duffy client list-pools
+```
+
+!!! note
+    The name of the pool is structured like this: 
+
+    `<AAA>-<BBB>-<CCC>-<DDD>-<EEE>-<FFF>`
+
+    - AAA: Identify if it is a bare metal or virtual machine
+    - BBB: The kind of the instance, like seamicro, AWS EC2, etc
+    - CCC: The size of the machine
+    - DDD: The operational system
+    - EEE: Operational system's version
+    - FFF: The architecture
+
+
+Having the name of the pool, request how many sessions needed. Duffy has a limit of sessions per tenant, this information is available in the duffy server.
+
+```shell
+duffy client request-session pool=<name of the pool>,quantity=<number of sessions>
+``` 
+
+By default this command outputs a _json_, but it's possible to change the format to _yaml_ or _flat_ using `--format`. Under "node" key it's possible to find the node's hostname provisioned. Log in to it as `root` user, using `ssh`.
+
+```json
+{
+<...output ommited...>
+
+"nodes": [
+    {
+        "hostname": "<hostname>",
+        "ipaddr": "<ip address>",
+
+<...output ommited...>
+}
+```
+
+### Retiring a session
+To retire a session, the session id is required. Check the id executing.
+
+```shell
+duffy client list-sessions
+```
+
+When needed to retire the session execute the command.
+
+```shell
+duffy client retire-session <session id>
+```