diff --git a/docs/how-to/aws-service-linked-roles/README.md b/docs/how-to/aws-service-linked-roles/README.md index 1eb1a47d..3909126e 100644 --- a/docs/how-to/aws-service-linked-roles/README.md +++ b/docs/how-to/aws-service-linked-roles/README.md @@ -1,6 +1,69 @@ -# AWS Service Linked Roles Setup in common/ +# AWS Service Linked Roles + +AWS Service Linked Roles (SLRs) are IAM roles that are linked to specific AWS services and grant them permissions to act on your behalf. + +## Policy + +Users are **not** granted IAM permissions to create service-linked roles directly. All service-linked roles must be managed through Terraform. + +## New Accounts + +For accounts provisioned through the standard account setup process, the following files are included in `common/` automatically: + +| File | Purpose | +|------|---------| +| `service-linked-roles.tf` | Terraform resource definitions for SLRs | +| `variables.service-linked-roles.tf` | Variable declaration for the SLR list | +| `variables.service-linked-roles.auto.tfvars` | List of AWS service names to create SLRs for | + +To add a new service-linked role to a new account, add the AWS service name to the `service_linked_roles` list in `variables.service-linked-roles.auto.tfvars` and follow the standard [git workflow](../../how-to/submit-pull-request/). + +## Existing Accounts (no SLR setup yet) + +### 1. Copy the Terraform files + +Copy the three files from the [reference location](https://github.e.it.census.gov/terraform/support/tree/master/local-app/aws-account-setup/ansible/roles/inf-common/files) in the support repo into the account's `common/` directory: + +``` +support/local-app/aws-account-setup/ansible/roles/inf-common/files/service-linked-roles.tf +support/local-app/aws-account-setup/ansible/roles/inf-common/files/variables.service-linked-roles.tf +support/local-app/aws-account-setup/ansible/roles/inf-common/files/variables.service-linked-roles.auto.tfvars +``` + +### 2. Identify already-existing service-linked roles + +Check the account for SLRs that AWS may have created automatically (e.g., when a service was first used). You can list them in the AWS console under **IAM → Roles**, filtering by type *Service-linked role*, or via the CLI: + +```bash +aws iam list-roles --path-prefix /aws-service-role/ \ + --query 'Roles[*].[RoleName,AssumedRolePolicyDocument.Statement[0].Principal.Service]' \ + --output table +``` + +### 3. Import existing roles into Terraform state + +For each SLR that already exists, add its service name to `variables.service-linked-roles.auto.tfvars` and then import it so Terraform does not attempt to re-create it. + +```bash +# Example — adjust the service name and ARN to match +terraform import \ + 'aws_iam_service_linked_role.roles["autoscaling.amazonaws.com"]' \ + arn:aws-us-gov:iam:::role/aws-service-role/autoscaling.amazonaws.com/AWSServiceRoleForAutoScaling +``` + +Repeat for every SLR that is already present in the account. + +### 4. Add any additional roles needed + +Add any further service names required for the account to `variables.service-linked-roles.auto.tfvars`. They will be created on the next `tf-apply`. + +### 5. Follow the git workflow + +Run `tf-plan` to confirm only the expected changes (imports show no-op; new entries show as additions), then commit, push, and open a pull request per the standard [git workflow](../../how-to/submit-pull-request/). + +--- # CHANGELOG -* 1.0.0 -- YYYY-MM-DD +* 1.0.0 -- 2026-04-14 - initial