Add basic documentation on metal3-integration job

Give an overview of the metal3 integration job, its workflow,
and adds usefule links to familiarize with the metal3 project
and reach the metal3 community.

Change-Id: I94bd6a90f813af7323a7c3363577953a69e62ade

doc/source/contributor/jobs-description.rst

@@ -111,3 +111,10 @@ The description of each jobs that runs in the CI when you submit a patch for
   * - bifrost-integration-redfish-vmedia-uefi-centos-9
     - Tests the integration between Ironic and Bifrost using redfish vmedia and
       a dib image based on centos stream 9.
+  * - `metal3-integration`_
+    - Tests the integration between Ironic and `Metal3`_ using the
+      `metal3-dev-env`_ environment
+
+.. _metal3-integration: :doc:`/contributor/metal3-integration`
+.. _Metal3: https://metal3.io/
+.. _metal3-dev-env: https://github.com/metal3-io/metal3-dev-env

doc/source/contributor/metal3-integration.rst

@@ -0,0 +1,72 @@
+.. _metal3-integration:
+
+=============================
+Metal3 Continuous Integration
+=============================
+
+The Metal3 Continuous Integration job, named ``metal3-integration`` in the zuul
+configuration file, deploys a kubernetes cluster on emulated bare metal nodes,
+helping tests the ironic source code using the `Metal3 Development
+Environment (metal3-dev-env)`_ workflow from the `Metal3`_ project.
+
+=================
+Job configuration
+=================
+
+While the `metal3-integration job definition yaml file`_ is in the same path
+of the other Ironic CI jobs, it uses separate configuration files under
+`playbooks/metal3-ci`_ in the Ironic repository.
+The configuration follows ansible syntax as for other CI jobs.
+The actual job is configured in `run.yaml`_, where various environment variables
+for metal3-dev-env are defined under the ``metal3_environment`` entry.
+For more info about the metal3-dev-env environment variables definition and
+values please see the `metal3-dev-env env variables`_ page.
+In `post.yaml`_ we execute some post execution operations, like collecting logs
+and environment configuration, that are useful in case of troubleshooting.
+
+====================================
+Metal3 Development Environment Guide
+====================================
+
+To familiarize with the `Metal3 Development Environment (metal3-dev-env)`_,
+the Metal3 workflow, and in general with the project, it's recommended to
+follow the `TryIt`_ section of the Metal3 User Guide.
+The metal3-dev-env workflow steps are explained in Section 1.2.
+
+The `Metal3 Development Environment (metal3-dev-env)`_ is maintained by the
+`Metal3`_ project community which is present in the ``#cluster-api-baremetal``
+channel on Kubernetes Slack.
+For any questions or help on the project, or to escalate issues related to the
+``metal3-integration`` job please contact the Metal3 community.
+
+=====================
+Troubleshooting Guide
+=====================
+
+The ``metal3-integration`` job logs are stored in the same way and
+following roughly the same path of the other Ironic CI jobs.
+In the main directory the ``job-output.txt`` file contains the console
+output of the job and, if any failure exists, the main reason of the breakage.
+Other useful logs are stored under the ``controller`` directory:
+
+* ``before_pivoting`` directory stores services logs of the management cluster
+
+* ``libvirt`` directory stores libvirt configuration and logs, including
+  console logs of the emulated bare metal nodes
+
+* ``management_cluster`` directory stores all configuration and logs of the
+  metal3 services, such as the baremetal-operator (BMO)
+
+* ``system`` directory stores information and logs from the operating system
+  where metal3-dev-env is running
+
+
+.. _Metal3 Development Environment (metal3-dev-env): https://github.com/metal3-io/metal3-dev-env
+.. _Metal3: https://metal3.io/
+.. _metal3-integration job definition yaml file: https://opendev.org/openstack/ironic/src/branch/master/zuul.d/metal3-jobs.yaml
+.. _playbooks/metal3-ci: https://opendev.org/openstack/ironic/src/branch/master/playbooks/metal3-ci
+.. _run.yaml: https://opendev.org/openstack/ironic/src/branch/master/playbooks/metal3-ci/run.yaml
+.. _metal3-dev-env env variables: https://github.com/metal3-io/metal3-dev-env/blob/main/vars.md
+.. _post.yaml: https://opendev.org/openstack/ironic/src/branch/master/playbooks/metal3-ci/post.yaml
+.. _TryIt: https://book.metal3.io/developer_environment/tryit
+.. _Bare Metal Operator: https://github.com/metal3-io/baremetal-operator