As discussed previously, the changes done in 7r1 for proxy management are so massive that they need proper documentation. I have compiled a list of the information we would like to see, as well as recommendation as to where to make them appear. I know that a fraction of this is not directly your work, however it never was documented, and now is a good time, so I am adding them here.
As a reminder, there are basically 3 types of documentations in DIRAC:
- Administrator guides: this is aimed at people managing an installation
- Developer guide: for people wanting to develop in DIRAC or in extensions
- User guide: for end user.
Of course, each doc can refer to the other for further details.
And we agreed (but are still in the process of doing) to have for each type of docs some general description as well as some more practical "howto"
Administrator docs
As an administrator, you need to understand several things when it comes to user management:
At the moment, there is no description of the components involved in user management at all.
I have seen the page https://dirac.readthedocs.io/en/rel-v7r1/AdministratorGuide/Resources/proxyprovider.html which is good. I think it can be kept as it is.
Developers docs
There are two aspects that needs to be covered
- if I am developing/fixing something directly related to proxy/user management
- if I am developing something else, but I need to interact with the user identity or authorization
If I understand correctly, all your new developments only impact the first point. For a service or an agent, there is no difference between v7r0 and v7r1, is that correct ? For the second point, there is already some (far from complete) docs here https://dirac.readthedocs.io/en/rel-v7r1/DeveloperGuide/Internals/Core/componentsAuthNandAuthZ.html . I think it remains correct, even after your changes, but please, check it.
For the first point, just like for the admin doc, there is no global picture.
Examples are the interaction with the proxy providers, what is really stored in the proxyDB, etc
For example of what I mean, you can look at what is in https://dirac.readthedocs.io/en/rel-v7r1/DeveloperGuide/Internals/Core/index.html
A few examples of developer documentation inside the doc:
User docs
This is the worse part of the documentation.
I do not think users need to know really a lot about that, but certainly this part could be extended if needed
Transition docs
I have seen you added some docs in the wiki part, but I think this is not quite enough. We need to understand more clearly what happens during the transition phase. All this information should be detailed in the adminsitrator, developer and code docs, but the wiki should give a global overview, and refer to details.
For example how are old and new proxy cohabiting in the ProxyDB, etc. Example of things I do not understand from the wiki are:
- " As a consequence, there will be no DIRAC group value in the output of dirac-proxy-init" Why wouldn't there be a group if I create a proxy localy ?
- " If a user deletes the proxy from the ProxyManager, then proxies for all the user groups will be no more available". Why ?
- Under which condition is a proxy less group uploaded if there are already proxy in the DB ?
Finally
Example of questions I have (and I'll probably add more)
- what happens to VOMS extensions ?
- How are users filed in the CS (VOMS2CS equivalent)
I do not expect you to answer the questions here, but just example of what I hope will be clear after reading the doc
As discussed previously, the changes done in 7r1 for proxy management are so massive that they need proper documentation. I have compiled a list of the information we would like to see, as well as recommendation as to where to make them appear. I know that a fraction of this is not directly your work, however it never was documented, and now is a good time, so I am adding them here.
As a reminder, there are basically 3 types of documentations in DIRAC:
Of course, each doc can refer to the other for further details.
And we agreed (but are still in the process of doing) to have for each type of docs some general description as well as some more practical "howto"
Administrator docs
As an administrator, you need to understand several things when it comes to user management:
What are the components involved in that.
What is a "user" in DIRAC (belongs to group, has properties, etc)
How are permissions managed
There should be one page, at the root of the admin docs, describing roughly all of the above (including your changes), and redirecting to more details sections (of the admin or developers docs)
There already is a HowTo about authentication and authorizations, but this should be extended to reflect the new possibilities, or a new one be added: https://dirac.readthedocs.io/en/rel-v7r1/AdministratorGuide/HowTo/authentication.html
At the moment, there is no description of the components involved in user management at all.
I have seen the page https://dirac.readthedocs.io/en/rel-v7r1/AdministratorGuide/Resources/proxyprovider.html which is good. I think it can be kept as it is.
Although this is really not mandatory for v7r1, there should really be a new tutorial about adding ProxyProviders https://dirac.readthedocs.io/en/rel-v7r1/AdministratorGuide/Tutorials/index.html
The ConfigReference part of the documentation should disappear. It is work in progress (see Documentation: Document Service/Agent/Executor Options via literalinclude of ConfigTemplate #4087) So the content of what is in there, related to user/proxy management should go either in the
dirac.cfg(with comment) or in the correspondingConfigTemplate.cfg(also with comment). And these should be added to the documentation using the literalinclude feature (see github issue quoted previously)Developers docs
There are two aspects that needs to be covered
If I understand correctly, all your new developments only impact the first point. For a service or an agent, there is no difference between v7r0 and v7r1, is that correct ? For the second point, there is already some (far from complete) docs here https://dirac.readthedocs.io/en/rel-v7r1/DeveloperGuide/Internals/Core/componentsAuthNandAuthZ.html . I think it remains correct, even after your changes, but please, check it.
For the first point, just like for the admin doc, there is no global picture.
Examples are the interaction with the proxy providers, what is really stored in the proxyDB, etc
For example of what I mean, you can look at what is in https://dirac.readthedocs.io/en/rel-v7r1/DeveloperGuide/Internals/Core/index.html
At some points, it is very likely that someone will want to add a new type of ProxyProvider. It should be quite clear how to do it. However, I would encourage you to only write very little about the matter in rst files, and rather refer to the doc contains directly inside the code.
Speaking about the docs inside the code, it would be nice to have, for each of the classes involved in user management, a description of what they are, with what they interact, how you can extend, etc
A few examples of developer documentation inside the doc:
User docs
This is the worse part of the documentation.
I do not think users need to know really a lot about that, but certainly this part could be extended if needed
Transition docs
I have seen you added some docs in the wiki part, but I think this is not quite enough. We need to understand more clearly what happens during the transition phase. All this information should be detailed in the adminsitrator, developer and code docs, but the wiki should give a global overview, and refer to details.
For example how are old and new proxy cohabiting in the ProxyDB, etc. Example of things I do not understand from the wiki are:
Finally
Example of questions I have (and I'll probably add more)
I do not expect you to answer the questions here, but just example of what I hope will be clear after reading the doc