Merge pull request #6 from speee/add-example

Add docs and example

README.md

@@ -2,6 +2,70 @@
 
 Terraform module which creates AWS SSO assignments on AWS.
 
+## Usage
+```hcl
+module "account_assignments" {
+  source = "speee/sso_assignments/aws"
+
+  instance_arn      = "arn:aws:sso:::instance/ssoins-9999999999999999"
+  identity_store_id = "d-9999999999"
+
+  organization_accounts = [
+    {
+      arn = "arn:aws:organizations::123456789012:account/o-xxxxxxxxxx/123456789012"
+      email = "account1@example.com"
+      id = "123456789012"
+      name = "account1"
+    },
+    {
+      arn = "arn:aws:organizations::123456789012:account/o-xxxxxxxxxx/234567890123"
+      email = "account2@example.com"
+      id = "234567890123"
+      name = "account2"
+    },
+  ]
+
+  assignments = {
+    "account1" = {
+      "groups" = {
+        "SystemAdministrator" = [
+          "AdministratorAccess",
+        ],
+        "Engineer" = [
+          "PowerUserAccess",
+        ],
+        "Manager" = [
+          "ReadOnlyAccess",
+        ],
+      },
+      "users" = {
+        "alice@example.com" = [
+          "AdministratorAccess",
+        ],
+      },
+    },
+    "account2" = {
+      "users" = {
+        "alice@example.com" = [
+          "AdministratorAccess",
+        ],
+        "bob@example.com" = [
+          "ReadOnlyAccess",
+        ],
+      },
+    },
+  }
+}
+```
+
+## Examples
+- [All account assignments in a single module](https://github.com/speee/terraform-aws-sso-assignment/tree/master/examples/all-in-one)
+- [Account assignments per organization units](https://github.com/speee/terraform-aws-sso-assignment/tree/master/examples/module-per-organizations-unit)
+
+## Notes
+1. This module does not create no resource other than `aws_ssoadmin_account_assignment` resource. Use resources or data sources directly to manage other resources like `aws_ssoadmin_permission_set`.
+
+
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements
 
@@ -14,7 +78,7 @@ Terraform module which creates AWS SSO assignments on AWS.
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | 3.52.0 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 3.24.0 |
 
 ## Modules
 

examples/all-in-one/README.md

@@ -0,0 +1,52 @@
+# All account assignments in a single module
+
+Define all account assignments in a single module.
+
+## Usage
+
+To run this example you need to execute:
+
+```bash
+$ terraform init
+$ terraform plan
+$ terraform apply
+```
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 0.13.7 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >=3.24.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 3.24.0 |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_all_assignments"></a> [all\_assignments](#module\_all\_assignments) | ../.. | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_organizations_organization.organization](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/organizations_organization) | data source |
+| [aws_ssoadmin_instances.instances](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssoadmin_instances) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_assignments_all"></a> [assignments\_all](#input\_assignments\_all) | All of account assignments. | `map(map(map(list(string))))` | n/a | yes |
+| <a name="input_sso_region"></a> [sso\_region](#input\_sso\_region) | Region of your AWS SSO instance. | `string` | n/a | yes |
+
+## Outputs
+
+No outputs.
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/all-in-one/backend.tf

@@ -0,0 +1,5 @@
+terraform {
+  backend "local" {
+    path = "terraform.tfstate"
+  }
+}

examples/all-in-one/main.tf

@@ -0,0 +1,20 @@
+data "aws_ssoadmin_instances" "instances" {}
+
+data "aws_organizations_organization" "organization" {}
+
+locals {
+  instance_arn      = tolist(data.aws_ssoadmin_instances.instances.arns)[0]
+  identity_store_id = tolist(data.aws_ssoadmin_instances.instances.identity_store_ids)[0]
+  accounts          = data.aws_organizations_organization.organization.accounts
+}
+
+module "all_assignments" {
+  source = "../.."
+
+  instance_arn      = local.instance_arn
+  identity_store_id = local.identity_store_id
+
+  organization_accounts = local.accounts
+
+  assignments = var.assignments_all
+}

examples/all-in-one/providers.tf

@@ -0,0 +1,3 @@
+provider "aws" {
+  region = var.sso_region
+}

examples/all-in-one/terraform.tfvars

@@ -0,0 +1,41 @@
+assignments_all = {
+  "account1" = {
+    "groups" = {
+      "SystemAdministrator" = [
+        "AdministratorAccess",
+      ],
+      "Engineer" = [
+        "PowerUserAccess",
+      ],
+      "Manager" = [
+        "ReadOnlyAccess",
+      ],
+    },
+    "users" = {
+      "alice@example.com" = [
+        "AdministratorAccess",
+      ],
+    },
+  },
+  "account2" = {
+    "groups" = {
+      "SystemAdministrator" = [
+        "AdministratorAccess",
+      ],
+      "Engineer" = [
+        "PowerUserAccess",
+      ],
+      "Manager" = [
+        "ReadOnlyAccess",
+      ],
+    },
+    "users" = {
+      "alice@example.com" = [
+        "AdministratorAccess",
+      ],
+      "bob@example.com" = [
+        "ReadOnlyAccess",
+      ],
+    },
+  },
+}

examples/all-in-one/variables.tf

@@ -0,0 +1,9 @@
+variable "sso_region" {
+  type        = string
+  description = "Region of your AWS SSO instance."
+}
+
+variable "assignments_all" {
+  type        = map(map(map(list(string))))
+  description = "All of account assignments."
+}

examples/all-in-one/version.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 0.13.7"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">=3.24.0"
+    }
+  }
+}

examples/module-per-organizations-unit/README.md

@@ -0,0 +1,54 @@
+# Account assignment per organization units
+
+Define account assignments per organization units.
+
+## Usage
+
+To run this example you need to execute:
+
+```bash
+$ terraform init
+$ terraform plan
+$ terraform apply
+```
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 0.13.7 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >=3.24.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 3.24.0 |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_ou1_assignments"></a> [ou1\_assignments](#module\_ou1\_assignments) | ../.. | n/a |
+| <a name="module_ou2_assignments"></a> [ou2\_assignments](#module\_ou2\_assignments) | ../.. | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_organizations_organization.organization](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/organizations_organization) | data source |
+| [aws_ssoadmin_instances.instances](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssoadmin_instances) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_assignments_ou1"></a> [assignments\_ou1](#input\_assignments\_ou1) | Account assignments for Organization Unit 1. | `map(map(map(list(string))))` | n/a | yes |
+| <a name="input_assignments_ou2"></a> [assignments\_ou2](#input\_assignments\_ou2) | Account assignments for Organization Unit 2. | `map(map(map(list(string))))` | n/a | yes |
+| <a name="input_sso_region"></a> [sso\_region](#input\_sso\_region) | Region of your AWS SSO instance. | `string` | n/a | yes |
+
+## Outputs
+
+No outputs.
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/module-per-organizations-unit/backend.tf

@@ -0,0 +1,5 @@
+terraform {
+  backend "local" {
+    path = "terraform.tfstate"
+  }
+}

examples/module-per-organizations-unit/main.tf

@@ -0,0 +1,31 @@
+data "aws_ssoadmin_instances" "instances" {}
+
+data "aws_organizations_organization" "organization" {}
+
+locals {
+  instance_arn      = tolist(data.aws_ssoadmin_instances.instances.arns)[0]
+  identity_store_id = tolist(data.aws_ssoadmin_instances.instances.identity_store_ids)[0]
+  accounts          = data.aws_organizations_organization.organization.accounts
+}
+
+module "ou1_assignments" {
+  source = "../.."
+
+  instance_arn      = local.instance_arn
+  identity_store_id = local.identity_store_id
+
+  organization_accounts = local.accounts
+
+  assignments = var.assignments_ou1
+}
+
+module "ou2_assignments" {
+  source = "../.."
+
+  instance_arn      = local.instance_arn
+  identity_store_id = local.identity_store_id
+
+  organization_accounts = local.accounts
+
+  assignments = var.assignments_ou2
+}

examples/module-per-organizations-unit/ou1.auto.tfvars

@@ -0,0 +1,41 @@
+assignments_ou1 = {
+  "account1" = {
+    "groups" = {
+      "SystemAdministrator" = [
+        "AdministratorAccess",
+      ],
+      "Engineer" = [
+        "PowerUserAccess",
+      ],
+      "Manager" = [
+        "ReadOnlyAccess",
+      ],
+    },
+    "users" = {
+      "alice@example.com" = [
+        "AdministratorAccess",
+      ],
+    },
+  },
+  "account2" = {
+    "groups" = {
+      "SystemAdministrator" = [
+        "AdministratorAccess",
+      ],
+      "Engineer" = [
+        "PowerUserAccess",
+      ],
+      "Manager" = [
+        "ReadOnlyAccess",
+      ],
+    },
+    "users" = {
+      "alice@example.com" = [
+        "AdministratorAccess",
+      ],
+      "bob@example.com" = [
+        "ReadOnlyAccess",
+      ],
+    },
+  },
+}

examples/module-per-organizations-unit/ou2.auto.tfvars

@@ -0,0 +1,35 @@
+assignments_ou2 = {
+  "account3" = {
+    "groups" = {
+      "SystemAdministrator" = [
+        "AdministratorAccess",
+      ],
+      "Manager" = [
+        "ReadOnlyAccess",
+      ],
+    },
+    "users" = {
+      "alice@example.com" = [
+        "AdministratorAccess",
+      ],
+    },
+  },
+  "account4" = {
+    "groups" = {
+      "SystemAdministrator" = [
+        "AdministratorAccess",
+      ],
+    },
+    "users" = {
+      "alice@example.com" = [
+        "AdministratorAccess",
+      ],
+      "bob@example.com" = [
+        "ReadOnlyAccess",
+      ],
+      "carol@example.com" = [
+        "ReadOnlyAccess",
+      ],
+    },
+  },
+}