> ## Documentation Index > Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # AWS IAM Role > AWS IAM role with configurable trust relationships, managed policies, inline policies, permission boundaries, and optional instance profiles. **Type:** `rvn-aws-iam-role` · **Latest version:** `0.2.1` ## Readme AWS IAM role with configurable trust relationships, managed policies, inline policies, permission boundaries, and optional instance profiles. ### Overview Use this module to create an IAM role for AWS services, cross-account access, OIDC workloads, SAML federation, or EC2 instance profiles. The module builds the trust policy from structured inputs by default, attaches managed policies, and can add inline policy documents or structured inline statements. IAM roles are security-sensitive resources. Start with the narrowest trust relationship and policy permissions that work, then expand only when a workload needs additional access. ### Use cases | Scenario | Benefit | | --------------------------------- | ---------------------------------------------------------------------------------------------------------- | | ECS task or Lambda execution role | Trust an AWS service principal and attach only the policies the workload needs. | | Cross-account access | Allow a specific AWS account or IAM principal to assume the role, optionally with MFA or other conditions. | | GitHub Actions or EKS OIDC access | Trust an OIDC provider and constrain access with token claims. | | EC2 instance role | Create an instance profile alongside the role for EC2 attachment. | ### Trust relationships Trusted AWS services accepts service principals such as ecs-tasks.amazonaws.com, lambda.amazonaws.com, or ec2.amazonaws.com. Trusted AWS principals accepts 12-digit AWS account IDs or IAM ARNs for cross-account and delegated access. Trusted OIDC providers accepts provider ARNs and condition blocks. Use conditions to restrict subjects, audiences, repositories, service accounts, or other identity claims. Without specific conditions, an OIDC trust relationship can be broader than intended. Trusted SAML providers accepts IAM SAML provider ARNs for federated access. Custom assume role policy JSON is an escape hatch. When set, it replaces the generated trust policy from the structured trust inputs. ### Permission policies Managed policy ARNs attaches existing AWS managed or customer managed policies to the role. Inline JSON policies accepts a map where each key is the inline policy name and each value is a JSON IAM policy document. Inline policy statements builds one inline policy from structured statement entries. Each statement includes an effect, actions, resources, and optional conditions. Permission boundary ARN sets a maximum permissions boundary for the role. Use this when an organization requires roles to stay within a managed boundary policy. ### Instance profiles Enable Create instance profile when EC2 instances need to use this role. The instance profile name and path default to the role settings unless you provide specific values. ### Configuration | Setting | Required | Default | Notes | | -------------------------------- | -------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | | AWS account | Yes | None | AWS account where the IAM role is created. | | Region | Yes | None | Runner region for the stack. IAM resources are global, but Terraform still runs with an AWS region. | | Role name | Yes | Project, environment, and module given IDs | IAM role name. Must be unique in the AWS account. | | Description | No | Managed by Terraform | Description stored on the IAM role. | | Path | No | / | IAM path for the role. | | Maximum session duration seconds | No | 3600 | STS session duration, from 3600 to 43200 seconds. | | Force detach policies on destroy | No | true | Detaches managed policies before destroying the role. | | Trusted AWS services | No | Empty list | AWS service principals allowed to assume the role. | | Trusted AWS principals | No | Empty list | AWS account IDs or IAM ARNs allowed to assume the role. | | Trusted OIDC providers | No | Empty list | OIDC providers and conditions for web identity trust. | | Trusted SAML providers | No | Empty list | SAML provider ARNs allowed to assume the role. | | Assume role conditions | No | Empty list | Conditions applied to all generated trust statements. | | Custom assume role policy JSON | No | None | Replaces generated trust policy when provided. | | Managed policy ARNs | No | Empty list | Existing managed policies to attach. | | Inline JSON policies | No | Empty map | Inline policy names mapped to JSON policy documents. | | Inline policy statements | No | Empty list | Structured statements combined into one inline policy. | | Permission boundary ARN | No | None | Managed policy ARN used as the permissions boundary. | | Create instance profile | No | false | Creates an IAM instance profile for EC2. | | Instance profile name | No | Role name | Visible when instance profile creation is enabled. | | Instance profile path | No | Role path | Visible when instance profile creation is enabled. | | Tags | No | Standard Ravion tags | Additional tags merged with Ravion ownership and identity tags. | | Terraform execution environment | No | None | Optional runner environment override. | | Advanced Terraform variables | No | Empty object | Escape hatch for one-off Terraform variable overrides. | ### Design decisions The module definition asks for an explicit role name instead of exposing name prefixes. Stable names make downstream references and audits easier to understand. Trust relationships are structured by default so common service, cross-account, OIDC, and SAML roles can be configured without hand-writing full IAM JSON. Custom assume role policy JSON remains available for uncommon trust policies. Ravion adds standard tags for ownership and traceability. User-provided Tags are merged on top for team, cost, or environment metadata. ### Learn more * [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) * [IAM JSON policy elements](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) * [IAM permissions boundaries](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) * [Source module](https://github.com/flightcontrolhq/modules/tree/rvn-aws-iam-role@0.2.1/security/iam) ## Inputs reference All inputs for `rvn-aws-iam-role` version `0.2.1`. Use the `name` shown for each field as the input key in module config. ### AWS account & region **AWS account.** * Immutable after creation **Region.** * Immutable after creation ### IAM role **Role name.** Name of the IAM role. AWS IAM role names must be unique in the account. * Default: `<>-<>-<>` * Immutable after creation * Pattern: `^[A-Za-z0-9+=,.@_-]{1,64}$` — Use 1-64 characters: letters, numbers, plus, equals, comma, period, at, underscore, or hyphen. **Description.** Description stored on the IAM role. **Path.** IAM path for the role. Most roles should use the root path. * Default: `/` * Immutable after creation * Pattern: `^/$|^/.*/$` — Start and end with a slash, for example / or /service-roles/. **Maximum session duration seconds.** Maximum STS session duration in seconds for this role. * Default: `3600` * Min: `3600` * Max: `43200` **Force detach policies on destroy.** Detach managed policies before destroying the role. * Default: `true` ### Trust relationships **Trusted AWS services.** AWS service principals that can assume this role. * Default: `[]` * Pattern: `.+\.(amazonaws\.com|amazonaws\.com\.cn)$` — Use an AWS service principal ending in .amazonaws.com or .amazonaws.com.cn. **Trusted AWS principals.** AWS account IDs or IAM ARNs that can assume this role. * Default: `[]` * Pattern: `^(\d{12}|arn:aws(-cn|-us-gov)?:iam::.+)$` — Use a 12-digit account ID or IAM ARN. **Trusted OIDC providers.** OIDC identity providers that can assume this role, with STS condition checks. * Default: `[]` **OIDC provider ARN.** IAM OIDC provider that issues tokens for this trust relationship. * Pattern: `^arn:aws(-cn|-us-gov)?:iam::\d{12}:oidc-provider/.+$` — Use a valid IAM OIDC provider ARN. **Conditions.** STS condition checks that restrict which OIDC identities can assume the role. * Default: `[]` **Condition operator.** IAM condition operator used to compare the condition key and values. Common operators are listed, and custom IAM operators such as ForAnyValue:StringLike can be entered manually. * Default: `StringEquals` * Allowed values: `StringEquals` (String equals), `StringNotEquals` (String not equals), `StringEqualsIgnoreCase` (String equals ignore case), `StringNotEqualsIgnoreCase` (String not equals ignore case), `StringLike` (String like), `StringNotLike` (String not like), `NumericEquals` (Numeric equals), `NumericNotEquals` (Numeric not equals), `NumericLessThan` (Numeric less than), `NumericLessThanEquals` (Numeric less than or equals), `NumericGreaterThan` (Numeric greater than), `NumericGreaterThanEquals` (Numeric greater than or equals), `DateEquals` (Date equals), `DateNotEquals` (Date not equals), `DateLessThan` (Date less than), `DateLessThanEquals` (Date less than or equals), `DateGreaterThan` (Date greater than), `DateGreaterThanEquals` (Date greater than or equals), `Bool` (Boolean), `BinaryEquals` (Binary equals), `IpAddress` (IP address), `NotIpAddress` (Not IP address), `ArnEquals` (ARN equals), `ArnNotEquals` (ARN not equals), `ArnLike` (ARN like), `ArnNotLike` (ARN not like), `Null` **Condition key.** IAM context key evaluated by the condition. **Condition values.** Allowed or matched values for the condition key. **Trusted SAML providers.** SAML provider ARNs that can assume this role. * Default: `[]` * Pattern: `^arn:aws(-cn|-us-gov)?:iam::\d{12}:saml-provider/.+$` — Use a valid IAM SAML provider ARN. **Shared trust conditions.** STS condition checks added to every generated trust policy statement. * Default: `[]` **Condition operator.** IAM condition operator used to compare the condition key and values. Common operators are listed, and custom IAM operators such as ForAnyValue:StringLike can be entered manually. * Default: `Bool` * Allowed values: `StringEquals` (String equals), `StringNotEquals` (String not equals), `StringEqualsIgnoreCase` (String equals ignore case), `StringNotEqualsIgnoreCase` (String not equals ignore case), `StringLike` (String like), `StringNotLike` (String not like), `NumericEquals` (Numeric equals), `NumericNotEquals` (Numeric not equals), `NumericLessThan` (Numeric less than), `NumericLessThanEquals` (Numeric less than or equals), `NumericGreaterThan` (Numeric greater than), `NumericGreaterThanEquals` (Numeric greater than or equals), `DateEquals` (Date equals), `DateNotEquals` (Date not equals), `DateLessThan` (Date less than), `DateLessThanEquals` (Date less than or equals), `DateGreaterThan` (Date greater than), `DateGreaterThanEquals` (Date greater than or equals), `Bool` (Boolean), `BinaryEquals` (Binary equals), `IpAddress` (IP address), `NotIpAddress` (Not IP address), `ArnEquals` (ARN equals), `ArnNotEquals` (ARN not equals), `ArnLike` (ARN like), `ArnNotLike` (ARN not like), `Null` **Condition key.** IAM context key evaluated by the condition. **Condition values.** Allowed or matched values for the condition key. **Custom assume role policy JSON.** Optional complete assume role policy JSON. When set, this overrides all trust relationship inputs above. ### Permission policies **Managed policy ARNs.** AWS managed or customer managed policy ARNs to attach to the role. * Default: `[]` * Pattern: `^arn:aws(-cn|-us-gov)?:iam::(aws|\d{12}):policy/.+$` — Use a valid IAM managed policy ARN. **Inline JSON policies.** Map of inline policy names to JSON policy documents. * Default: `{}` **Inline policy statements.** Structured IAM statements combined into one inline policy. * Default: `[]` **SID.** Optional IAM statement ID. **Effect.** Whether this statement allows or denies the listed actions. * Default: `Allow` * Allowed values: `Allow`, `Deny` **Actions.** IAM actions for this statement. **Resources.** Resource ARNs covered by this statement. **Conditions.** Optional IAM conditions for this statement. * Default: `[]` **Condition operator.** IAM condition operator used to compare the condition key and values. Common operators are listed, and custom IAM operators such as ForAnyValue:StringLike can be entered manually. * Default: `StringEquals` * Allowed values: `StringEquals` (String equals), `StringNotEquals` (String not equals), `StringEqualsIgnoreCase` (String equals ignore case), `StringNotEqualsIgnoreCase` (String not equals ignore case), `StringLike` (String like), `StringNotLike` (String not like), `NumericEquals` (Numeric equals), `NumericNotEquals` (Numeric not equals), `NumericLessThan` (Numeric less than), `NumericLessThanEquals` (Numeric less than or equals), `NumericGreaterThan` (Numeric greater than), `NumericGreaterThanEquals` (Numeric greater than or equals), `DateEquals` (Date equals), `DateNotEquals` (Date not equals), `DateLessThan` (Date less than), `DateLessThanEquals` (Date less than or equals), `DateGreaterThan` (Date greater than), `DateGreaterThanEquals` (Date greater than or equals), `Bool` (Boolean), `BinaryEquals` (Binary equals), `IpAddress` (IP address), `NotIpAddress` (Not IP address), `ArnEquals` (ARN equals), `ArnNotEquals` (ARN not equals), `ArnLike` (ARN like), `ArnNotLike` (ARN not like), `Null` **Condition key.** IAM context key evaluated by the condition. **Condition values.** Allowed or matched values for the condition key. **Permission boundary ARN.** Optional permissions boundary policy ARN for the role. * Pattern: `^arn:aws(-cn|-us-gov)?:iam::(aws|\d{12}):policy/.+$` — Use a valid IAM managed policy ARN. ### Instance profile **Create instance profile.** Create an IAM instance profile for EC2 instances to use this role. * Default: `false` * Immutable after creation **Instance profile name.** Instance profile name. Defaults to the role name when empty. * Immutable after creation * Pattern: `^[A-Za-z0-9+=,.@_-]{1,128}$` — Use 1-128 characters: letters, numbers, plus, equals, comma, period, at, underscore, or hyphen. * Shown when: `{"instance_profile_creation_enabled":true}` **Instance profile path.** IAM path for the instance profile. Defaults to the role path when empty. * Immutable after creation * Pattern: `^/$|^/.*/$` — Start and end with a slash, for example / or /service-roles/. * Shown when: `{"instance_profile_creation_enabled":true}` ### Misc **Tags.** A map of tags to assign to all resources. Default tags are `Owner`, `ProjectGivenId`, `EnvironmentGivenId`, `ModuleGivenId`, `ModuleId` ### Terraform settings **OpenTofu version override.** Override the environment's default version for this module **Ravion Terraform workspace name.** Override Terraform state backend workspace name. Defaults to project + environment + module given ids. * Immutable after creation **Advanced Terraform variables.** Optional raw Terraform variable overrides for advanced module inputs or one-off overrides. Values here override the generated variables above. * Default: `{}` **Terraform execution environment.** Override the execution environment for Terraform runners. Must use the same AWS account as selected above.