feat(INT-53): bring in tf module from existing repo (#1)

## what

- bring in existing postgres module under new repo name

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
- Introduced comprehensive support for managing Google Workspace users,
groups, group settings, and group memberships via Terraform.
- Added detailed input variables for users and groups with extensive
validation.
- Provided example configurations and import workflows for existing
organizations using YAML and Terraform files.

- **Documentation**
- Rewrote and expanded the README with Google Workspace-specific usage
instructions, examples, and input schemas.
- Updated provider and resource documentation to reflect new
functionality.

- **Bug Fixes**
- Improved input validation for user and group attributes, ensuring
correct email formats and allowed values.

- **Tests**
- Added extensive test coverage for user and group variable validation,
including edge cases and failure scenarios.

- **Chores**
  - Updated .gitignore rules and removed outdated changelog entries.
- Removed obsolete outputs and variables related to previous random
resource usage.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Matt Gowie <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

.github/renovate.json5

@@ -61,4 +61,4 @@
       "groupName": "tf"
     }
   ]
-}
+}

.gitignore

@@ -9,9 +9,15 @@
 # Local .terraform directories
 **/.terraform/*
 
+# Example terraform lock files
+examples/**/*.terraform.lock.hcl
+
 # Ignore the root .terraform.lock.hcl file (Child modules don't want this)
 .terraform.lock.hcl
-!examples/**/.terraform.lock.hcl
+# !examples/**/.terraform.lock.hcl
+
+# Ignore the live-providers.tf file
+examples/**/live-provider.tf
 
 # IDE/Editor settings
 **/.idea
@@ -44,3 +50,6 @@ backend.tf.json
 **/*.bak
 **/*.*swp
 **/.DS_Store
+
+
+

CHANGELOG.md

@@ -1,7 +1,5 @@
 # Changelog
 
-## [0.7.0](https://github.com/masterpointio/terraform-module-template/compare/v0.6.0...v0.7.0) (2025-05-07)
-
 
 ### Features
 

README.md

@@ -1,24 +1,82 @@
 [![Banner][banner-image]](https://masterpoint.io/)
 
-# terraform-module-template
+# terraform-googleworkspace-users-groups-automation
 
 [![Release][release-badge]][latest-release]
 
 💡 Learn more about Masterpoint [below](#who-we-are-𐦂𖨆𐀪𖠋).
 
 ## Purpose and Functionality
 
-This repository serves as a template for creating Terraform modules, providing a standardized structure and essential files for efficient module development. It's designed to ensure consistency and our best practices across Terraform projects.
+This is a [child-module](https://opentofu.org/docs/language/modules/#child-modules) for managing Google Workspace users, groups, and roles.
 
 ## Usage
 
-### Prerequisites (optional)
-
-TODO
-
 ### Step-by-Step Instructions
 
-TODO
+There are 2 provider authentication routes available,
+1 - authenticate a service account via API keys
+2 - authenticate using API keys and impersonate a real User with Super Admin privileges.
+
+We recommend impersonating a Super Admin, which allows you to grant Admin privileges to users (service Accounts cannot do this).
+
+Follow the provider [authentication setup instructions](https://github.com/hashicorp/terraform-provider-googleworkspace/blob/main/docs/index.md#google-workspace-provider).
+
+<!-- TODO(weston) - provide step by step instructions for setting this up -->
+
+Once you've finished the setup process, your provider block should look like this,
+
+```hcl
+provider "googleworkspace" {
+  # use 'my_customer', which is an alias that Google's API recognizes to reference your account's customerId.
+  # For example - Custom Schemas on the user object will fail if the customer_id is set to your actual customer_id.
+  # For more details see: https://developers.google.com/workspace/admin/directory/reference/rest/v1/schemas/get
+  customer_id = "my_customer"
+
+  credentials             = "/path/to/credentials/my-google-project-credentials-1234567890.json"
+  impersonated_user_email = "my_impersonated_user_email@my_domain.com"
+
+  oauth_scopes = [
+    "https://www.googleapis.com/auth/admin.directory.group",
+    "https://www.googleapis.com/auth/admin.directory.user",
+    "https://www.googleapis.com/auth/admin.directory.userschema",
+    "https://www.googleapis.com/auth/apps.groups.settings",
+    "https://www.googleapis.com/auth/iam",
+  ]
+}
+```
+
+## Example
+
+```hcl
+module "googleworkspace_users_groups" {
+  source = "git::https://github.com/masterpointio/terraform-googleworkspace-users-groups-automation.git"
+
+  users = {
+    "[email protected]" = {
+      primary_email = "[email protected]"
+      family_name   = "Last"
+      given_name    = "First"
+      password      = "example-password"
+      groups = {
+        "platform" = {
+          role = "member"
+        }
+      }
+    }
+  }
+
+  groups = {
+    "platform" = {
+      name     = "Platform"
+      email    = "[email protected]"
+      settings = {
+        who_can_join = "ALL_IN_DOMAIN_CAN_JOIN"
+      }
+    }
+  }
+}
+```
 
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable MD013 -->
@@ -28,13 +86,13 @@ TODO
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
-| <a name="requirement_random"></a> [random](#requirement\_random) | >= 3.0 |
+| <a name="requirement_googleworkspace"></a> [googleworkspace](#requirement\_googleworkspace) | >= 0.7.0 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_random"></a> [random](#provider\_random) | >= 3.0 |
+| <a name="provider_googleworkspace"></a> [googleworkspace](#provider\_googleworkspace) | >= 0.7.0 |
 
 ## Modules
 
@@ -46,7 +104,10 @@ TODO
 
 | Name | Type |
 |------|------|
-| [random_pet.template](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/pet) | resource |
+| [googleworkspace_group.defaults](https://registry.terraform.io/providers/hashicorp/googleworkspace/latest/docs/resources/group) | resource |
+| [googleworkspace_group_member.user_to_groups](https://registry.terraform.io/providers/hashicorp/googleworkspace/latest/docs/resources/group_member) | resource |
+| [googleworkspace_group_settings.defaults](https://registry.terraform.io/providers/hashicorp/googleworkspace/latest/docs/resources/group_settings) | resource |
+| [googleworkspace_user.defaults](https://registry.terraform.io/providers/hashicorp/googleworkspace/latest/docs/resources/user) | resource |
 
 ## Inputs
 
@@ -59,24 +120,23 @@ TODO
 | <a name="input_descriptor_formats"></a> [descriptor\_formats](#input\_descriptor\_formats) | Describe additional descriptors to be output in the `descriptors` output map.<br/>Map of maps. Keys are names of descriptors. Values are maps of the form<br/>`{<br/>   format = string<br/>   labels = list(string)<br/>}`<br/>(Type is `any` so the map values can later be enhanced to provide additional options.)<br/>`format` is a Terraform format string to be passed to the `format()` function.<br/>`labels` is a list of labels, in order, to pass to `format()` function.<br/>Label values will be normalized before being passed to `format()` so they will be<br/>identical to how they appear in `id`.<br/>Default is `{}` (`descriptors` output will be empty). | `any` | `{}` | no |
 | <a name="input_enabled"></a> [enabled](#input\_enabled) | Set to false to prevent the module from creating any resources | `bool` | `null` | no |
 | <a name="input_environment"></a> [environment](#input\_environment) | ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' | `string` | `null` | no |
+| <a name="input_groups"></a> [groups](#input\_groups) | List of groups | <pre>map(object({<br/>    name : string,<br/>    description : optional(string),<br/>    email : string,<br/>    timeouts : optional(object({<br/>      create : optional(string),<br/>      update : optional(string),<br/>      }), {<br/>      create = null<br/>      update = null<br/>    }),<br/>    # https://registry.terraform.io/providers/hashicorp/googleworkspace/latest/docs/resources/group_settings<br/>    settings : optional(object({<br/>      allow_external_members : optional(bool),<br/>      allow_web_posting : optional(bool),<br/>      archive_only : optional(bool),<br/>      custom_footer_text : optional(string),<br/>      custom_reply_to : optional(string),<br/>      default_message_deny_notification_text : optional(string),<br/>      enable_collaborative_inbox : optional(bool),<br/>      include_custom_footer : optional(bool),<br/>      include_in_global_address_list : optional(bool),<br/>      is_archived : optional(bool),<br/>      members_can_post_as_the_group : optional(bool),<br/>      message_moderation_level : optional(string),<br/>      primary_language : optional(string),<br/>      reply_to : optional(string),<br/>      send_message_deny_notification : optional(bool),<br/>      spam_moderation_level : optional(string),<br/>      who_can_assist_content : optional(string),<br/>      who_can_contact_owner : optional(string),<br/>      who_can_discover_group : optional(string),<br/>      who_can_join : optional(string),<br/>      who_can_leave_group : optional(string),<br/>      who_can_moderate_content : optional(string),<br/>      who_can_moderate_members : optional(string),<br/>      who_can_post_message : optional(string),<br/>      who_can_view_group : optional(string),<br/>      who_can_view_membership : optional(string),<br/>    }), {}),<br/>  }))</pre> | `{}` | no |
 | <a name="input_id_length_limit"></a> [id\_length\_limit](#input\_id\_length\_limit) | Limit `id` to this many characters (minimum 6).<br/>Set to `0` for unlimited length.<br/>Set to `null` for keep the existing setting, which defaults to `0`.<br/>Does not affect `id_full`. | `number` | `null` | no |
 | <a name="input_label_key_case"></a> [label\_key\_case](#input\_label\_key\_case) | Controls the letter case of the `tags` keys (label names) for tags generated by this module.<br/>Does not affect keys of tags passed in via the `tags` input.<br/>Possible values: `lower`, `title`, `upper`.<br/>Default value: `title`. | `string` | `null` | no |
 | <a name="input_label_order"></a> [label\_order](#input\_label\_order) | The order in which the labels (ID elements) appear in the `id`.<br/>Defaults to ["namespace", "environment", "stage", "name", "attributes"].<br/>You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present. | `list(string)` | `null` | no |
 | <a name="input_label_value_case"></a> [label\_value\_case](#input\_label\_value\_case) | Controls the letter case of ID elements (labels) as included in `id`,<br/>set as tag values, and output by this module individually.<br/>Does not affect values of tags passed in via the `tags` input.<br/>Possible values: `lower`, `title`, `upper` and `none` (no transformation).<br/>Set this to `title` and set `delimiter` to `""` to yield Pascal Case IDs.<br/>Default value: `lower`. | `string` | `null` | no |
 | <a name="input_labels_as_tags"></a> [labels\_as\_tags](#input\_labels\_as\_tags) | Set of labels (ID elements) to include as tags in the `tags` output.<br/>Default is to include all labels.<br/>Tags with empty values will not be included in the `tags` output.<br/>Set to `[]` to suppress all generated tags.<br/>**Notes:**<br/>  The value of the `name` tag, if included, will be the `id`, not the `name`.<br/>  Unlike other `null-label` inputs, the initial setting of `labels_as_tags` cannot be<br/>  changed in later chained modules. Attempts to change it will be silently ignored. | `set(string)` | <pre>[<br/>  "default"<br/>]</pre> | no |
-| <a name="input_length"></a> [length](#input\_length) | The length of the random name | `number` | `2` | no |
 | <a name="input_name"></a> [name](#input\_name) | ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.<br/>This is the only ID element not also included as a `tag`.<br/>The "name" tag is set to the full `id` string. There is no tag with the value of the `name` input. | `string` | `null` | no |
 | <a name="input_namespace"></a> [namespace](#input\_namespace) | ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique | `string` | `null` | no |
 | <a name="input_regex_replace_chars"></a> [regex\_replace\_chars](#input\_regex\_replace\_chars) | Terraform regular expression (regex) string.<br/>Characters matching the regex will be removed from the ID elements.<br/>If not set, `"/[^a-zA-Z0-9-]/"` is used to remove all characters other than hyphens, letters and digits. | `string` | `null` | no |
 | <a name="input_stage"></a> [stage](#input\_stage) | ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release' | `string` | `null` | no |
 | <a name="input_tags"></a> [tags](#input\_tags) | Additional tags (e.g. `{'BusinessUnit': 'XYZ'}`).<br/>Neither the tag keys nor the tag values will be modified by this module. | `map(string)` | `{}` | no |
 | <a name="input_tenant"></a> [tenant](#input\_tenant) | ID element \_(Rarely used, not included by default)\_. A customer identifier, indicating who this instance of a resource is for | `string` | `null` | no |
+| <a name="input_users"></a> [users](#input\_users) | List of users | <pre>map(object({<br/>    # addresses<br/>    aliases : optional(list(string), []),<br/>    archived : optional(bool, false),<br/>    change_password_at_next_login : optional(bool),<br/>    # custom_schemas<br/>    # emails<br/>    # external_ids<br/>    family_name : string,<br/>    given_name : string,<br/>    groups : optional(map(object({<br/>      role : optional(string, "MEMBER"),<br/>      delivery_settings : optional(string, "ALL_MAIL"),<br/>      type : optional(string, "USER"),<br/>    })), {}),<br/>    # ims<br/>    include_in_global_address_list : optional(bool),<br/>    ip_allowlist : optional(bool),<br/>    is_admin : optional(bool),<br/>    # keywords<br/>    # languages<br/>    # locations<br/>    org_unit_path : optional(string),<br/>    # organizations<br/>    # phones<br/>    # posix_accounts<br/>    primary_email : string,<br/>    recovery_email : optional(string),<br/>    recovery_phone : optional(string),<br/>    # relations<br/>    # ssh_public_keys<br/>    suspended : optional(bool),<br/>    # timeouts<br/>    # websites<br/><br/>    # User attributes with unique constraints<br/><br/>    # password and hash_function<br/>    # If a hashFunction is specified, the password must be a valid hash key.<br/>    # If it's not specified, the password should be in clear text and between<br/>    # 8–100 ASCII characters.<br/>    # https://developers.google.com/workspace/admin/directory/v1/guides/manage-users<br/>    hash_function : optional(string),<br/>    password : optional(string),<br/>  }))</pre> | `{}` | no |
 
 ## Outputs
 
-| Name | Description |
-|------|-------------|
-| <a name="output_random_pet_name"></a> [random\_pet\_name](#output\_random\_pet\_name) | The generated random pet name |
+No outputs.
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 <!-- markdownlint-enable MD013 -->
 <!-- prettier-ignore-end -->
@@ -138,11 +198,8 @@ Copyright © 2016-2025 [Masterpoint Consulting LLC](https://masterpoint.io/)
 [newsletter-url]: https://newsletter.masterpoint.io/
 [youtube-badge]: https://img.shields.io/badge/YouTube-Subscribe-D191BF?style=for-the-badge&logo=youtube&logoColor=white
 [youtube-url]: https://www.youtube.com/channel/UCeeDaO2NREVlPy9Plqx-9JQ
-
-<!-- TODO: Replace `terraform-module-template` with your actual repository name. -->
-
-[release-badge]: https://img.shields.io/github/v/release/masterpointio/terraform-module-template?color=0E383A&label=Release&style=for-the-badge&logo=github&logoColor=white
-[latest-release]: https://github.com/masterpointio/terraform-module-template/releases/latest
-[contributors-image]: https://contrib.rocks/image?repo=masterpointio/terraform-module-template
-[contributors-url]: https://github.com/masterpointio/terraform-module-template/graphs/contributors
-[issues-url]: https://github.com/masterpointio/terraform-module-template/issues
+[release-badge]: https://img.shields.io/github/v/release/masterpointio/terraform-googleworkspace-users-groups-automation?color=0E383A&label=Release&style=for-the-badge&logo=github&logoColor=white
+[latest-release]: https://github.com/masterpointio/terraform-googleworkspace-users-groups-automation/releases/latest
+[contributors-image]: https://contrib.rocks/image?repo=masterpointio/terraform-googleworkspace-users-groups-automation
+[contributors-url]: https://github.com/masterpointio/terraform-googleworkspace-users-groups-automation/graphs/contributors
+[issues-url]: https://github.com/masterpointio/terraform-googleworkspace-users-groups-automation/issues

examples/complete/main.tf

@@ -1 +1,58 @@
-# complete.tf
+locals {
+  default_group_settings = {
+    allow_external_members                         = false
+    allow_web_posting                              = true
+    archive_only                                   = false
+    custom_roles_enabled_for_settings_to_be_merged = false
+    enable_collaborative_inbox                     = false
+    is_archived                                    = false
+    primary_language                               = "en_US"
+    who_can_join                                   = "ALL_IN_DOMAIN_CAN_JOIN"
+    who_can_assist_content                         = "OWNERS_AND_MANAGERS"
+    who_can_view_group                             = "ALL_IN_DOMAIN_CAN_VIEW"
+    who_can_view_membership                        = "ALL_IN_DOMAIN_CAN_VIEW"
+  }
+}
+
+
+module "googleworkspace" {
+  source = "../../"
+
+  users = {
+    "[email protected]" = {
+      primary_email = "[email protected]"
+      family_name   = "Last"
+      given_name    = "First"
+      password      = "insecure-password-for-example" # trunk-ignore(checkov/CKV_SECRET_6)
+      groups = {
+        "platform" = {
+          role = "MEMBER"
+        }
+      }
+    }
+  }
+
+  groups = {
+    "support" = {
+      name  = "Support"
+      email = "[email protected]"
+      settings = merge(local.default_group_settings, {
+        enable_collaborative_inbox = true,
+      })
+    },
+    "platform" = {
+      name     = "Platform"
+      email    = "[email protected]"
+      settings = merge(local.default_group_settings, {})
+    },
+    "engineers" = {
+      name  = "Engineering"
+      email = "[email protected]"
+      settings = merge(local.default_group_settings, {
+        who_can_join            = "INVITED_CAN_JOIN",
+        who_can_view_group      = "ALL_MEMBERS_CAN_VIEW",
+        who_can_view_membership = "ALL_MEMBERS_CAN_VIEW",
+      })
+    }
+  }
+}

examples/complete/outputs.tf

@@ -0,0 +1,17 @@
+provider "googleworkspace" {
+  # # use the 'my_customer' string, which is an alias that Google's API recognizes to reference your account's customerId.
+  # # Custom Schemas on the user object will fail if the customer_id is set to your actual customer_id.
+  # # For more details see: https://developers.google.com/workspace/admin/directory/reference/rest/v1/schemas/get
+  customer_id = "my_customer"
+
+  credentials             = "/Users/my_user/Downloads/my-google-project-credentials-1234567890.json"
+  impersonated_user_email = "my_impersonated_user_email@my_domain.com"
+
+  oauth_scopes = [
+    "https://www.googleapis.com/auth/admin.directory.group",
+    "https://www.googleapis.com/auth/admin.directory.user",
+    "https://www.googleapis.com/auth/admin.directory.userschema",
+    "https://www.googleapis.com/auth/apps.groups.settings",
+    "https://www.googleapis.com/auth/iam",
+  ]
+}

examples/complete/providers.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    googleworkspace = {
+      source  = "hashicorp/googleworkspace"
+      version = "0.7.0"
+    }
+  }
+}

examples/complete/variables.tf

@@ -0,0 +1,21 @@
+---
+_default_active_settings: &default_active_settings
+  allow_external_members: false
+  allow_web_posting: true
+  archive_only: false
+  custom_roles_enabled_for_settings_to_be_merged: false
+  enable_collaborative_inbox: false
+  is_archived: false
+  primary_language: en_US
+  who_can_join: ALL_IN_DOMAIN_CAN_JOIN
+  who_can_assist_content: OWNERS_AND_MANAGERS
+  who_can_view_group: ALL_IN_DOMAIN_CAN_VIEW
+  who_can_view_membership: ALL_IN_DOMAIN_CAN_VIEW
+
+team:
+  email: [email protected]
+  name: Engineering Team
+  description: Engineering Team that all technical employees are members of by default
+  is_admin: false
+  settings:
+    <<: *default_active_settings