write a doc on how-to service-linked-roles

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 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::<ACCOUNT_ID>: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