Merge pull request #72 from omazin/fix-documentation

Rewrite upgrade guides. Update readme. Promote using submodules
terraform-google-modules · Nov 14, 2019 · 471b72a · 471b72a
2 parents 3f2362c + ad347b5
commit 471b72a
Show file tree

Hide file tree

Showing 3 changed files with 79 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -2,6 +2,18 @@
 
 This Terraform module makes it easier to non-destructively manage multiple IAM roles for resources on Google Cloud Platform.
 
+The module is a collection of submodules. We recommend using the specific resource submodules directly:
+* [Folders IAM](modules/folders_iam)
+* [KMS Crypto Keys IAM](modules/kms_crypto_keys_iam)
+* [KMS_Key Rings IAM](modules/kms_key_rings_iam)
+* [Organizations IAM](modules/organizations_iam)
+* [Projects IAM](modules/projects_iam)
+* [Pubsub Subscriptions IAM](modules/pubsub_subscriptions_iam)
+* [Pubsub Topics IAM](modules/pubsub_topics_iam)
+* [Service Accounts IAM](modules/service_accounts_iam)
+* [Storage Buckets IAM](modules/storage_buckets_iam)
+* [Subnets IAM](modules/subnets_iam)
+
 ## Compatibility
 
 This module is meant for use with Terraform 0.12. If you haven't
@@ -23,7 +35,7 @@ Full examples are in the [examples](./examples/) folder, but basic usage is as f
 ```hcl
 module "projects_iam_bindings" {
   source  = "terraform-google-modules/iam/google//modules/projects_iam"
-  version = "~> 3.0"
+  version = "~> 4.0"
 
   projects = ["project-123456", "project-9876543"]
 
@@ -50,7 +62,7 @@ The module also offers an **authoritative** mode which will remove all roles not
 ```hcl
 module "storage_buckets_iam_bindings" {
   source  = "terraform-google-modules/iam/google//modules/storage_buckets_iam"
-  version = "~> 3.0"
+  version = "~> 4.0"
 
   storage_buckets = ["my-storage-bucket"]
 
@@ -168,7 +180,7 @@ This Terraform module performs operations over some variables before making any
 
 ## IAM Bindings
 
-You can choose the following resource types for apply the IAM bindings:
+You can choose the following resource types to apply the IAM bindings:
 
 - Projects (`projects` variable)
 - Organizations(`organizations` variable)

diff --git a/docs/upgrading_to_iam_3.0.md b/docs/upgrading_to_iam_3.0.md
@@ -61,35 +61,32 @@ some additional variables to support this use case.
 
 ## Upgrade Instructions
 
-The generic `bindings` variable has been replaced with
-resource-specific variables, like `projects_bindings` or
-`folders_bindings`. Additionally, to support cases where dynamic values
-are used to define the bindings or the bindings targets, number
-variables are available to provide a static count of the contents, like
-`projects_num` and `projects_bindings_num`. Both `*_num`
-variables must be used regardless of which variable contains the
-dynamic content.
-
-To continue from the previous example, the following configurations
-highlight the changes required to upgrade the module to 3.0.
+We recommend using individual bindings target submodules that can be invoked
+directly. The following configurations highlight the approach in 3.0:
 
 ```diff
  module "iam" {
-   source  = "terraform-google-modules/iam/google"
+-  source  = "terraform-google-modules/iam/google"
++  source  = "terraform-google-modules/iam/google//modules/projects_iam"
 -  version = "~> 2.0"
 +  version = "~> 3.0"
 
    projects = ["project-123456"]
 
--  bindings = {
-+  projects_bindings = {
+   bindings = {
      "roles/storage.admin" = [
        "serviceAccount:[email protected]",
      ]
    }
  }
 ```
 
+Additionally, to support cases where dynamic values
+are used to define the bindings or the bindings targets, number
+variables are available to provide a static count of the contents, e.g.
+`projects_num` and `bindings_num`. Both `*_num` variables must be used
+regardless of which variable contains the dynamic content:
+
 ```diff
  module "project_factory" {
    source  = "terraform-google-modules/project-factory/google"
@@ -103,45 +100,64 @@ highlight the changes required to upgrade the module to 3.0.
  }
 
  module "iam" {
-   source  = "terraform-google-modules/iam/google"
+-  source  = "terraform-google-modules/iam/google"
++  source  = "terraform-google-modules/iam/google//modules/projects_iam"
 -  version = "~> 2.0"
 +  version = "~> 3.0"
 
    projects = [module.project_factory.project_id]
 
 +  projects_num = 1
 
--  bindings = {
-+  projects_bindings = {
+   bindings = {
      "roles/storage.admin" = [
        "serviceAccount:${module.project_factory.service_account_email}",
      ]
    }
 
-+  projects_bindings_num = 1
++  bindings_num = 1
  }
 ```
 
-Alternatively, individual bindings target submodules can be invoked
-directly. The following configurations highlight that approach.
+Alternatively, you can use a root module where generic `bindings` variable has
+ been replaced with resource-specific variables, like `projects_bindings` or
+`folders_bindings`. To continue from the previous example, the following
+configurations highlight the changes required to upgrade the module to 3.0:
 
 ```diff
  module "iam" {
--  source  = "terraform-google-modules/iam/google"
-+  source  = "terraform-google-modules/iam/google//modules/projects_iam"
+   source  = "terraform-google-modules/iam/google"
 -  version = "~> 2.0"
 +  version = "~> 3.0"
 
    projects = ["project-123456"]
 
-   bindings = {
+-  bindings = {
++  projects_bindings = {
      "roles/storage.admin" = [
        "serviceAccount:[email protected]",
      ]
    }
+
++  pubsub_topics_bindings = {}
++  pubsub_subscriptions_bindings = {}
++  storage_buckets_bindings = {}
++  subnets_bindings = {}
++  subnets_region = ""
++  organizations_bindings = {}
++  kms_crypto_keys_bindings = {}
++  kms_key_rings_bindings = {}
++  service_accounts_bindings = {}
++  folders_bindings = {}
  }
 ```
 
+In case of dynamic values are used to define the bindings or the bindings
+targets, number variables, e.g. `projects_num` and `projects_bindings_num`,
+are available to provide a static count of the contents. Both `*_num`
+variables must be used regardless of which variable contains the
+dynamic content:
+
 ```diff
  module "project_factory" {
    source  = "terraform-google-modules/project-factory/google"
@@ -155,20 +171,32 @@ directly. The following configurations highlight that approach.
  }
 
  module "iam" {
--  source  = "terraform-google-modules/iam/google"
-+  source  = "terraform-google-modules/iam/google//modules/projects_iam"
+   source  = "terraform-google-modules/iam/google"
 -  version = "~> 2.0"
 +  version = "~> 3.0"
 
    projects = [module.project_factory.project_id]
 
 +  projects_num = 1
 
-   bindings = {
+-  bindings = {
++  projects_bindings = {
      "roles/storage.admin" = [
        "serviceAccount:${module.project_factory.service_account_email}",
      ]
    }
 
-+  bindings_num = 1
++  projects_bindings_num = 1
+
++  pubsub_topics_bindings = {}
++  pubsub_subscriptions_bindings = {}
++  storage_buckets_bindings = {}
++  subnets_bindings = {}
++  subnets_region = ""
++  organizations_bindings = {}
++  kms_crypto_keys_bindings = {}
++  kms_key_rings_bindings = {}
++  service_accounts_bindings = {}
++  folders_bindings = {}
  }
+```
diff --git a/docs/upgrading_to_iam_4.0.md b/docs/upgrading_to_iam_4.0.md
@@ -35,24 +35,24 @@ module "project_factory_1" {
 }
 
 module "iam" {
-  source  = "terraform-google-modules/iam/google"
+  source  = "terraform-google-modules/iam/google//modules/projects_iam"
   version = "~> 3.0"
 
   projects = [module.project_factory_0.project_id, module.project_factory_1.project_id]
   projects_num = 2
 
-  projects_bindings = {
+  bindings = {
     "roles/storage.admin" = [
       "serviceAccount:${module.project_factory_0.service_account_email}",
       "serviceAccount:${module.project_factory_1.service_account_email}"
     ]
   }
-  projects_bindings_num = 2
+  bindings_num = 2
 }
 ```
 
 Note that you have to specify the additional options which look like
-they are redundant: `projects_num` and `projects_bindings_num`. These
+they are redundant: `projects_num` and `bindings_num`. These
 options had to be introduced in 3.0 to support the dynamic configuration
 usecase. Internally it was bounded to the way `count` works in terraform.
 
@@ -109,7 +109,7 @@ highlight the changes required to upgrade the module to 4.0.
  }
 
  module "iam" {
-   source  = "terraform-google-modules/iam/google"
+   source  = "terraform-google-modules/iam/google//modules/projects_iam"
 -  version = "~> 3.0"
 +  version = "~> 4.0"
 
@@ -119,24 +119,24 @@ highlight the changes required to upgrade the module to 4.0.
 +  projects = [module.project_factory_0.project_id]
 -  projects_num = 2
 
-   projects_bindings = {
+   bindings = {
      "roles/storage.admin" = [
        "serviceAccount:${module.project_factory_0.service_account_email}",
        "serviceAccount:${module.project_factory_1.service_account_email}"
      ]
    }
--  projects_bindings_num = 2
+-  bindings_num = 2
  }
 +
 +module "iam" {
-+  source  = "terraform-google-modules/iam/google"
++  source  = "terraform-google-modules/iam/google//modules/projects_iam"
 +  version = "~> 4.0"
 +
 +  mode = "authoritative"
 +
 +  projects = [module.project_factory_1.project_id]
 +
-+  projects_bindings = {
++  bindings = {
 +    "roles/storage.admin" = [
 +      "serviceAccount:${module.project_factory_0.service_account_email}",
 +      "serviceAccount:${module.project_factory_1.service_account_email}"