New: added readme.md to example and update existing readme.md [INPRO-399

]
strg-at · May 11, 2021 · 0bdb56d · 0bdb56d
1 parent c7011ea
commit 0bdb56d
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 95 deletions.
diff --git a/README.md b/README.md
@@ -1,110 +1,29 @@
 # Dynamic User- and Group Management for Google Workspace with Terraform
-ISAS Implementation for User- and Group Management in Google Workspace (formerly GSuite).
-## Prerequisites
-### Local
-* Terraform installed
+ISAS Implementation for User- and Group Management in Google Workspace (formerly GSuite)
 
-### Google Cloud
-#### **Setup Service Account**
-[Google SDK Documentation about Delegation](https://developers.google.com/admin-sdk/directory/v1/guides/delegation)
 
-Go to [IAM service accounts](https://console.developers.google.com/iam-admin/serviceaccounts) and create a Service account.
-* enter Service account name
-* add yourself to 'Grant users access to this service account'
+## How to use this module
 
-#### **Add key**
-In the Service account overview open the 'Actions' menu on the right of the dedicated service account and choose **Manage keys**.
-Click on 'Add key' and create a new key in JSON format, this key will be used for Terraform.
+This repo has the following folder structure:
+* [modules](modules/): This folder contains a set of modules for maintaining Users and Groups in Google Workspace. The modules are basically standalone, however a proper data source is needed.
+* [examples](examples/): This folder shows examples on how to use this module with different data sources as well as an example for a data source and authentication with the Google API.
 
-#### **Add domain-wide delegation for GSuite**
-In the Service account overview open the 'Actions' menu on the right of the dedicated service account and choose **Manage details**.
+### Google Cloud Service account
 
-Open this part below and **Enable GSuite Domain-wide Delegation**.
-* Enter Product name, f.e. Terraform GSuite service
-* the impersonated user account will do the terraform job and needs admin permission.
-* copy ID for next step
+To maintain the Google Workspace ressources a Service account is needed. See [example-gsuite-authentication](examples/example-gsuite-authentication) on how to provide credentials to Terraform.
 
-#### **Grant Google Workspace admin permissions**
-Now go to [Google Admin Console](https://admin.google.com) and open the Burger menu on the left. Choose **Security** > **API controls**.
+## How do I contribute to this module?
 
-Get the Service account with the ID provided before (Service account details), then add the following oauth scopes:
-```
-https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.userschema, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/apps.groups.settings
-```
+Contributions are very welcome! Please create a Pull Request.
 
-## Usage
-### Provide Service account credentials to Terraform
-```terraform
-provider "gsuite" {
-  impersonated_user_email = "[email protected]"
-  credentials             = "/path/to/google_credentials.json"
-  oauth_scopes = [
-    "https://www.googleapis.com/auth/admin.directory.group",
-    "https://www.googleapis.com/auth/apps.groups.settings",
-    "https://www.googleapis.com/auth/admin.directory.user",
-    "https://www.googleapis.com/auth/admin.directory.userschema",
-  ]
-}
-```
-It is also possible to use a *.tfvars file to define variables for the credentials and exclude this file in .gitignore.
+## How is this module versioned?
 
-### Data source examples
-#### **Groups example structure**
-```yaml
-role:
-  email: '[email protected]'
-  name: 'Example Role'
-```
+This module uses [Semantic Versioning](http://semver.org/).
 
-##### Groups in Group example structure
-Group member have to be defined within the group definition.
-```yaml
-role:
-  email: '[email protected]'
-  name: 'Example Role'
-  groups:
-    - alt_role
-```
-In this example the group 'alt_role' will be a member of the group 'role'.
+## Licence
 
-
-#### **Users example structure**
-```yaml
-jane:
-  family_name: 'Doe'
-  given_name: 'Jane'
-  primary_email: '[email protected]'
-  recovery_email: '[email protected]'
-  recovery_phone: '+10000'
-  org_unit_path: /
-  is_suspended: false
-  suspension_reason: ''
-  roles: 
-    - role
-```
-
-### How to use this module
-This is an example usage with local yaml files (see [Terraform yamldecode](https://www.terraform.io/docs/language/functions/yamldecode.html) for details). It is also possible to use any other sources like Github, which are defined by Terraform (see [Terraform module sources](https://www.terraform.io/docs/language/modules/sources.html) for details).
-
-```terraform
-locals {
-  groups = yamldecode(file("${path.module}/groups.yaml"))
-  users  = yamldecode(file("${path.module}/users.yaml"))
-}
-
-module "gworkspace" {
-  source   = "https://github.com/strg-at/terraform-google-workspace-module.git"
-  providers = {
-    gsuite = gsuite
-  }
-  groups = local.groups
-  users = local.users
-}
-```
-
-## How to use Terraform
-See [Terraform docs](https://www.terraform.io/docs/cli/run/index.html) for details.
+This code is released under the MIT Licence. Please see [LICENCE](LICENCE) for more details.
 
 ## Authors
 
-* **[Jasmin Müller](mailto:[email protected])** (:octocat: [jazzlyn](https://github.com/jazzlyn)) - first implementation
+* **[Jasmin Müller](mailto:[email protected])** (:octocat: [jazzlyn](https://github.com/jazzlyn)) - implementation
diff --git a/examples/example-gsuite-authentication/README.md b/examples/example-gsuite-authentication/README.md
@@ -0,0 +1,31 @@
+### Google Cloud Service account
+#### **Setup Service Account**
+[Google SDK Documentation about Delegation](https://developers.google.com/admin-sdk/directory/v1/guides/delegation)
+
+Go to [IAM service accounts](https://console.developers.google.com/iam-admin/serviceaccounts) and create a Service account.
+* enter Service account name
+* add yourself to 'Grant users access to this service account'
+
+#### **Add key**
+In the Service account overview open the 'Actions' menu on the right of the dedicated service account and choose **Manage keys**.
+Click on 'Add key' and create a new key in JSON format, this key will be used for Terraform.
+
+#### **Add domain-wide delegation for GSuite**
+In the Service account overview open the 'Actions' menu on the right of the dedicated service account and choose **Manage details**.
+
+Open this part below and **Enable GSuite Domain-wide Delegation**.
+* Enter Product name, f.e. Terraform GSuite service
+* the impersonated user account will do the terraform job and needs admin permission.
+* copy ID for next step
+
+#### **Grant Google Workspace admin permissions**
+Now go to [Google Admin Console](https://admin.google.com) and open the Burger menu on the left. Choose **Security** > **API controls**.
+
+Get the Service account with the ID provided before (Service account details), then add the following oauth scopes:
+```
+https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.userschema, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/apps.groups.settings
+```
+
+#### Provide Service account credentials to Terraform
+
+Add credentials to terraform.tfvars, see [terraform.tfvars.example](terraform.tfvars.example).
diff --git a/...les/example-with-local-yaml-files/main.tf → examples/example-with-local-files/main.tf b/...les/example-with-local-yaml-files/main.tf → examples/example-with-local-files/main.tf