Guide for tofu openstack config usage

[claudia-lola]

User guide for tofu-openstack-config including opentofu-vast-manila repo integration.

#21 should be merged first.

[L-Chams]

Looking good, just a few grammatical changes I'd recommend.

[sjpb]

Think it needs some work:
a. Make it clear what's different from the README - maybe some stuff needs moving from there to here.
b. Currently it just shows structures, so you're still going to have to read the code to find out types and optional/required.

If you really want to add this much detail, I think it needs to be much more like the provider docs TBH, e.g. https://registry.terraform.io/providers/terraform-provider-openstack/openstack/latest/docs/resources/compute_instance_v2.html

which has examples, optional/required, type information and descriptions. If you want to do that - which is useful - I'd be tempted to point an LLM at it as a first pass, then review carefully!

[sjpb]

How come you're using RST for this when the readme is markdown?
This needs to be linked from the README too which a clear sentence describing why its separate. E.g. "for guidance on how to strucure complex configuration, see ...." or something.

[claudia-lola]

I've now converted to markdown, kept the .rst file so your comments don't disappear :)

Quick(ish) overview of updates:

• I decided to separate out the different resources into files, grouping them where felt appropriate. Such as networks with routers. Users with roles and groups.
• Argument references have been added for all the resources. Stating whether it is required or optional, the argument type and if changing given argument will cause tofu to destroy and recreate the given resource.
• They also include one example usage. I haven't made an example usage for shares just because I'm unsure if we actually need this resource?
• There are two new resources that are defined in the vast support PR sharetypes and sharetypes_access. These resources are currently in development by Jed and Stig in gophercloud but will be a while until they are available without the custom opentofu provider we were using to test. These can be taken out of the guide and then merged in a separate PR to avoid confusion.
• The vast resources from opentofu-vast-manila have been moved to this repo ( vippools and vast_tenant ) as seen in the vast support PR.
• Updated the README.md removing the network-config part into networking.md. More needs updating with the README.md for what resources are supported and maybe adding a part on the vast support (?)

[sjpb]

where's locals {} defined?

[sjpb]

Doesn't this duplicate https://github.com/stackhpc/tofu-openstack-config#network-config-example, but with actually less guidance? E.g. it doesn't explain here the stuff in the notes there. I mean it shouldn't be duplicated, but I'm finding this quite confusing!

[sjpb]

None of these distinuish between optional and required parameters, or give any type info. I do think reading the raw tofu files with that info is a bit hard, but I'm not sure this adds very much TBH.

[sjpb]

external_fixed_ips need to be separated by a comma

Is this just meaning external_fixed_ips itself takes a list? Or you can specify external_fixed_ips multiple times? If the former, we're not explaining how to structure a list everywhere else (or a map), why here?