From 253c51d07ccfbfc58a5552fe8a9fd1123af65d98 Mon Sep 17 00:00:00 2001 From: Ludovico Magnocavallo Date: Fri, 10 Jan 2020 13:44:54 +0100 Subject: [PATCH] Update docs using tfdoc format (#28) * update README files * set all types on variables --- foundations/business-units/README.md | 75 ++++++++++----------- foundations/business-units/variables.tf | 7 ++ foundations/environments/README.md | 61 +++++++++-------- foundations/environments/variables.tf | 9 +++ infrastructure/hub-and-spoke-vpns/README.md | 52 +++++++------- infrastructure/shared-vpc/README.md | 51 +++++++------- infrastructure/shared-vpc/variables.tf | 18 +++++ tools/tfdoc/tfdoc.py | 0 8 files changed, 150 insertions(+), 123 deletions(-) mode change 100644 => 100755 tools/tfdoc/tfdoc.py diff --git a/foundations/business-units/README.md b/foundations/business-units/README.md index 297a0ab7..684579bc 100644 --- a/foundations/business-units/README.md +++ b/foundations/business-units/README.md @@ -25,45 +25,44 @@ The number of resources in this sample is kept to a minimum so as to make it gen This sample uses a top-level folder to encapsulate projects that host resources that are not specific to a single environment. If no shared services are needed,the Terraform and audit modules can be easily attached to the root node, and the shared services folder and project removed from `main.tf`. - -## Inputs + +## Variables -| Name | Description | Type | Default | Required | -|------|-------------|:----:|:-----:|:-----:| -| audit\_viewers | Audit project viewers, in IAM format. | list | `` | no | -| billing\_account\_id | Billing account id used as default for new projects. | string | n/a | yes | -| business\_unit\_1\_name | Business unit 1 short name. | string | n/a | yes | -| business\_unit\_2\_name | Business unit 2 short name. | string | n/a | yes | -| business\_unit\_3\_name | Business unit 3 short name. | string | n/a | yes | -| environments | Environment short names. | list(string) | n/a | yes | -| gcs\_location | GCS bucket location. | string | `"EU"` | no | -| generate\_service\_account\_keys | Generate and store service account keys in the state file. | string | `"false"` | no | -| organization\_id | Organization id. | string | n/a | yes | -| prefix | Prefix used for resources that need unique names. | string | n/a | yes | -| project\_services | Service APIs enabled by default in new projects. | list | `` | no | -| root\_node | Root node for the new hierarchy, either 'organizations/org_id' or 'folders/folder_id'. | string | n/a | yes | -| shared\_bindings\_members | List of comma-delimited IAM-format members for the additional shared project bindings. | list | `` | no | -| shared\_bindings\_roles | List of roles for additional shared project bindings. | list | `` | no | -| terraform\_owners | Terraform project owners, in IAM format. | list | `` | no | +| name | description | type | required | default | +|---|---|:---: |:---:|:---:| +| billing_account_id | Billing account id used as default for new projects. | string | ✓ | | +| business_unit_1_name | Business unit 1 short name. | string | ✓ | | +| business_unit_2_name | Business unit 2 short name. | string | ✓ | | +| business_unit_3_name | Business unit 3 short name. | string | ✓ | | +| environments | Environment short names. | list(string) | ✓ | | +| organization_id | Organization id. | string | ✓ | | +| prefix | Prefix used for resources that need unique names. | string | ✓ | | +| root_node | Root node for the new hierarchy, either 'organizations/org_id' or 'folders/folder_id'. | string | ✓ | | +| *audit_viewers* | Audit project viewers, in IAM format. | list(string) | | [] | +| *gcs_location* | GCS bucket location. | string | | EU | +| *generate_service_account_keys* | Generate and store service account keys in the state file. | bool | | false | +| *project_services* | Service APIs enabled by default in new projects. | list(string) | | ... | +| *shared_bindings_members* | List of comma-delimited IAM-format members for the additional shared project bindings. | list(string) | | [] | +| *shared_bindings_roles* | List of roles for additional shared project bindings. | list(string) | | [] | +| *terraform_owners* | Terraform project owners, in IAM format. | list(string) | | [] | ## Outputs -| Name | Description | -|------|-------------| -| audit\_logs\_bq\_dataset | Bigquery dataset for the audit logs export. | -| audit\_logs\_project | Project that holds the audit logs export resources. | -| bootstrap\_tf\_gcs\_bucket | GCS bucket used for the bootstrap Terraform state. | -| business\_unit\_1\_environment\_folders\_ids | Business unit 1 environment folders. | -| business\_unit\_1\_folder\_id | Business unit 1 top-level folder ID. | -| business\_unit\_2\_environment\_folders\_ids | Business unit 2 environment folders. | -| business\_unit\_2\_folder\_id | Business unit 2 top-level folder ID. | -| business\_unit\_3\_environment\_folders\_ids | Business unit 3 environment folders. | -| business\_unit\_3\_folder\_id | Business unit 3 top-level folder ID. | -| environment\_service\_account\_keys | Service account keys used to run each environment Terraform modules. | -| environment\_service\_accounts | Service accounts used to run each environment Terraform modules. | -| environment\_tf\_gcs\_buckets | GCS buckets used for each environment Terraform state. | -| shared\_folder\_id | Shared folder ID. | -| shared\_resources\_project | Project that holdes resources shared across business units. | -| terraform\_project | Project that holds the base Terraform resources. | - - +| name | description | sensitive | +|---|---|:---:| +| audit_logs_bq_dataset | Bigquery dataset for the audit logs export. | | +| audit_logs_project | Project that holds the audit logs export resources. | | +| bootstrap_tf_gcs_bucket | GCS bucket used for the bootstrap Terraform state. | | +| business_unit_1_environment_folders_ids | Business unit 1 environment folders. | | +| business_unit_1_folder_id | Business unit 1 top-level folder ID. | | +| business_unit_2_environment_folders_ids | Business unit 2 environment folders. | | +| business_unit_2_folder_id | Business unit 2 top-level folder ID. | | +| business_unit_3_environment_folders_ids | Business unit 3 environment folders. | | +| business_unit_3_folder_id | Business unit 3 top-level folder ID. | | +| environment_service_account_keys | Service account keys used to run each environment Terraform modules. | ✓ | +| environment_service_accounts | Service accounts used to run each environment Terraform modules. | | +| environment_tf_gcs_buckets | GCS buckets used for each environment Terraform state. | | +| shared_folder_id | Shared folder ID. | | +| shared_resources_project | Project that holdes resources shared across business units. | | +| terraform_project | Project that holds the base Terraform resources. | | + diff --git a/foundations/business-units/variables.tf b/foundations/business-units/variables.tf index c25a1755..3dbecffd 100644 --- a/foundations/business-units/variables.tf +++ b/foundations/business-units/variables.tf @@ -14,6 +14,7 @@ variable "audit_viewers" { description = "Audit project viewers, in IAM format." + type = list(string) default = [] } @@ -44,11 +45,13 @@ variable "environments" { variable "generate_service_account_keys" { description = "Generate and store service account keys in the state file." + type = bool default = false } variable "gcs_location" { description = "GCS bucket location." + type = string default = "EU" } @@ -70,21 +73,25 @@ variable "root_node" { variable "shared_bindings_members" { description = "List of comma-delimited IAM-format members for the additional shared project bindings." # example: ["user:a@example.com,b@example.com", "user:c@example.com"] + type = list(string) default = [] } variable "shared_bindings_roles" { description = "List of roles for additional shared project bindings." # example: ["roles/storage.objectViewer", "roles/storage.admin"] + type = list(string) default = [] } variable "terraform_owners" { description = "Terraform project owners, in IAM format." + type = list(string) default = [] } variable "project_services" { description = "Service APIs enabled by default in new projects." + type = list(string) default = [ "resourceviews.googleapis.com", "stackdriver.googleapis.com", diff --git a/foundations/environments/README.md b/foundations/environments/README.md index 70208f63..3e13134f 100644 --- a/foundations/environments/README.md +++ b/foundations/environments/README.md @@ -27,38 +27,37 @@ For more complex setups where multiple shared services projects are needed to en If no shared services are needed, the shared service project module can of course be removed from `main.tf`. - -## Inputs + +## Variables -| Name | Description | Type | Default | Required | -|------|-------------|:----:|:-----:|:-----:| -| audit\_viewers | Audit project viewers, in IAM format. | list | `` | no | -| billing\_account\_id | Billing account id used as default for new projects. | string | n/a | yes | -| environments | Environment short names. | list(string) | n/a | yes | -| gcs\_location | GCS bucket location. | string | `"EU"` | no | -| generate\_service\_account\_keys | Generate and store service account keys in the state file. | string | `"false"` | no | -| grant\_xpn\_folder\_roles | Grant roles needed for Shared VPC creation to service accounts at the environment folder level. | string | `"true"` | no | -| grant\_xpn\_org\_roles | Grant roles needed for Shared VPC creation to service accounts at the organization level. | string | `"false"` | no | -| organization\_id | Organization id. | string | n/a | yes | -| prefix | Prefix used for resources that need unique names. | string | n/a | yes | -| project\_services | Service APIs enabled by default in new projects. | list | `` | no | -| root\_node | Root node for the new hierarchy, either 'organizations/org_id' or 'folders/folder_id'. | string | n/a | yes | -| shared\_bindings\_members | List of comma-delimited IAM-format members for the additional shared project bindings. | list | `` | no | -| shared\_bindings\_roles | List of roles for additional shared project bindings. | list | `` | no | -| terraform\_owners | Terraform project owners, in IAM format. | list | `` | no | +| name | description | type | required | default | +|---|---|:---: |:---:|:---:| +| billing_account_id | Billing account id used as default for new projects. | string | ✓ | | +| environments | Environment short names. | list(string) | ✓ | | +| organization_id | Organization id. | string | ✓ | | +| prefix | Prefix used for resources that need unique names. | string | ✓ | | +| root_node | Root node for the new hierarchy, either 'organizations/org_id' or 'folders/folder_id'. | string | ✓ | | +| *audit_viewers* | Audit project viewers, in IAM format. | list(string) | | [] | +| *gcs_location* | GCS bucket location. | string | | EU | +| *generate_service_account_keys* | Generate and store service account keys in the state file. | bool | | false | +| *grant_xpn_folder_roles* | Grant roles needed for Shared VPC creation to service accounts at the environment folder level. | bool | | true | +| *grant_xpn_org_roles* | Grant roles needed for Shared VPC creation to service accounts at the organization level. | bool | | false | +| *project_services* | Service APIs enabled by default in new projects. | list(string) | | ... | +| *shared_bindings_members* | List of comma-delimited IAM-format members for the additional shared project bindings. | list(string) | | [] | +| *shared_bindings_roles* | List of roles for additional shared project bindings. | list(string) | | [] | +| *terraform_owners* | Terraform project owners, in IAM format. | list(string) | | [] | ## Outputs -| Name | Description | -|------|-------------| -| audit\_logs\_bq\_dataset | Bigquery dataset for the audit logs export. | -| audit\_logs\_project | Project that holds the audit logs export resources. | -| bootstrap\_tf\_gcs\_bucket | GCS bucket used for the bootstrap Terraform state. | -| environment\_folders | Top-level environment folders. | -| environment\_service\_account\_keys | Service account keys used to run each environment Terraform modules. | -| environment\_service\_accounts | Service accounts used to run each environment Terraform modules. | -| environment\_tf\_gcs\_buckets | GCS buckets used for each environment Terraform state. | -| shared\_resources\_project | Project that holdes resources shared across environments. | -| terraform\_project | Project that holds the base Terraform resources. | - - +| name | description | sensitive | +|---|---|:---:| +| audit_logs_bq_dataset | Bigquery dataset for the audit logs export. | | +| audit_logs_project | Project that holds the audit logs export resources. | | +| bootstrap_tf_gcs_bucket | GCS bucket used for the bootstrap Terraform state. | | +| environment_folders | Top-level environment folders. | | +| environment_service_account_keys | Service account keys used to run each environment Terraform modules. | ✓ | +| environment_service_accounts | Service accounts used to run each environment Terraform modules. | | +| environment_tf_gcs_buckets | GCS buckets used for each environment Terraform state. | | +| shared_resources_project | Project that holdes resources shared across environments. | | +| terraform_project | Project that holds the base Terraform resources. | | + diff --git a/foundations/environments/variables.tf b/foundations/environments/variables.tf index 2b8e6f09..113fcddb 100644 --- a/foundations/environments/variables.tf +++ b/foundations/environments/variables.tf @@ -14,6 +14,7 @@ variable "audit_viewers" { description = "Audit project viewers, in IAM format." + type = list(string) default = [] } @@ -29,21 +30,25 @@ variable "environments" { variable "generate_service_account_keys" { description = "Generate and store service account keys in the state file." + type = bool default = false } variable "gcs_location" { description = "GCS bucket location." + type = string default = "EU" } variable "grant_xpn_org_roles" { description = "Grant roles needed for Shared VPC creation to service accounts at the organization level." + type = bool default = false } variable "grant_xpn_folder_roles" { description = "Grant roles needed for Shared VPC creation to service accounts at the environment folder level." + type = bool default = true } @@ -65,21 +70,25 @@ variable "root_node" { variable "shared_bindings_members" { description = "List of comma-delimited IAM-format members for the additional shared project bindings." # example: ["user:a@example.com,b@example.com", "user:c@example.com"] + type = list(string) default = [] } variable "shared_bindings_roles" { description = "List of roles for additional shared project bindings." # example: ["roles/storage.objectViewer", "roles/storage.admin"] + type = list(string) default = [] } variable "terraform_owners" { description = "Terraform project owners, in IAM format." + type = list(string) default = [] } variable "project_services" { description = "Service APIs enabled by default in new projects." + type = list(string) default = [ "resourceviews.googleapis.com", "stackdriver.googleapis.com", diff --git a/infrastructure/hub-and-spoke-vpns/README.md b/infrastructure/hub-and-spoke-vpns/README.md index 855dd684..adbc4fcd 100644 --- a/infrastructure/hub-and-spoke-vpns/README.md +++ b/infrastructure/hub-and-spoke-vpns/README.md @@ -48,34 +48,32 @@ SSH access to instances is configured via [OS Login](https://cloud.google.com/co - Please refer to the [bug](https://github.com/terraform-providers/terraform-provider-google/issues/3753) for more details. - Please refer to the [documentation](https://cloud.google.com/dns/zones/#creating_a_dns_policy_that_enables_inbound_dns_forwarding) on how to get the IPs with `gcloud`. - -## Inputs + +## Variables -| Name | Description | Type | Default | Required | -|------|-------------|:----:|:-----:|:-----:| -| forwarding\_dns\_zone\_domain | Forwarding DNS Zone Domain. | string | `"on-prem.local."` | no | -| forwarding\_dns\_zone\_name | Forwarding DNS Zone Name. | string | `"on-prem-local"` | no | -| forwarding\_zone\_server\_addresses | Forwarding DNS Zone Server Addresses | list(string) | `` | no | -| hub\_bgp\_asn | Hub BGP ASN. | number | `"64515"` | no | -| hub\_project\_id | Hub Project id. Same project can be used for hub and spokes. | string | n/a | yes | -| hub\_subnets | Hub VPC subnets configuration. | object | `` | no | -| private\_dns\_zone\_domain | Private DNS Zone Domain. | string | `"gcp.local."` | no | -| private\_dns\_zone\_name | Private DNS Zone Name. | string | `"gcp-local"` | no | -| spoke\_1\_bgp\_asn | Spoke 1 BGP ASN. | number | `"64516"` | no | -| spoke\_1\_project\_id | Spoke 1 Project id. Same project can be used for hub and spokes. | string | n/a | yes | -| spoke\_1\_subnets | Spoke 1 VPC subnets configuration. | list | `` | no | -| spoke\_2\_bgp\_asn | Spoke 2 BGP ASN. | number | `"64517"` | no | -| spoke\_2\_project\_id | Spoke 2 Project id. Same project can be used for hub and spokes. | string | n/a | yes | -| spoke\_2\_subnets | Spoke 2 VPC subnets configuration. | list | `` | no | -| spoke\_to\_spoke\_route\_advertisement | Use custom route advertisement in hub routers to advertise all spoke subnets. | bool | `"true"` | no | +| name | description | type | required | default | +|---|---|:---: |:---:|:---:| +| hub_project_id | Hub Project id. Same project can be used for hub and spokes. | string | ✓ | | +| spoke_1_project_id | Spoke 1 Project id. Same project can be used for hub and spokes. | string | ✓ | | +| spoke_2_project_id | Spoke 2 Project id. Same project can be used for hub and spokes. | string | ✓ | | +| *forwarding_dns_zone_domain* | Forwarding DNS Zone Domain. | string | | on-prem.local. | +| *forwarding_dns_zone_name* | Forwarding DNS Zone Name. | string | | on-prem-local | +| *forwarding_zone_server_addresses* | Forwarding DNS Zone Server Addresses | list(string) | | ["8.8.8.8", "8.8.4.4"] | +| *hub_bgp_asn* | Hub BGP ASN. | number | | 64515 | +| *hub_subnets* | Hub VPC subnets configuration. | list(object({...})) | | ... | +| *private_dns_zone_domain* | Private DNS Zone Domain. | string | | gcp.local. | +| *private_dns_zone_name* | Private DNS Zone Name. | string | | gcp-local | +| *spoke_1_bgp_asn* | Spoke 1 BGP ASN. | number | | 64516 | +| *spoke_1_subnets* | Spoke 1 VPC subnets configuration. | | | ... | +| *spoke_2_bgp_asn* | Spoke 2 BGP ASN. | number | | 64517 | +| *spoke_2_subnets* | Spoke 2 VPC subnets configuration. | | | ... | +| *spoke_to_spoke_route_advertisement* | Use custom route advertisement in hub routers to advertise all spoke subnets. | bool | | true | ## Outputs -| Name | Description | -|------|-------------| -| hub | Hub network resources. | -| spoke-1 | Spoke1 network resources. | -| spoke-2 | Spoke2 network resources. | -| test-instances | Test instance attributes. | - - \ No newline at end of file +| name | description | sensitive | +|---|---|:---:| +| hub | Hub network resources. | | +| spoke-1 | Spoke1 network resources. | | +| spoke-2 | Spoke2 network resources. | | + diff --git a/infrastructure/shared-vpc/README.md b/infrastructure/shared-vpc/README.md index 75ef68fd..9bec065a 100644 --- a/infrastructure/shared-vpc/README.md +++ b/infrastructure/shared-vpc/README.md @@ -31,34 +31,31 @@ The networking and GKE instances have `dig` and the `mysql` client installed via There's a minor glitch that can surface running `terraform destroy`, with a simple workaround. The glitch is due to a delay between the API reporting service project removal from the Shared VPC as successful (`google_compute_shared_vpc_service_project` resources destroyed), and the Shared VPC resource being aligned with that event. This results in an error that prevents disabling the Shared VPC feature: `Error disabling Shared VPC Host [...] Cannot disable project as a shared VPC host because it has active service projects.`. The workaround is to run `terraform destroy` again after a few seconds, giving the Shared VPC resource time to be in sync with service project removal. - -## Inputs + +## Variables -| Name | Description | Type | Default | Required | -|------|-------------|:----:|:-----:|:-----:| -| billing\_account\_id | Billing account id used as default for new projects. | string | n/a | yes | -| kms\_keyring\_location | Location used for the KMS keyring. | string | `"europe"` | no | -| kms\_keyring\_name | Name used for the KMS keyring. | string | `"svpc-example"` | no | -| oslogin\_admins\_gce | GCE project oslogin admin members, in IAM format. | list | `` | no | -| oslogin\_users\_gce | GCE project oslogin user members, in IAM format. | list | `` | no | -| owners\_gce | GCE project owners, in IAM format. | list | `` | no | -| owners\_gke | GKE project owners, in IAM format. | list | `` | no | -| owners\_host | Host project owners, in IAM format. | list | `` | no | -| prefix | Prefix used for resources that need unique names. | string | n/a | yes | -| project\_services | Service APIs enabled by default in new projects. | list | `` | no | -| root\_node | Hierarchy node where projects will be created, 'organizations/org_id' or 'folders/folder_id'. | string | n/a | yes | -| subnet\_secondary\_ranges | Shared VPC subnets secondary range definitions. | map | `` | no | -| subnets | Shared VPC subnet definitions. | list | `` | no | +| name | description | type | required | default | +|---|---|:---: |:---:|:---:| +| billing_account_id | Billing account id used as default for new projects. | string | ✓ | | +| prefix | Prefix used for resources that need unique names. | string | ✓ | | +| root_node | Hierarchy node where projects will be created, 'organizations/org_id' or 'folders/folder_id'. | string | ✓ | | +| *kms_keyring_location* | Location used for the KMS keyring. | string | | europe | +| *kms_keyring_name* | Name used for the KMS keyring. | string | | svpc-example | +| *oslogin_admins_gce* | GCE project oslogin admin members, in IAM format. | list(string) | | [] | +| *oslogin_users_gce* | GCE project oslogin user members, in IAM format. | list(string) | | [] | +| *owners_gce* | GCE project owners, in IAM format. | list(string) | | [] | +| *owners_gke* | GKE project owners, in IAM format. | list(string) | | [] | +| *owners_host* | Host project owners, in IAM format. | list(string) | | [] | +| *project_services* | Service APIs enabled by default in new projects. | list(string) | | ... | +| *subnet_secondary_ranges* | Shared VPC subnets secondary range definitions. | map(list(object({...}))) | | ... | +| *subnets* | Shared VPC subnet definitions. | list(object({...})) | | ... | ## Outputs -| Name | Description | -|------|-------------| -| host\_project\_id | VPC host project id. | -| mysql-root-password | Password for the test MySQL db root user. | -| service\_project\_ids | Service project ids. | -| test-instances | Test instance names. | -| vpc\_name | Shared VPC name | -| vpc\_subnets | Shared VPC subnets. | - - +| name | description | sensitive | +|---|---|:---:| +| host_project_id | VPC host project id. | | +| service_project_ids | Service project ids. | | +| vpc_name | Shared VPC name | | +| vpc_subnets | Shared VPC subnets. | | + diff --git a/infrastructure/shared-vpc/variables.tf b/infrastructure/shared-vpc/variables.tf index 0efe0bab..0f1f03fa 100644 --- a/infrastructure/shared-vpc/variables.tf +++ b/infrastructure/shared-vpc/variables.tf @@ -19,36 +19,43 @@ variable "billing_account_id" { variable "kms_keyring_location" { description = "Location used for the KMS keyring." + type = string default = "europe" } variable "kms_keyring_name" { description = "Name used for the KMS keyring." + type = string default = "svpc-example" } variable "oslogin_admins_gce" { description = "GCE project oslogin admin members, in IAM format." + type = list(string) default = [] } variable "oslogin_users_gce" { description = "GCE project oslogin user members, in IAM format." + type = list(string) default = [] } variable "owners_gce" { description = "GCE project owners, in IAM format." + type = list(string) default = [] } variable "owners_gke" { description = "GKE project owners, in IAM format." + type = list(string) default = [] } variable "owners_host" { description = "Host project owners, in IAM format." + type = list(string) default = [] } @@ -64,6 +71,12 @@ variable "root_node" { variable "subnets" { description = "Shared VPC subnet definitions." + type = list(object({ + subnet_name = string + subnet_ip = string + subnet_region = string + subnet_private_access = string + })) default = [ { subnet_name = "networking" @@ -88,6 +101,10 @@ variable "subnets" { variable "subnet_secondary_ranges" { description = "Shared VPC subnets secondary range definitions." + type = map(list(object({ + range_name = string + ip_cidr_range = string + }))) default = { networking = [], gce = [], @@ -106,6 +123,7 @@ variable "subnet_secondary_ranges" { variable "project_services" { description = "Service APIs enabled by default in new projects." + type = list(string) default = [ "resourceviews.googleapis.com", "stackdriver.googleapis.com", diff --git a/tools/tfdoc/tfdoc.py b/tools/tfdoc/tfdoc.py old mode 100644 new mode 100755