From d9d70ede776220c06a1d1286874380f33fc30839 Mon Sep 17 00:00:00 2001 From: Norbert Dopjera Date: Wed, 1 Nov 2023 17:43:08 +0100 Subject: [PATCH] docs(resources): iam_member documentation and examples (#63) --- docs/resources/iam_group.md | 9 ++- docs/resources/iam_member.md | 79 +++++++++++++++++++ .../montecarlo_iam_member/resource.tf | 18 +++++ 3 files changed, 102 insertions(+), 4 deletions(-) create mode 100644 docs/resources/iam_member.md create mode 100644 examples/resources/montecarlo_iam_member/resource.tf diff --git a/docs/resources/iam_group.md b/docs/resources/iam_group.md index b41cc75..7b56dc5 100644 --- a/docs/resources/iam_group.md +++ b/docs/resources/iam_group.md @@ -10,7 +10,7 @@ description: |- Represents a named resource which lets you define _Monte Carlo_ **authorization group** responsible for assigning roles to the users. An authorization group policy is made up of three primary parts: - a list of permissions -- a list of group members (not set by this resource) +- a list of group members (not set by this resource, see [montecarlo_iam_member](iam_member.md)) - optionally, one or more Monte Carlo domains to restrict the group to The list of permissions/roles specifies **what can be done** (such as access or edit monitors), and the domain restrictions specify what parts of your data/metadata those users **may access under given permissions**. @@ -63,24 +63,25 @@ Allowed roles: - `sso_group` (String, _default:_ `null`) Automatically assignes all of the users from the provided **SSO group** to the authorization group. - - if set, users cannot be assigned to the authorization group directly + - if set, users cannot be assigned to the authorization group directly (see [montecarlo_iam_member](iam_member.md)) - if set, when authorization group already exists, all of the previous user assignments will be destroyed. ### Read-Only -- `label` (String) Authorization group **label/name** as it should be presented in the _Monte Carlo_ UI. Implementation of this resource will always set this attribute to the same value as the `name` attribute ([see above](#attr--name)) to avoid confusion. +- `label` (String) Authorization group **label/name** as it should be presented in the _Monte Carlo_ UI. Implementation of this resource will always set this attribute to the same value as the `name` attribute ([see above](#attr--name)) to avoid confusion and to make integrations of resource [montecarlo_iam_member](iam_member.md) easier. ## Import +Only non-managed (custom) groups can be imported. This resource can be imported using the import ID with following format: * `{{group_name}}` -In **Terraform v1.5.0** and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import a _Transactional Warehouse_ using one of the formats above. For example: +In **Terraform v1.5.0** and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import a _Authorization Group_ using one of the formats above. For example: ```terraform import { diff --git a/docs/resources/iam_member.md b/docs/resources/iam_member.md new file mode 100644 index 0000000..5ba526f --- /dev/null +++ b/docs/resources/iam_member.md @@ -0,0 +1,79 @@ +--- +page_title: "montecarlo_iam_member Resource - terraform-provider-montecarlo" +subcategory: "" +description: |- + A named resource which lets you assign users to the Monte Carlo authorization group. +--- + +# montecarlo_iam_member (Resource) + +Represents a named resource which lets you assign user to the _Monte Carlo_ **authorization group** (see [montecarlo_iam_group](iam_group.md)). This assignment is allowed only if the **authorization group** is not configured for SSO. Configured member (user) will be asigned to the configured group, selected by the group name. This group name is effectively group ID as well (see [montecarlo_iam_group](iam_group.md)) and is not shown in the _Monte Carlo_ UI by default. + +`montecarlo_iam_group` resource sets the group name (ID) to the same value as its label, so the value displayed in the _Monte Carlo_ UI, for groups terraformed by that resource, is also a group name (ID). Alternatively, if you are using `montecarlo_iam_group` resource, you can reference group name (ID) directly in the _Terraform_ code. + +To get more information about _Monte Carlo_ **authorization groups** member assignments, see: +- [API documentation](https://apidocs.getmontecarlo.com/#definition-UpdateUserAuthorizationGroupMembership) +- How-to Guides + - [Authorization](https://docs.getmontecarlo.com/docs/authorization) + + + +## Example Usage + +```terraform +resource "montecarlo_iam_member" "example_builtin" { + group = "groups/editors-all" + member = "user:user@google.com" +} + +resource "montecarlo_iam_member" "example_custom" { + group = "groups/custom-group" + member = "user:user@google.com" +} + +resource "montecarlo_iam_member" "example_multiple" { + group = "groups/custom-group" + member = each.value + for_each = toset([ + "user:user1@google.com", + "user:user2@google.com" + ]) +} +``` + + + + +## Schema + +### Required + +- `group` (String) ID (name) of the **authorization group** to which the member (user) will be assigned. Current implementation requires the value to follow this format `groups/`. _Monte Carlo_ UI currently does not expose name of the groups, therefore it might be complicated to obtain this value for existing groups. For this purpose, resource [montecarlo_iam_group](iam_group.md) sets name of the group and its label to the same values. + + - builtin groups are supported (e.g. `groups/editors-all`) + - custom groups are supported (e.g. `groups/custom-group`) + +- `member` (String) This attribute represents the user that will be assigned to the specified Monte Carlo **authorization group**. Current implementation requires the value to follow this format `user:email@google.com`. If user with this **email** is not found in the _Monte Carlo_, the resource operations will fail. + + + +## Import + +This resource can be imported using the import ID with following format: + +* `{{groups/,user:}}` + +In **Terraform v1.5.0** and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import a _Member assignment_ using one of the formats above. For example: + +```terraform +import { + id = "{{groups/,user:}}" + to = montecarlo_iam_member.default +} +``` + +When using the [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import), _Member assignment_ can be imported using one of the formats above. For example: + +``` +$ terraform import montecarlo_iam_member.default {{groups/,user:}} +``` diff --git a/examples/resources/montecarlo_iam_member/resource.tf b/examples/resources/montecarlo_iam_member/resource.tf new file mode 100644 index 0000000..7922148 --- /dev/null +++ b/examples/resources/montecarlo_iam_member/resource.tf @@ -0,0 +1,18 @@ +resource "montecarlo_iam_member" "example_builtin" { + group = "groups/editors-all" + member = "user:user@google.com" +} + +resource "montecarlo_iam_member" "example_custom" { + group = "groups/custom-group" + member = "user:user@google.com" +} + +resource "montecarlo_iam_member" "example_multiple" { + group = "groups/custom-group" + member = each.value + for_each = toset([ + "user:user1@google.com", + "user:user2@google.com" + ]) +}