Provider doc missing reference to mandatory region parameter

[stevestrutt]

The Schematics documentation on the definition of the Terraform provider block, does not mention that the provider block is mandatory for resources, including VPC and ICD. It is required to specify the 'region' for resources that use regional API endpoints, this includes VPC and ICD. Otherwise all provisioning defaults to us-south.

This is a usability issue that is resulting in users creating multiple Github issues and Slack requests for support.

In the Schematics documentation these two discussions on the provider block only discuss that its not required due to IBM integration, they do not mention that its mandatory for VPC and ICD to specify region. This is setting the wrong expectation for the provider block.

• https://cloud.ibm.com/docs/schematics?topic=schematics-workspace-setup#plan-terraform-migration

• https://cloud.ibm.com/docs/schematics?topic=schematics-create-tf-config#configure-provider

• Additional section is required to cover the requirement for the 'region' parameter and which resources require it.

The Terraform provider doc itself does reference this requirement. https://cloud.ibm.com/docs/terraform?topic=terraform-provider-reference#required-parameters, but it is buried a long way down in the text. It uses a generic description for 'IAM services' which does not make it clear which services it is a mandatory requirement for.

Individual resource definitions in the Terraform doc for VPC and ICD also do not make this requirement clear and only refer back to the above Terraform doc section.

Proposed Terraform doc change:

• Update required parameters section to clearly identify the currently known resources that require the region parameter to be specified in the provider block.
• Additional sections are also required in the Terraform provider docs for each resource, such as ibm_is_vpc and ibm_database where it is mandatory to have a provider block specifying the region.

[Nadine2016]

@stevestrutt in this topic here: https://cloud.ibm.com/docs/schematics?topic=schematics-create-tf-config#configure-provider step 2 and 3 describe very detailed what information you need to provide in the provider block. it even has a sample provider block for VPC in there. Not sure what information you are looking for in here specifically? the only parameter that the docs talk about that is not required is the IBM Cloud API key.

same on this page here https://cloud.ibm.com/docs/terraform?topic=terraform-provider-reference#required-parameters VPC infrastructure is listed separately in this table with the required parameters. I used IAM-enabled services to cover all other services. But I can also rename it to all other resources or something and make it its own line if you think that makes it more clear?

for the Terraform provider doc, I have an important note on every single page that links to the provider block section, such as here

if you think it makes sense to add this note to every single resource, I can certainly do that. I could potentially also add a provider block to all examples? not sure what you would prefer?

[stevestrutt]

I'm coming from my own experience, that I couldn't find the references about region while I was looking for them. :-( Now you have pointed out the examples in the Terraform doc I can see that there is a reference there.

My first reference is to the Schematics doc, https://cloud.ibm.com/docs/schematics?topic=schematics-create-tf-config#configure-provider. This only refers to the API key not being required. The implication from a Schematics perspective is that a provider block is not necessary. And is in fact how I've run all my Schematics jobs for the last 9 months! All being in us-south. In which case I've never used a provider block in Schematics.

My experience is that it is not clear enough that additional parameters are needed when using Schematics. I was reading the text for the information and not the reverse highlighted example blocks. The examples are also called 'examples' and I ignored them as examples are typically not the source of truth. it doesn't mention that region is a required parameter to target resources.

Yes agree the info is in the Terraform docs. Though I see the starting point is the Schematics docs. Users moving from Terraform will likely just delete the entire provider block, which is what I did.

In the Terraform docs, I had not come across the highlighted section at the start of the page (and it doesn't mention that to use the resource the region has to be specified, all other parameters can be overridden like ResourceGroup on the resource definition). I never start at the start of the page, I use the quicklinks or the nav bar to go directly to the resource. The ibm_is_vpc resource is several pages down into the vpc page. I doubt many people start reading from the top :-) I think each resource that requires region to be specified like ibm_is_ipc, should have the same text as we've added to ibm_database discussing the use of region.

The section https://cloud.ibm.com/docs/terraform?topic=terraform-provider-reference#required-parameters discussing the different resource types is has technical inaccuracies.

• The heading Cloud Foundry and all other IAM-enabled services says region is required for all resources. This is incorrect. There are a number of 'global' resources like CIS which do not use the provider block region. The region is specified on the resource.
• The Cloud Foundry and all other IAM-enabled services heading assumes that users know what services these are. I doubt new users will know what IAM services these are and I would like to see at least a few examples mentioned, e.g. ICD, KeyProtect etc. At the time I think this was written there were none or at least very few. Now there are more, this could do with elucidating.
• The Classic heading incorrectly says that region is required. Classic resources are 'global' and associated with a data center and not a region. The region is not specified.

Maybe I'm unusual, but coming from a Terraform on Softlayer background using CIS, the region parameter was never needed on a provider block. Hence I deleted the provider block as it only contained the API key, which isn't required in Schematics!

I think as we have users come over from using Terraform on other Cloud platforms, they will make assumptions based on their previous Terraform usage and skip the basic material. Going directly to the resources they want to use and just want the differences highlighted.

[geethasathyamurthy]

@stevestrutt Request to know, should we still work on this issue, or is it set, so that we can close this issue.

Thanks, Geetha

[geethasm]

@stevestrutt

We are closing this issue, is the issue persist, request to reopen an issue.

Regards, Geetha