Document and format test outputs and variables

test/fixtures/full/extra_outputs.tf

@@ -15,5 +15,6 @@
  */
 
 output "extra_service_account_email" {
-  value = "${google_service_account.extra_service_account.email}"
+  description = "The email address of the extra service account"
+  value       = "${google_service_account.extra_service_account.email}"
 }

test/fixtures/full/main.tf

@@ -16,7 +16,7 @@
 
 provider "google" {
   credentials = "${file(var.credentials_path)}"
-  version = "~> 1.19"
+  version     = "~> 1.19"
 }
 
 provider "gsuite" {

test/fixtures/minimal/main.tf

@@ -16,7 +16,7 @@
 
 provider "google" {
   credentials = "${file(var.credentials_path)}"
-  version = "~> 1.19"
+  version     = "~> 1.19"
 }
 
 provider "gsuite" {
@@ -32,9 +32,9 @@ provider "gsuite" {
 }
 
 resource "random_string" "suffix" {
-  length = 5
+  length  = 5
   special = false
-  upper = false
+  upper   = false
 }
 
 module "project-factory" {

test/fixtures/shared/outputs.tf

@@ -15,54 +15,66 @@
  */
 
 output "project_id" {
-  value = "${module.project-factory.project_id}"
+  description = "The project ID of the created project."
+  value       = "${module.project-factory.project_id}"
 }
 
 output "project_number" {
-  value = "${module.project-factory.project_number}"
+  description = "The project number of the created project."
+  value       = "${module.project-factory.project_number}"
 }
 
 output "domain" {
-  value = "${module.project-factory.domain}"
+  description = "The organization's domain"
+  value       = "${module.project-factory.domain}"
 }
 
 output "group_email" {
-  value = "${module.project-factory.group_email}"
+  description = "The email of the created GSuite group with group_name"
+  value       = "${module.project-factory.group_email}"
 }
 
 output "group_role" {
-  value = "${var.group_role}"
+  description = "A forwarded copy of the `group_role` variable for access by InSpec"
+  value       = "${var.group_role}"
 }
 
 output "service_account_email" {
-  value = "${module.project-factory.service_account_email}"
+  description = "The email of the default service account"
+  value       = "${module.project-factory.service_account_email}"
 }
 
 output "gsuite_admin_account" {
-  value = "${var.gsuite_admin_account}"
+  description = "A forwarded copy of the `group_role` variable for access by InSpec"
+  value       = "${var.gsuite_admin_account}"
 }
 
 output "region" {
-  value = "${var.region}"
+  description = "A forwarded copy of the `region` variable for access by InSpec"
+  value       = "${var.region}"
 }
 
-// Pass through the `credentials_path` variable so that InSpec can reuse the credentials.
 output "credentials_path" {
-  value = "${var.credentials_path}"
+  description = "A forwarded copy of the `credentials_path` variable for access by InSpec"
+  value       = "${var.credentials_path}"
 }
 
 output "sa_role" {
-  value = "${var.sa_role}"
+  description = "A forwarded copy of the `sa_role` variable for access by InSpec"
+  value       = "${var.sa_role}"
 }
 
 output "shared_vpc" {
-  value = "${var.shared_vpc}"
+  description = "A forwarded copy of the `shared_vpc` variable for access by InSpec"
+  value       = "${var.shared_vpc}"
 }
 
 output "usage_bucket_name" {
-  value = "${var.usage_bucket_name}"
+  description = "A forwarded copy of the `usage_bucket_name` variable for access by InSpec"
+  value       = "${var.usage_bucket_name}"
 }
 
 output "usage_bucket_prefix" {
-  value = "${var.usage_bucket_prefix}"
+  description = "A forwarded copy of the `usage_bucket_prefix` variable for access by InSpec"
+  value       = "${var.usage_bucket_prefix}"
 }

test/fixtures/shared/variables.tf

@@ -14,53 +14,83 @@
  * limitations under the License.
  */
 
-variable "credentials_path" {}
+variable "credentials_path" {
+  description = "Path to a Service Account credentials file with permissions documented in the readme"
+}
 
-variable "org_id" {}
+variable "org_id" {
+  description = "The organization ID where test projects will be created."
+}
 
 variable "folder_id" {
-  default = ""
+  description = "The ID of a folder to host this project"
+  default     = ""
 }
 
 variable "domain" {
+  description = "The domain name"
 }
 
 variable "usage_bucket_name" {
-  default = ""
+  description = "Name of a GCS bucket to store GCE usage reports in (optional)"
+  default     = ""
 }
 
 variable "usage_bucket_prefix" {
-  default = ""
+  description = "Prefix in the GCS bucket to store GCE usage reports in (optional)"
+  default     = ""
 }
 
-variable "billing_account" {}
+variable "billing_account" {
+  description = "The ID of the billing account to associate this project with"
+}
 
 variable "group_name" {
-  default = ""
+  description = "A group to control the project by being assigned group_role (defaults to project editor)"
+  default     = ""
 }
 
 variable "create_group" {
-  default = "false"
+  description = "Whether to create the group or not"
+  default     = "false"
 }
 
 variable "group_role" {
-  default = "roles/viewer"
+  description = "The role to give the controlling group (group_name) over the project (defaults to project editor)"
+  default     = "roles/viewer"
 }
 
 variable "shared_vpc" {
+  description = <<EOD
+The Shared VPC host project. An additional network and subnet will be provisioned within
+this project. The provided project must already be configured as a shared VPC host.
+
+Example:
+
+```
+org_id=$(gcloud organizations list --format='get(name)')
+gcloud compute shared-vpc organizations list-host-projects $org_id
+```
+EOD
+
   default = ""
 }
 
 variable "sa_role" {
-  default = "roles/editor"
+  description = "A role to give the default Service Account for the project (defaults to none)"
+  default     = "roles/editor"
 }
 
 variable "sa_group" {
-  default = ""
+  description = "A GSuite group to place the default Service Account for the project in"
+  default     = ""
 }
 
 variable "region" {
-  default = "us-east4"
+  description = "The region where the `full` test fixture will deploy the Google App Engine instance"
+  default     = "us-east4"
 }
 
-variable "gsuite_admin_account" {}
+variable "gsuite_admin_account" {
+  description = "The G Suite admin account to impersonate when managing G Suite groups and group membership"
+}