Add documentation for operator features and security hardening#455
Add documentation for operator features and security hardening#455posikoya wants to merge 1 commit into
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: posikoya The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
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.
posikoya
force-pushed
the
posikoya/update-docs
branch
from
9264978 to
336ffee
Compare
kstrenkova
left a comment
kstrenkova
left a comment
There was a problem hiding this comment.
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.
| The :code:`ansibleGitBranch` field accepts any valid git ref — branch names, | ||
| tag names, or commit SHAs all work. | ||
|
|
||
| .. note:: |
There was a problem hiding this comment.
I don't think this note is necessary, this information is already in the first section of this feature.
| If :code:`ansibleGitBranch` is omitted or set to an empty string, the | ||
| repository's default branch is used. | ||
|
|
||
| .. note:: |
There was a problem hiding this comment.
I do not think this explanation is needed as well. The logic related to the merging of the workflows should be in a more visible place. What you have described is not something specific to the AnsibleTest Git Branch, but works like that for all workflow features.
|
|
||
| spec: | ||
| ansibleGitRepo: "https://github.com/myorg/openstack-tests" | ||
| ansibleGitBranch: "v3.0.0" |
There was a problem hiding this comment.
Are we sure this works? Even if it does, I would not include this example, I think the one on line 89 is enough to get the picture :D
|
|
||
| * :ref:`ansibletest-custom-resource` | ||
|
|
||
| .. _configurable-openstack-config: |
There was a problem hiding this comment.
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.
|
|
||
| Network Attachments | ||
| =================== | ||
| OpenStack deployments distribute services across multiple isolated networks. |
There was a problem hiding this comment.
I would drop this paragraph, it doesn't give any useful information imho. The next paragraph about The networkAttachments field allows users to specify additional.... is enough in that regard.
| all four test CRDs (Tempest, Tobiko, AnsibleTest, and HorizonTest). When | ||
| omitted, the scheduler uses its default placement logic. | ||
|
|
||
| Behaviour Per Test |
There was a problem hiding this comment.
I don't think this subsection is needed as well.
| effect: "NoSchedule" | ||
| containerImage: quay.io/podified-antelope-centos9/openstack-ansible-tests:current-podified | ||
|
|
||
| The toleration grants permission to run on the tainted node. The |
There was a problem hiding this comment.
This could be up in the first paragraph.
|
|
||
| .. _security-hardening: | ||
|
|
||
| Security Hardening |
There was a problem hiding this comment.
I think this whole security hardening should get a new page and not clutter this one.
|
|
||
| .. _service-config-ready-condition: | ||
|
|
||
| ServiceConfigReady Condition |
There was a problem hiding this comment.
This section is a good idea. I wouldn't necessarily call it ServiceConfigReady Condition, but maybe Checking Conditions. Then sum up how a user can check the conditions and what does it mean really briefly.
|
|
||
| .. _tempest-rerun-failed-tests: | ||
|
|
||
| Tempest Re-run Failed Tests |
There was a problem hiding this comment.
This section is in the wrong page imho. I would say to remove it all together or brainstorm where to put it. Again, the content is too long with little key information, I would suggest shortening it.
2 participants
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.shsphinx-autobuild docs/source docs/build/html