Insufficient documentation of terraform provider

[adamfowleruk]

Describe the bug

The documentation website does not correctly identify any examples within the resource or data source documentation pages even though sections and samples do exist in the examples folder (although incorrect...)

Furthermore, the documentation is not helpful. There is no description of the correct order resource calls have to be made in for a working Avi system to be created. The only way to determine this is to step through a manual configuration and then reverse engineer the steps into terraform (and only by reading the source code due to a lack of type information in the 'website' documentation - just names, no values, no values examples).

E.g. on https://registry.terraform.io/providers/vmware/avi/latest/docs/resources/avi_systemconfiguration the documentation for ntp_configuration is "(Optional) Dict settings for systemconfiguration." but there is no information on its format, no example, and no link to type information. You have to read the Go source code and then do trial by error when creating a module.

Reproduction steps

1. Read the documentation: https://registry.terraform.io/providers/vmware/avi/latest/docs/resources/avi_systemconfiguration
2.
3.
...

Expected behavior

Clear, concise documentation that gives real examples for each resource/datasource for common usage scenarios with an explanation beyond a single sentence. Also links to type information for dict type elements, again with examples.

There should be a list of which minimum elements post VM creation are required to get a fully configured Avi system - currently this list and order is not available in the terraform provider.

Additional context

No response

[itlinux]

Hello Adam, let me know what would you like and I will be happy to help, I just finished the example of AWS and working on the Azure side, then GCP. Have a good day. Remo

[adamfowleruk]

Sweet. More than a single sentence per operation in the terraform docs would be great. The examples are literally invocation examples without any config. When you look at the vsphere provider, for example, it'll give you 1-3 real world examples of using each operation. Also as I said a general introduction that says "To get a working Avi install like in the install guide, you'll need to do these in order, and here's a minimal working config" - today that provided config can never work.

[jcsmith]

I agree with @adamfowleruk over all the documentation surrounding the avi terraform provider is quite lacking. The examples often times don't even include all of the required attributes for a resource.

[cathode911]

Hello Adam, let me know what would you like and I will be happy to help, I just finished the example of AWS and working on the Azure side, then GCP. Have a good day. Remo

Here's a good example of what would be great to have.
Let's take this block of code for a resource "avi_network" which I recently wrote

resource "avi_network" "se-data" {
  name                = somename
  cloud_ref           = avi_cloud.nsxt.id
  dhcp_enabled        = false
  ip6_autocfg_enabled = false
  vrf_context_ref     = avi_vrfcontext.se-data-gw.id
  configured_subnets {
    prefix {
      ip_addr {
        addr = cidrhost(nsxt_policy_segment.on_tier1_gw_common["label1"].subnet[0].network, 0)
        type = "V4"
      }
      mask = 29
    }
    static_ip_ranges {
      range  {
        begin {
          addr = cidrhost(nsxt_policy_segment.on_tier1_gw_common["label1"].subnet[0].network, 2)
          type = "V4"
        }
        end {
          addr = cidrhost(nsxt_policy_segment.on_tier1_gw_common["label1"].subnet[0].network, 6)
          type = "V4"
        }
      }
      type = "STATIC_IPS_FOR_VIP_AND_SE"
    }
  }
}

Now let's open the documentation page for this resource https://registry.terraform.io/providers/vmware/avi/latest/docs/resources/avi_network

• configured_subnets - (Optional) Allowed in enterprise edition with any value, essentials, basic, enterprise with cloud services edition.

There is zero information about any sub blocks for block configured_subnets, ZERO.
Only looking for examples online and using trial and error method I finally was able to properly configure it.

Same goes for any other resource in the documentation, there is no information about any sub level blocks, only top level ones.

A good example would be NSX-T documentation with thorough description of every possible attribute/sub-attribute in hierarchical form, e.g. https://registry.terraform.io/providers/vmware/nsxt/latest/docs/resources/policy_tier0_gateway

[jakauppila]

I'd echo the sentiment here, any non-trivial resource in this provider has a large gap in documentation for required configurations for blocks. I've found that I've had to either drop over to the Swagger page to look at the data models or simply modify a resource manually via the UI to see how TF pulls it back into state on the read. Both are not great.

Ideally, the entire schema would be documented in the docs pages for each resource.