From: Jessica Wagantall <jwagantall@linuxfoundation.org>
Date: Mon, 21 May 2018 08:29:41 +0000 (-0700)
Subject: Add documentation on build minions
X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F31%2F10731%2F10;p=releng%2Fdocs.git

Add documentation on build minions

Add informtion on Jenkins build minions
- Explanation on the topic
- Pointer to packer images section
- How to configure a cloud and templates

Issue: RELENG-548
Change-Id: I69103e717e704cc78128cf500886b5a97051a0d7
Signed-off-by: Jessica Wagantall <jwagantall@linuxfoundation.org>
---

diff --git a/docs/_static/minions-add-cloud.png b/docs/_static/minions-add-cloud.png
new file mode 100644
index 0000000..7eb18d6
Binary files /dev/null and b/docs/_static/minions-add-cloud.png differ
diff --git a/docs/_static/minions-defaults.png b/docs/_static/minions-defaults.png
new file mode 100644
index 0000000..4631de8
Binary files /dev/null and b/docs/_static/minions-defaults.png differ
diff --git a/docs/_static/minions-manage-jenkins.png b/docs/_static/minions-manage-jenkins.png
new file mode 100644
index 0000000..6186bc3
Binary files /dev/null and b/docs/_static/minions-manage-jenkins.png differ
diff --git a/docs/_static/minions-template.png b/docs/_static/minions-template.png
new file mode 100644
index 0000000..c15a215
Binary files /dev/null and b/docs/_static/minions-template.png differ
diff --git a/docs/_static/minions-test.png b/docs/_static/minions-test.png
new file mode 100644
index 0000000..7d5884e
Binary files /dev/null and b/docs/_static/minions-test.png differ
diff --git a/docs/jenkins.rst b/docs/jenkins.rst
index 938d9e0..a6f70ad 100644
--- a/docs/jenkins.rst
+++ b/docs/jenkins.rst
@@ -99,10 +99,86 @@ the jobs published in Jenkins.
 This will push the jobs to Gerrit and your jobs will appear in Jenkins once the
 releng/builder or ci-management teams has reviewed and merged your patch.
 
-Build Minions
+Build minions
 =============
 
-.. todo:: RELENG-548
+Jenkins jobs run on build minions (executors) created on demand and deleted when the job
+terminates. Jenkins supports different types of dynamic build nodes and developers must
+know the flavors available to run their custom jobs.
+
+Jenkins uses the OpenStack Cloud plugin to administer node templates and configuration
+for the node instances. For more information on the template:
+``https://wiki.jenkins.io/display/JENKINS/Openstack+Cloud+Plugin``
+
+Projects requiring a specific build configuration can submit a change to the ``ci-management``
+or ``releng`` repos.
+
+Refer to the :ref:`Jenkins Configuration Merge <lf-global-jjb-jenkins-cfg-merge>`
+section to understand how the configuration changes get merged.
+
+.. note::
+
+   Here is an example from OpenDaylight:
+   https://github.com/opendaylight/releng-builder/tree/master/jenkins-config/clouds/openstack/odlvex
+
+For details on how to build an image for a particular build flavor, refer to the
+:ref: `Packer Images <lfdocs-packer-images>` section.
+
+Cloud configuration (Global Configuration)
+------------------------------------------
+
+This information will help developers (who do not have administer permissions) understand how
+LFIT configures a cloud and build minions via OpenStack Cloud plugin:
+
+#. Log in into Jenkins and click on ``Manage Jenkins``
+
+   .. image:: _static/minions-manage-jenkins.png
+
+#. Scroll to the ``Cloud`` section
+
+#. Click ``Add a new cloud``, ``Cloud (OpenStack)``
+
+   .. image:: _static/minions-add-cloud.png
+
+#. Fill the require information for Cloud provider, URL, credentials and region
+
+   .. note::
+
+      Click ``Test Connection`` to make sure the parameters provided establishes a connection.
+
+   .. image:: _static/minions-test.png
+
+#. Configure ``Default slave options...``
+
+   .. note::
+
+      The ``Default slave options`` can be overwritten for a particular node flavor
+      using the ``Template Advanced`` options
+
+   .. image:: _static/minions-defaults.png
+
+#. Click ``Add template`` and provide a node ``Name`` and ``Labels``
+
+   .. image:: _static/minions-template.png
+
+#. Specify a ``build-node`` in a project's yaml file:
+
+   .. code-block:: bash
+
+      build-node: ubuntu1604-builder-4c-4g
+
+   .. note::
+
+      The value should match an available ``Label`` for the node template.
+
+Build minion flavors
+--------------------
+
+This section points to each LF project's build minions availability and flavors.
+
+* OpenDaylight: https://github.com/opendaylight/releng-builder/tree/master/jenkins-config/clouds/openstack/odlvex
+
+.. todo:: Add more LF projects build minions links
 
 Log Server
 ==========