Update documentation

_sources/changelog.rst.txt

@@ -0,0 +1,5 @@
+=========
+ChangeLog
+=========
+
+.. include:: ../CHANGELOG.rst

_sources/ci/files.rst.txt

@@ -0,0 +1,57 @@
+=============
+Special Files
+=============
+
+As part of the execution of the toolbox commands, some special files
+will be generated in the `$ARTIFACT_DIR` directory. They will be
+recognized by the code in `ci-dashboard
+<https://github.com/openshift-psap/ci-dashboard/>`_ repository and
+interpreted to enhance the dashboard display:
+
+- ``$ARTIFACT_DIR/<toolbox directory>/_ansible.log.json``: `JSON
+  <https://docs.ansible.com/ansible/latest/collections/ansible/posix/json_callback.html>`_
+  array of the ansible tasks executed as part of the toolbox
+  command. In particular, in this file, we parse the ``stats``
+  information of the last entry:
+
+.. code-block:: json
+
+    {
+      "log_level": "info",
+      "scope": "playbook",
+      "stats": {
+          "localhost": {
+              "changed": 4,
+              "failures": 0,
+              "ignored": 0,
+              "ok": 5,
+              "rescued": 0,
+              "skipped": 2,
+              "unreachable": 0
+          }
+      },
+      "status": "finished"
+    }
+
+
+- ``$ARTIFACT_DIR/FAILURE``: the presence this file after the CI
+  execution indicates that the testing failed.
+
+- ``$ARTIFACT_DIR/<toolbox step>/FLAKE``: the presence of this file
+  after a toolbox command fail indicates that a known flake
+  occurred. The file contains a brief description of the problem(s)
+  that happened, each on a dedicated line.
+
+- ``$ARTIFACT_DIR/<toolbox step>/EXPECTED_FAIL``: the presence of this
+  file after a test run indicates that this toolbox box step failure
+  was expected (i.e., not a failure, only a condition test). The file
+  contains a brief description of what was being tested.
+
+
+- ``$ARTIFACT_DIR/FLAKE``: the presence of this file after a test run
+  indicates that a known flake occurred. The file contains a brief
+  description of the problem that happened.
+
+- ``$ARTIFACT_DIR/_WARNINGS``: the presence of this directory after a
+  test run indicates that some warnings were raised. The files contain
+  a brief description of the problem that happened.

_sources/ci/intro.rst.txt

@@ -0,0 +1,20 @@
+============
+Introduction
+============
+
+As part of Red Hat PSAP team, we run nightly a set of tests to
+validate the proper execution of the operators we are in charge of:
+
+- the `GPU Operator <https://openshift-psap.github.io/ci-dashboard/gpu-operator_daily-matrix.html>`_
+- the `Node Feature Discovery operator <https://openshift-psap.github.io/ci-dashboard/nfd_daily-matrix.html>`_
+- the `Node Tuning Operator <https://openshift-psap.github.io/ci-dashboard/nto_daily-matrix.html>`_
+- the `Special Resource Operator <https://openshift-psap.github.io/ci-dashboard/sro_daily-matrix.html>`_
+
+The execution of these nightly tests is controlled by the code in the
+`ci-artifacts <https://github.com/openshift-psap/ci-artifacts/>`_
+repository, and the test steps are driven by the `toolbox
+<https://openshift-psap.github.io/ci-artifacts/index.html#psap-toolbox>`_
+commands.
+
+The nightly test overview is generated with the help of the `ci-dashboard
+<https://github.com/openshift-psap/ci-dashboard/>`_ repository.

_sources/contrib.rst.txt

@@ -0,0 +1,4 @@
+Contributing
+============
+
+.. include:: ../CONTRIBUTING.rst

_sources/index.rst.txt

@@ -0,0 +1,38 @@
+=================================
+Red Hat PSAP CI-Artifacts toolbox
+=================================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: General
+
+   intro
+   contrib
+   changelog
+
+.. _psap_ci:
+
+.. toctree::
+   :maxdepth: 3
+   :caption: PSAP Operator CI
+
+   ci/intro
+   ci/files
+
+.. _psap_toolbox:
+
+.. toctree::
+   :maxdepth: 3
+   :caption: PSAP Toolbox
+
+   toolbox/cluster
+   toolbox/entitlement
+   toolbox/gpu_operator
+   toolbox/nfd
+   toolbox/nto
+   toolbox/sro
+   toolbox/local-ci
+   toolbox/repo
+
+
+Documentation generated on |today| from |release|.

_sources/intro.rst.txt

@@ -0,0 +1 @@
+.. include:: ../README.rst

_sources/toolbox/cluster.rst.txt

@@ -0,0 +1,42 @@
+=======
+Cluster
+=======
+
+.. _toolbox_cluster_scale:
+
+Cluster Scale
+=============
+
+* Set number of nodes with given instance type
+
+.. code-block:: shell
+
+    ./run_toolbox.py cluster set_scale <machine-type> <replicas> [--base_machineset=BASE_MACHINESET]
+
+**Example usage:**
+
+.. code-block:: shell
+
+    # Set the total number of g4dn.xlarge nodes to 2
+    ./run_toolbox.py cluster set_scale g4dn.xlarge 2
+
+.. code-block:: shell
+
+    # Set the total number of g4dn.xlarge nodes to 5,
+    # even when there are some machinesets that might need to be downscaled
+    # to 0 to achive that.
+    ./run_toolbox.py cluster set_scale g4dn.xlarge 5 --force
+
+ .. code-block:: shell
+
+    # list the machinesets of the cluster
+    $ oc get machinesets -n openshift-machine-api
+
+    NAME                                      DESIRED   CURRENT   READY   AVAILABLE   AGE
+    playground-8p9vm-worker-eu-central-1a      1         1         1       1           57m
+    playground-8p9vm-worker-eu-central-1b      1         1         1       1           57m
+    playground-8p9vm-worker-eu-central-1c      0         0                             57m
+
+    # Set the total number of m5.xlarge nodes to 1
+    # using 'playground-8p9vm-worker-eu-central-1c' to derive the new machineset
+    ./run_toolbox.py cluster set_scale m5.xlarge 1 --base_machineset=playground-8p9vm-worker-eu-central-1c

_sources/toolbox/entitlement.rst.txt

@@ -0,0 +1,67 @@
+===========
+Entitlement
+===========
+
+
+Deployment
+==========
+
+* Deploy the entitlement cluster-wide
+
+Deploy a PEM key and RHSM configuration, and optionally, a custom CA
+PEM file.
+
+The custom CA file will be stored in
+``/etc/rhsm-host/ca/custom-repo-ca.pem`` in the host and in
+``/etc/rhsm/ca/custom-repo-ca.pem`` in the Pods.
+
+.. code-block:: shell
+
+    ./run_toolbox.py entitlement deploy --pem /path/to/key.pem
+
+* Undeploy the cluster-wide entitlement (PEM keys, RHSM configuration
+  and custom CA, if they exist)
+
+.. code-block:: shell
+
+    ./run_toolbox.py entitlement undeploy
+
+Testing and Waiting
+===================
+
+* Test a PEM key in a local ``podman`` container (requires access to
+  ``registry.access.redhat.com/ubi8/ubi``)
+
+.. code-block:: shell
+
+   ./run_toolbox.py entitlement test_in_podman /path/to/key.pem
+
+* Test a PEM key inside a cluster Pod (without deploying it)
+
+
+.. code-block:: shell
+
+   ./run_toolbox.py entitlement test_in_cluster /path/to/key.pem
+
+* Test cluster-wide entitlement
+
+(currently tested on a *random* node of the cluster)
+
+.. code-block:: shell
+
+    ./run_toolbox.py entitlement test_cluster [--no-inspect]
+
+* Wait for the cluster-wide entitlement to be deployed
+
+(currently tested on a *random* node of the cluster)
+
+.. code-block:: shell
+
+    ./run_toolbox.py entitlement wait
+
+Troubleshooting
+===============
+
+.. code-block:: shell
+
+    ./run_toolbox.py entitlement inspect