fix: update Terraform examples

[wilderj]

Summary

The examples in this repo were a bit out of date, and they no longer match the examples given in the Fortinet documentation. This PR cleans things up. In particular, this changeset:

1. Updates the README examples to contain an up-to-date versions.tf
2. Updates the google TF provider to contain a project field, since this is now required
3. Adds annotations to explain certain variables and options, where appropriate.
4. Adds the "organization ID" to project level example READMEs, since this is now a required field for project level integrations. The examples themselves already contained these fields.

Special focus was given to getting the README files up-to-date since in the near future, the Fortinet documentation won't contain Terraform examples at all; the docs will simply point to these READMEs on https://registry.terraform.io/modules/lacework/agentless-scanning/gcp/latest.

How did you test this change?

I test deployed both a project level and and organization level integration using the examples with these changes in place. In both cases, terraform apply was successful and the integration appears properly configured.

Issue

https://lacework.atlassian.net/browse/AWLS2-550

[kirklandnuts]

thanks for updating these @wilderj

[kirklandnuts]

To be clear, does this mean that region in this block must be set to "global"? If so, why not just set region = "global" instead of region = <region1>?

Otherwise, does it mean that the GCP project where the customer wants to deploy scanning resources must be assigned to the global region in GCP?

[wilderj]

It refers to the per-region blocks below that actually define our module, like lacework_gcp_agentless_scanning_project_multi_region_<alias1>.

Exactly one of these blocks must have global = true, since we create "global" resources that still have to be created in a particular region.

Since those resources must also live in the scanning account, this comment is saying you have to use this provider in whichever module uses global = true. Does that make sense? Not sure if I am explaining this well. I also lifted this comment directly from the example in the FortiCNAPP docs.

[kirklandnuts]

Yes, this makes total sense - thanks for explaining!

[kirklandnuts]

I think the following changes would help reduce confusion:

1. Instead of having this comment right above the project assignment statement, move it to apply to the entire provider block.
2. Clarify the comment to be more aligned with your explanatory comment above.

/*
This provider will be used to deploy AWLS's scanning resources. As such, it must be assigned as
the provider in the per-region AWLS module block where `global == true`. 
For reference, see module "lacework_gcp_agentless_scanning_project_multi_region_<alias1>", which
has `global = true` and therefore is where we set this provider as the google provider.
*/
provider "google" {
  alias  = <alias1>
  # Set the region in which the scanning resources will be hosted.
  region = <region1>
  # Set the project in which the scanning resources will be hosted.
  project = <your-project-id>
}

[kirklandnuts]

Beyond that, perhaps we can even be opinionated about the naming for this specific global provider/AWLS module - for example:

provider "google" {
  alias  = "scanning_resources"
  ...
}
 
...

module "lacework_gcp_agentless_scanning_project_multi_region_scanning_resources" {
  ...
  providers = {
    google = google.scanning_resources
  }
  ...
  global = true
  ...
}

Though I'm not sure if scanning_resources is the right choice here.

[wilderj]

Yeah, the inline comment explaining in more detail is a good idea. Just applied that to all of the relevant examples.

I held off on aliasing the module to something like scanning_resources or similar because I think this can actually cause additional confusion. Technically every module is for scanning resources, but the one with global = true will just also contain all of the once-per-integration resources as well. But I'd be hesitant to rename it to global_scanning_resources since it will also contain the per-region resources.