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_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: true
 
     # 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

@@ -52,6 +52,56 @@ AnsibleTest Custom Resource
    :language: yaml
 
 
+.. _git-branch-selection-for-ansibletest:
+
+Git Branch Selection for AnsibleTest
+====================================
+AnsibleTest runs Ansible playbooks from a git repository inside a test pod.
+By default, the pod clones the repository and uses its default branch. The
+git branch selection feature allows you to specify which branch, tag, or ref
+should be checked out before the playbook runs.
+
+Functionality
+-------------
+
+The feature is controlled by two related fields in the AnsibleTest CR spec:
+
+:code:`ansibleGitRepo` **(required)**
+
+The URL of the git repository to clone into the test pod. This must be a
+valid URI accessible from within the cluster.
+
+:code:`ansibleGitBranch` **(optional, no default)**
+
+The branch, tag, or git ref to check out after cloning. When omitted or
+left empty, the repository's default branch is used.
+
+The operator passes both values to the test pod as environment variables.
+The container's entrypoint script handles the clone and checkout.
+
+Basic Usage
+-----------
+
+Run playbooks from a specific branch:
+
+.. code-block:: yaml
+
+   apiVersion: test.openstack.org/v1beta1
+   kind: AnsibleTest
+   metadata:
+     name: release-validation
+     namespace: openstack
+   spec:
+     ansibleGitRepo: "https://github.com/myorg/openstack-tests"
+     ansibleGitBranch: "release-2.1"
+     ansiblePlaybookPath: "playbooks/validate.yaml"
+
+The pod clones the repository, checks out :code:`release-2.1`, then runs the
+playbook.
+
+The :code:`ansibleGitBranch` field accepts any valid git ref — branch names,
+tag names, or commit SHAs all work.
+
 .. _parallel-execution:
 
 Parallel Execution
@@ -144,6 +194,36 @@ CRs that can use the workflow section:
 
 * :ref:`ansibletest-custom-resource`
 
+.. _nodeselector-and-tolerations:
+
+NodeSelector and Tolerations
+============================
+The test-operator creates pods to run OpenStack tests. By default, the
+Kubernetes scheduler places these pods on any available node based on resource
+availability.The toleration grants permission to run on the tainted nod. The
+:code:`nodeSelector` ensures the pod only runs on nodes with the matching
+label.
+
+Basic Usage
+-----------
+
+.. code-block:: yaml
+
+   apiVersion: test.openstack.org/v1beta1
+   kind: AnsibleTest
+   metadata:
+     name: ansible-validate
+     namespace: openstack
+   spec:
+     nodeSelector:
+       testoperator: "true"
+     tolerations:
+       - key: "test"
+         operator: "Equal"
+         value: "true"
+         effect: "NoSchedule"
+     containerImage: quay.io/podified-antelope-centos9/openstack-ansible-tests:current-podified
+
 ExtraMounts parameter
 =====================
 To correctly use the :code:`ExtraMounts` parameter, follow these steps:
@@ -159,7 +239,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,6 +201,26 @@ 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`.
 
+.. _configurable-openstack-config:
+
+Configurable OpenStack Config
+------------------------------
+Test pods authenticate against OpenStack using two resources mounted into
+every pod: a ConfigMap containing :code:`clouds.yaml` (endpoints, project,
+username) and a Secret containing :code:`secure.yaml` (passwords, tokens).
+The names default to :code:`openstack-config` and
+:code:`openstack-config-secret` but can be overridden per CR:
+
+.. code-block:: yaml
+
+   spec:
+     openStackConfigMap: "my-clouds-config"
+     openStackConfigSecret: "my-clouds-secret"
+
+.. note::
+   For HorizonTest and Tobiko, the operator automatically injects the password
+   from :code:`secure.yaml` into :code:`clouds.yaml` if it is missing. Tempest
+   and AnsibleTest mount the original ConfigMap and Secret directly.
 
 .. _executing-tests:
 
@@ -253,6 +273,15 @@ You should see a pod with a name like :code:`tempest-tests-xxxxx`.
 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 tempest-tests -n openstack -o jsonpath='{.status.conditions}' | jq
 
 .. _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,49 @@
+.. _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**: No default — users set this explicitly when needed.
+
+No configuration is required to get these defaults. They apply automatically
+to Tempest, Tobiko, HorizonTest, and AnsibleTest pods.
+
+When to Use Privileged Mode
+===========================
+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 (routing tables,
+  interfaces, firewall rules). Needed by Tempest neutron plugin tests and
+  Tobiko fault injection scenarios.
+
+* :code:`NET_RAW` — allows raw socket access for tools like :code:`ping` and
+  :code:`tcpdump`. Needed by Tempest connectivity tests and Tobiko
+  reachability checks.
+
+Privileged mode is also required when Tempest installs additional RPMs at
+runtime via :code:`extraRPMs`, since that needs a writable root filesystem.
+
+If your tests do not exercise network infrastructure or install extra
+packages, leave :code:`privileged: false` (the default).