Preserve custom roles when vendoring in updates (#697)

Author: Nuru

modules/aws-team-roles/README.md

@@ -3,7 +3,57 @@
 This component is responsible for provisioning user and system IAM roles outside the `identity` account.
 It sets them up to be assumed from the "team" roles defined in the `identity` account by
 [the `aws-teams` component](../aws-teams) and/or the AWS SSO permission sets
-defined in [the `aws-sso` component](../aws-sso).
+defined in [the `aws-sso` component](../aws-sso), and/or be directly accessible via SAML logins.
+
+
+### Privileges are Granted to Users via IAM Policies
+
+Each role is granted permissions by attaching a list of IAM policies to the IAM role
+via its `role_policy_arns` list. You can configure AWS managed policies by entering the ARNs of the policies
+directly into the list, or you can create a custom policy as follows:
+
+1. Give the policy a name, e.g. `eks-admin`. We will use `NAME` as a placeholder for the name in the instructions below.
+2. Create a file in the `aws-teams` directory with the name `policy-NAME.tf`.
+3. In that file, create a policy as follows:
+
+    ```hcl
+    data "aws_iam_policy_document" "NAME" {
+      # Define the policy here
+    }
+
+    resource "aws_iam_policy" "NAME" {
+      name   = format("%s-NAME", module.this.id)
+      policy = data.aws_iam_policy_document.NAME.json
+
+      tags = module.this.tags
+    }
+    ```
+
+4. Create a file named `additional-policy-map_override.tf` in the `aws-team-roles` directory (if it does not already exist).
+   This is a [terraform override file](https://developer.hashicorp.com/terraform/language/files/override), meaning its
+   contents will be merged with the main terraform file, and any locals defined in it will override locals defined in other files.
+   Having your code in this separate override file makes it possible for the component to provide a placeholder local variable
+   so that it works without customization, while allowing you to customize the component and still update it without losing your customizations.
+5. In that file, redefine the local variable `overridable_additional_custom_policy_map` map as follows:
+
+    ```hcl
+    locals {
+      overridable_additional_custom_policy_map = {
+        NAME = aws_iam_policy.NAME.arn
+      }
+    }
+    ```
+
+    If you have multiple custom policies, add each one to the map in the form `NAME = aws_iam_policy.NAME.arn`.
+6. With that done, you can now attach that policy by adding the name to the `role_policy_arns` list. For example:
+
+    ```yaml
+    role_policy_arns:
+    - "arn:aws:iam::aws:policy/job-function/ViewOnlyAccess"
+    - "NAME"
+    ```
+
+
 
 ## Usage
 

modules/aws-team-roles/additional-policy-map.tf

@@ -0,0 +1,10 @@
+locals {
+  # If you have custom policies, override this declaration by creating
+  # a file called `additional-policy-map_override.tf`.
+  # Then add the custom policies to the additional_custom_policy_map in that file.
+  # See the README for more details.
+  overridable_additional_custom_policy_map = {
+    # Example:
+    #   eks_viewer = aws_iam_policy.eks_viewer.arn
+  }
+}

modules/aws-team-roles/main.tf

@@ -10,12 +10,13 @@ locals {
   # If you want to create custom policies to add to multiple roles by name, create the policy
   # using an aws_iam_policy resource and then map it to the name you want to use in the
   # YAML configuration by adding an entry in `custom_policy_map`.
-  custom_policy_map = {
+  supplied_custom_policy_map = {
     billing_read_only = try(aws_iam_policy.billing_read_only[0].arn, null)
     billing_admin     = try(aws_iam_policy.billing_admin[0].arn, null)
     support           = try(aws_iam_policy.support[0].arn, null)
     eks_viewer        = try(aws_iam_policy.eks_viewer[0].arn, null)
   }
+  custom_policy_map = merge(local.supplied_custom_policy_map, local.overridable_additional_custom_policy_map)
 
   configured_policies = flatten([for k, v in local.roles_config : v.role_policy_arns])
 

modules/aws-teams/README.md

@@ -1,15 +1,24 @@
 # Component: `aws-teams`
 
-This component is responsible for provisioning all primary user and system roles into the centralized identity account.
-This is expected to be use alongside [the `aws-team-roles` component](../aws-team-roles) to provide
-fine grained role delegation across the account hierarchy.
+## Purpose
+
+This component implements the hub of a hub-and-spoke account access hierarchy, where the hub is the `identity` account.
+This allows you to assign each user to a single "team" (implemented as an IAM role) in the `identity` account, which they access
+via a single authentication (login), which then allows them to access a set of roles in a set of accounts.
+
+This component is responsible for provisioning team roles in the centralized identity account.
+This is expected to be used alongside [the `aws-team-roles` component](../aws-team-roles)
+which provisions the roles in the spoke accounts and configures their privileges and which teams can access them.
 
 ### Teams Function Like Groups and are Implemented as Roles
 The "teams" created in the `identity` account by this module can be thought of as access control "groups":
 a user who is allowed access one of these teams gets access to a set of roles (and corresponding permissions)
 across a set of accounts. Generally, there is nothing else provisioned in the `identity` account,
 so the teams have limited access to resources in the `identity` account by design.
 
+Privileges for the users within the identity account itself are generally limited, and are configured
+via the `role_policy_arns` variable, just as with `aws-team-roles`. See the `aws-team-roles` README for more details.
+
 Teams are implemented as IAM Roles in each account. Access to the "teams" in the `identity`
 account is controlled by the `aws-saml` and `aws-sso` components. Access to the roles in all the
 other accounts is controlled by the "assume role" policies of those roles, which allow the "team"

modules/aws-teams/additional-policy-map.tf

@@ -0,0 +1,10 @@
+locals {
+  # If you have custom policies, override this declaration by creating
+  # a file called `additional-policy-map_override.tf`.
+  # Then add the custom policies to the additional_custom_policy_map in that file.
+  # See the README in `aws-team-roles` for more details.
+  overridable_additional_custom_policy_map = {
+    # Example:
+    #   eks_viewer = aws_iam_policy.eks_viewer.arn
+  }
+}

modules/aws-teams/main.tf

@@ -6,10 +6,11 @@ locals {
   # If you want to create custom policies to add to multiple roles by name, create the policy
   # using an aws_iam_policy resource and then map it to the name you want to use in the
   # YAML configuration by adding an entry in `custom_policy_map`.
-  custom_policy_map = {
+  supplied_custom_policy_map = {
     team_role_access = aws_iam_policy.team_role_access.arn
     support          = try(aws_iam_policy.support[0].arn, null)
   }
+  custom_policy_map = merge(local.supplied_custom_policy_map, local.overridable_additional_custom_policy_map)
 
   configured_policies = flatten([for k, v in local.roles_config : v.role_policy_arns])