Document that GKE master_auth key is an array

[aeneasr]

This resolves hashicorp/terraform#16417 and is a follow up to hashicorp/terraform#14073

[danawillow]

Hey @arekkas, thanks for the PR!

I took a look to see how we handle this in other resources, and found the docs for compute instance: https://www.terraform.io/docs/providers/google/r/compute_instance.html#attributes-reference, namely:

• network_interface.0.address - The internal ip address of the instance, either manually or dynamically assigned.

• network_interface.0.access_config.0.assigned_nat_ip - If the instance has an access config, either the given external ip (in the nat_ip field) or the ephemeral (generated) ip (if you didn't provide one).
  (etc)

If the docs for container cluster had been in a format like that, do you think that would have been clearer? I think the docs you've proposed are fine, but I worry they're almost too detailed. Let me know what you think!

[aeneasr]

I think it depends on whether or not master_auth is populated with more than one array entry. I'm not very savvy on GKE internals/API payloads so I don't really know if and when that array has more than one entry. Depending on that I would either try to keep it a bit verbose (maybe even explain what those other array elements might be), or redact it a bit to make it more streamlined.

[aeneasr]

One thing though, in my experience

I worry they're almost too detailed

does almost never apply to docs! :) Someone is always confused by instructions, having examples and a bit of explanation usually prevents that, at least in my experience.

[danawillow]

This line: https://github.com/terraform-providers/terraform-provider-google/blob/master/google/resource_container_cluster.go#L189 guarantees there will never be more than one entry.

And sure, too detailed might not have been the best phrasing. Too generalized? I'm fine with examples, but I personally think that:
master_auth.0.client_certificate is a bit more to-the-point than master_auth.<key>.client_certificate

[aeneasr]

Ok, then it makes sense to shorten this down!

[aeneasr]

I moved the example to the top and simply added a 0 key to the affected keys, does that look better now?

[danawillow]

Looks good, thanks @arekkas!

[ghost]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you feel this issue should be reopened, we encourage creating a new issue linking back to this one for added context. If you feel I made an error 🤖 🙉 , please reach out to my human friends 👉 [email protected]. Thanks!