feat: Add custom_role submodule (terraform-google-modules#95)

* Added custom_role submodule

* Changed count for org level custom role resource

* Addressing PR comments

* Addressing PR comments, added org example and integration test

* Added Org Role Admin permission to project SA in test/setup.

* Addressing PR comments

* Fixed integration tests and lint issues

* Added random bit for role_id for org level custom role

* Added registry in README

* Setting description default

* Fixed README for module

Co-authored-by: Kunal Kumar Gupta <kunalkgupta@kunalkgupta-macbookpro3.roam.corp.google.com>

.kitchen.yml

@@ -97,3 +97,16 @@ suites:
           backend: local
     provisioner:
       name: terraform
+
+  - name: custom-role
+    driver:
+      name: terraform
+      command_timeout: 1800
+      root_module_directory: test/fixtures/custom-role
+    verifier:
+      name: terraform
+      systems:
+        - name: custom-role
+          backend: local
+    provisioner:
+      name: terraform

build/int.cloudbuild.yaml

@@ -67,6 +67,28 @@ steps:
   name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
   args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do destroy billing-iam-local']
 
+# ----- SUITE custom-role-local
+
+- id: create custom-role-local
+  waitFor:
+    - prepare
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do create custom-role-local']
+- id: converge custom-role-local
+  waitFor:
+    - create custom-role-local
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do converge custom-role-local']
+- id: verify custom-role-local
+  waitFor:
+    - converge custom-role-local
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do verify custom-role-local']
+- id: destroy custom-role-local
+  waitFor:
+    - verify custom-role-local
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do destroy custom-role-local']
 
 # ----- SUITE additive-local
 

examples/custom_role_org/README.md

@@ -0,0 +1,19 @@
+# Organization Level Custom Role Example
+
+This example illustrates how to use the `custom_role_iam` submodule to create a custom role at the organization level.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| org\_id | Variable for Organization ID. | string | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| role\_id | ID of the custom role created at organization level. |
+
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+

examples/custom_role_org/main.tf

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/******************************************
+  Provider configuration
+ *****************************************/
+provider "google" {
+  version = "~> 3.3"
+}
+
+provider "google-beta" {
+  version = "~> 3.3"
+}
+
+resource "random_id" "rand_custom_id" {
+  byte_length = 2
+}
+
+/******************************************
+  Module custom_role call
+ *****************************************/
+module "custom-roles-org" {
+  source = "../../modules/custom_role_iam/"
+
+  target_level = "org"
+  target_id    = var.org_id
+  role_id      = "iamDeleter_${random_id.rand_custom_id.hex}"
+  permissions  = ["iam.roles.list", "iam.roles.delete"]
+}

examples/custom_role_org/outputs.tf

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+output "role_id" {
+  value       = module.custom-roles-org.custom_role_id
+  description = "ID of the custom role created at organization level."
+}

examples/custom_role_org/variables.tf

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+variable "org_id" {
+  type        = string
+  description = "Variable for Organization ID."
+}

examples/custom_role_org/versions.tf

@@ -0,0 +1,19 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+terraform {
+  required_version = ">= 0.12"
+}

examples/custom_role_project/README.md

@@ -0,0 +1,19 @@
+# Project Level Custom Role Example
+
+This example illustrates how to use the `custom_role_iam` submodule to create a custom role at the project level.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| project\_id | Variable for Project ID. | string | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| role\_id | ID of the custom role created at project level. |
+
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+

examples/custom_role_project/main.tf

@@ -0,0 +1,38 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/******************************************
+  Provider configuration
+ *****************************************/
+provider "google" {
+  version = "~> 3.3"
+}
+
+provider "google-beta" {
+  version = "~> 3.3"
+}
+
+/******************************************
+  Module custom_role call
+ *****************************************/
+module "custom-role-project" {
+  source = "../../modules/custom_role_iam/"
+
+  target_level = "project"
+  target_id    = var.project_id
+  role_id      = "iamDeleter"
+  permissions  = ["iam.roles.list", "iam.roles.delete"]
+}

examples/custom_role_project/outputs.tf

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+output "role_id" {
+  value       = module.custom-role-project.custom_role_id
+  description = "ID of the custom role created at project level."
+}

examples/custom_role_project/variables.tf

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+variable "project_id" {
+  type        = string
+  description = "Variable for Project ID."
+}

examples/custom_role_project/versions.tf

@@ -0,0 +1,19 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+terraform {
+  required_version = ">= 0.12"
+}

modules/custom_role_iam/README.md

@@ -0,0 +1,54 @@
+# Module Custom Role IAM
+
+This optional module is used to create custom roles at organization or project level.
+
+## Usage - Custom Role at Organization Level
+
+```hcl
+module "custom-roles" {
+  source = "terraform-google-modules/iam/google//modules/custom_role_iam"
+
+  target_level = "org"
+  target_id       = "123456789"
+  role_id      = "custom_role_id"
+  title        = "Custom Role Unique Title"
+  description  = "Custom Role Description"
+  permissions  = ["iam.roles.list", "iam.roles.create", "iam.roles.delete"]
+}
+```
+
+## Usage - Custom Role at Project Level
+
+```hcl
+module "custom-roles" {
+  source = "terraform-google-modules/iam/google//modules/custom_role_iam"
+
+  target_level = "project"
+  target_id   = "project_id_123"
+  role_id      = "custom_role_id"
+  title        = "Custom Role Unique Title"
+  description  = "Custom Role Description"
+  permissions  = ["iam.roles.list", "iam.roles.create", "iam.roles.delete"]
+}
+```
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| description | Description of Custom role. | string | `""` | no |
+| permissions | IAM permissions assigned to Custom Role. | list(string) | n/a | yes |
+| role\_id | ID of the Custom Role. | string | n/a | yes |
+| stage | The current launch stage of the role. Defaults to GA. | string | `"GA"` | no |
+| target\_id | Variable for project or organization ID. | string | n/a | yes |
+| target\_level | String variable to denote if custom role being created is at project or organization level. | string | `"project"` | no |
+| title | Human-readable title of the Custom Role, defaults to role_id. | string | `""` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| custom\_role\_id | ID of the custom role created. |
+
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

modules/custom_role_iam/main.tf

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+locals {
+  custom-role-output = (var.target_level == "project") ? google_project_iam_custom_role.project-custom-role[0].role_id : google_organization_iam_custom_role.org-custom-role[0].role_id
+}
+
+/******************************************
+  Custom IAM Org Role
+ *****************************************/
+resource "google_organization_iam_custom_role" "org-custom-role" {
+  count = var.target_level == "org" ? 1 : 0
+
+  org_id      = var.target_id
+  role_id     = var.role_id
+  title       = var.title == "" ? var.role_id : var.title
+  permissions = var.permissions
+}
+
+/******************************************
+  Custom IAM Project Role
+ *****************************************/
+resource "google_project_iam_custom_role" "project-custom-role" {
+  count = var.target_level == "project" ? 1 : 0
+
+  project     = var.target_id
+  role_id     = var.role_id
+  title       = var.title == "" ? var.role_id : var.title
+  permissions = var.permissions
+}