Add documentation for operator features and security hardening

Document configurable OpenStack config, network attachments,  nodeSelector/tolerations, security hardening, privileged mode  capabilities, image creation timeout, and tempest cleanup in crds.rst.  Add ServiceConfigReady condition diagnostics to guide.rst.

Author: posikoya

config/samples/test_v1beta1_ansibletest.yaml

@@ -16,7 +16,10 @@ spec:
   storageClass: local-storage
   workloadSSHKeySecretName: open-ssh-keys
   ansiblePlaybookPath: playbooks/my_playbook.yaml
+  # git repository URL to clone into the test pod
   ansibleGitRepo: https://github.com/myansible/project
+  # branch, tag, or commit SHA to check out (default: repo's default branch)
+  # ansibleGitBranch: ""
   # containerImage:
   ansibleInventory: |
     localhost ansible_connection=local ansible_python_interpreter=python3

config/samples/test_v1beta1_tempest.yaml

@@ -9,6 +9,8 @@ spec:
   # storageClass: local-storage
   # parallel: false
   # debug: false
+  # networkAttachments: []  # list of NADs to attach extra networks to the test pod
+  #                         # if omitted, the pod uses only the default cluster network
 
   # configOverwrite
   # ---------------
@@ -91,6 +93,8 @@ spec:
     #       RAM: 512
     #       disk: 20
     #       vcpus: 1
+    # Set to true to remove all resources created by Tempest during teardown
+    # cleanup: false
 
     # extraRPMs:
     # ----------

config/samples/test_v1beta1_tobiko.yaml

@@ -35,6 +35,8 @@ spec:
   # storageClass: local-storage
   # parallel: false
   # debug: false
+  # networkAttachments: []  # list of NADs to attach extra networks to the test pod
+  #                         # if omitted, the pod uses only the default cluster network
   # privateKey: |
   #   <private-key-value>
   # publicKey: |

docs/source/crds.rst

@@ -144,6 +144,33 @@ CRs that can use the workflow section:
 
 * :ref:`ansibletest-custom-resource`
 
+.. _nodeselector-and-tolerations:
+
+NodeSelector and Tolerations
+============================
+Use :code:`nodeSelector` and :code:`tolerations` to control which nodes the
+test pods are scheduled on. The :code:`nodeSelector` ensures the pod only runs
+on nodes with a matching label. The :code:`tolerations` grant permission to run
+on tainted nodes.
+
+Basic Usage
+-----------
+
+.. code-block:: yaml
+
+   spec:
+     # Targets nodes labeled testoperator=true
+     # (oc get node <node-name> --show-labels)
+     nodeSelector:
+       testoperator: "true"
+     # Tolerates nodes tainted with test=true:NoSchedule
+     # (oc describe node <node-name> | grep Taints)
+     tolerations:
+       - key: "test"
+         operator: "Equal"
+         value: "true"
+         effect: "NoSchedule"
+
 ExtraMounts parameter
 =====================
 To correctly use the :code:`ExtraMounts` parameter, follow these steps:
@@ -159,7 +186,7 @@ to be mounted. The name assigned here is later referenced in the
 mounted in the Pod. Each entry should include the name of a volume
 from the :code:`volumes` field and the target mount path.
 
-Example of using the :code:`ExtraMounts` parameter:
+Example test of using the :code:`ExtraMounts` parameter:
 
 .. code-block:: yaml
 

docs/source/guide.rst

@@ -201,7 +201,6 @@ Please make sure that you follow the order of the steps:
    :code:`crd`. In such a case, try to delete the :code:`finalizers:`
    section in the output of the :code:`oc edit tempest/tempest-tests`.
 
-
 .. _executing-tests:
 
 Executing Tests
@@ -248,11 +247,31 @@ You should see a pod with a name like :code:`tempest-tests-xxxxx`.
 
 .. code-block:: bash
 
-    oc logs <name of the pod>
+    oc logs <pod-name>
 
 Read :ref:`getting-logs` section if you want to see logs and artifacts
 produced during the testing.
 
+.. _checking-conditions:
+
+Checking Conditions
+-------------------
+Every test CR exposes standard conditions that track its progress:
+
+.. code-block:: bash
+
+   oc get tempest <pod-name> -n openstack -o jsonpath='{.status.conditions}' | jq
+
+Example output of a condition:
+
+.. code-block:: bash
+
+   {
+     "type": "DeploymentReady",
+     "status": "False",
+     "reason": "Requested",
+     "message": "Deployment is running"
+   }
 
 .. _getting-logs:
 

docs/source/index.rst

@@ -24,6 +24,7 @@ Running Test Operator
    prerequisites.rst
    guide.rst
    crds.rst
+   security.rst
    FAQ.rst
 
 Alternative Ways of Running Tempest Container

docs/source/security.rst

@@ -0,0 +1,46 @@
+.. _test-pod-privileges:
+
+===================
+Test Pod Privileges
+===================
+The test-operator follows security best practices by applying a restricted
+security profile to all test pods by default. This section describes the
+defaults and when you might need to change them.
+
+Default Security Profile
+========================
+
+Every test pod runs with the following restrictions:
+
+* **Seccomp**: A :code:`RuntimeDefault` profile filters system calls at the
+  kernel level.
+
+* **Privilege escalation**: Disabled processes cannot gain more privileges
+  than their parent.
+
+* **Root filesystem**: Read-only containers cannot modify their own binaries
+  or write to unexpected locations.
+
+* **Capabilities**: All capabilities are dropped.
+
+* **SELinux level**: Not set by default. Only needed for privileged
+  workflows that write to shared PVCs.
+
+When to Use Privileged Mode
+===========================
+
+.. important::
+   Leave :code:`privileged: false` unless your tests specifically require it.
+
+Set :code:`privileged: true` on the CR spec when your tests need capabilities
+that the default profile blocks. The two capabilities added in privileged mode
+are:
+
+* :code:`NET_ADMIN` allows modifying network configuration such as routing
+  tables, interfaces, and firewall rules.
+
+* :code:`NET_RAW` allows raw socket access for tools like :code:`ping` and
+  :code:`tcpdump`.
+
+Privileged mode is also required when Tempest installs additional RPMs at
+runtime via :code:`extraRPMs`, since that needs a writable root filesystem.