Add documentation for operator features and security hardening

[posikoya]

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.

To run docs:
./docs/build-docs.sh
sphinx-autobuild docs/source docs/build/html

[kstrenkova]

Thank you for the work you put into this, this PR is much needed!

Saying that, I have left a lot of comments asking for changes. Overall, it is all about the same thing: please make it more compact. I don't think users want to read through sentences that are giving them no new information. I think the documentation should go straight to the point while having the most needed information :D

The change tackles the right things, however it could use some polishing to match the old style of the documentation and some sections moved to a different place.

[kstrenkova]

I don't think this is in the right place. I wouldn't say it's such a big feature to be added under this section. It rather makes a bit cluttered with a feature that will not be used as much. I would put it under Run Tests via Test Operator and make it a lot shorter.

[kstrenkova]

You moved it to the other file, but the remaining text is still here :D

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: posikoya
Once this PR has been reviewed and has the lgtm label, please ask for approval from kstrenkova. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[kstrenkova]

Thank you for your changes :D The structure is better now, but I left more comments to further reduce a bit of clutter. I hope my comments make sense, but if you are unsure, please let me know!

[kstrenkova]

I wouldn't add this Behaviour Per Framework section. First of all, I am not sure if the text is correct for every resource. Then I am also concerned that it is just text clutter.

[kstrenkova]

I think you can remove the whole Tempest Cleanup section. I don't think it's difficult to understand what the cleanup does, it's also just setting one boolean value.

If we want to let people know of it's existence, we can add it into the Tempest Custom Resource as a comment like:

# Set to true to remove all resources created by Tempest during teardown
#    cleanup: false

[kstrenkova]

I would remove this section as well. It is only Tempest specific and everyone knows what a timeout means. I think the section overall is too detailed around how it works as well. We don't need to explain every little detail to the reader, the documentation should explain briefly how it works and how to use it.

[kstrenkova]

When you run oc describe do you see this output? :D You need to talk about something that the user will experience exactly.

I would recommend either talking about using oc get tempest tempest-tests -o jsonpath='{.status.conditions}' | jq or talk about what you can really see under Conditions, e.g.

Conditions:
  Type                        Status
  PodReadyToStartContainers   False 
  Initialized                 True 
  Ready                       False 
  ContainersReady             False 
  PodScheduled                True 

[kstrenkova]

This part could be either removed or simplified (plus put next to the first sentence in this section). I think saying the first thing that failed is the problem should be obvious 😅

[kstrenkova]

I would remove this section and add it to the AnsibleTest Custom Resource as a comment. I don't think the feature is very difficult to understand and doesn't need much text to be explained.

[kstrenkova]

You moved it to the other file, but the remaining text is still here :D

[kstrenkova]

Network attachments are another feature that I would just comment on in Tempest Custom Resource and Tobiko Custom Resource. It is not difficult to understand, just adding another network, which can be explained in a simple comment.

[kstrenkova]

I would perhaps name this section Test pod privileges or something similar. I think talking about how it is set to follow security best practices is nice, just not piling too much (not useful) information on the user.

Overall this page is a good idea, but some parts are too specific like:

Two unnecessary host mounts (:code:`/etc/localtime` and
:code:`/etc/machine-id`) were also removed — .....

It should talk about things that actually affect the reader. Explain when to use it, when not.