> ## 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 Policy

> Creates one reusable customer-managed AWS IAM policy from structured statements or a complete JSON policy document.

**Type:** `rvn-aws-iam-policy` · **Latest version:** `0.1.0`

## Readme

Creates one reusable customer-managed AWS IAM policy from structured statements or a complete JSON policy document.

### Overview

Use this module when permissions need to be managed independently from an IAM role. The policy ARN can be attached to one or more roles, reused across workloads, or supplied as a permissions boundary.

Customer-managed policies are versioned by AWS when their document changes. Keep statements narrowly scoped to the actions and resource ARNs each workload needs.

### Use cases

| Scenario                     | Benefit                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| Shared workload permissions  | Reuse one policy across several IAM roles without duplicating inline policy documents.               |
| Permissions boundary         | Set the maximum permissions that another IAM role can receive.                                       |
| Independently managed access | Update permissions without combining policy ownership with trust relationships or instance profiles. |
| Complex policy document      | Use complete JSON when a policy cannot be represented by the structured statement form.              |

### Policy documents

Structured statements are the default. Each statement requires an effect, either Action or NotAction values, and either Resource or NotResource values. Optional conditions can restrict access by IAM context keys such as account, source ARN, principal tags, or resource tags.

NotAction and NotResource invert what a statement matches. They can simplify explicit deny policies, but combining either with Allow can grant broader access than expected. Prefer listed actions and resources unless an inverse statement is necessary.

JSON document accepts a complete IAM policy document. Use this mode for uncommon IAM elements or documents produced by another trusted policy-authoring workflow. The JSON document replaces structured statements rather than merging with them.

IAM policies can have broad security impact. Avoid wildcard actions and resources unless the AWS service requires them, and add conditions where they reduce unintended access.

### Using the policy

This module creates the policy but does not attach it. Attach the Policy ARN output through the AWS IAM Role module's Managed policy ARNs setting, or use it as that module's Permission boundary ARN.

Keeping policy creation and role creation separate allows a policy to be shared, audited, and updated without duplicating role trust configuration.

### Configuration

| Setting                         | Required           | Default               | Notes                                                                                               |
| ------------------------------- | ------------------ | --------------------- | --------------------------------------------------------------------------------------------------- |
| AWS account                     | Yes                | None                  | AWS account where the customer-managed policy is created.                                           |
| Region                          | Yes                | None                  | Runner region for the stack. IAM resources are global, but Terraform still runs with an AWS region. |
| Policy name                     | Yes                | Module given ID       | Must be unique within the selected path in the AWS account.                                         |
| Description                     | No                 | None                  | AWS does not allow a managed policy description to be edited after creation.                        |
| Path                            | No                 | /                     | IAM path used to organize the policy.                                                               |
| Policy document format          | Yes                | Structured statements | Chooses between the statement editor and complete JSON.                                             |
| Policy statements               | In structured mode | Empty list            | At least one statement is required when structured mode is selected.                                |
| Policy JSON                     | In JSON mode       | None                  | Complete policy document used instead of structured statements.                                     |
| 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 manages one policy and no attachments. IAM roles, users, and groups have separate lifecycles, while a customer-managed policy may be shared by several consumers.

Structured statements require an explicit Action or NotAction choice and an explicit Resource or NotResource choice. The module does not add wildcard permissions automatically.

Policy name, description, and path are immutable in Ravion because AWS replaces the managed policy when any of these values change. Replacement would sever attachments managed outside this module.

Ravion adds standard tags for ownership and traceability. User-provided Tags are merged on top for team, cost, or environment metadata.

### Learn more

* [IAM managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.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-policy@0.1.0/security/iam_policy)

## Inputs reference

All inputs for `rvn-aws-iam-policy` version `0.1.0`. Use the `name` shown for each field as the input key in module config.

### AWS account & region

<ResponseField name="aws_account_id" type="string" required>
  **AWS account.**

  * Immutable after creation
</ResponseField>

<ResponseField name="aws_region" type="string" required>
  **Region.**

  * Immutable after creation
</ResponseField>

### IAM policy

<ResponseField name="name" type="string" required>
  **Policy name.** Name of the customer-managed IAM policy. Policy names must be unique within their path in the AWS account.

  * Default: `<<module.given_id>>`
  * Immutable after creation
  * Pattern: `^[A-Za-z0-9+=,.@_-]{1,128}$` — 1-128 letters, numbers, plus, equals, comma, period, at, underscore, or hyphen characters.
</ResponseField>

<ResponseField name="description" type="string">
  **Description.** Optional description stored on the IAM policy. AWS does not allow this value to be changed after creation.

  * Immutable after creation
  * Pattern: `^.{0,1000}$` — 1000 characters or fewer.
</ResponseField>

<ResponseField name="path" type="string" required>
  **Path.** IAM path for organizing the policy. Most policies should use the root path.

  * Default: `/`
  * Immutable after creation
  * Pattern: `^/$|^/.*/$` — Start and end with a slash, for example / or /application/.
  * Pattern: `^[^*]*$` — Asterisks are not allowed in IAM paths.
  * Pattern: `^.{1,512}$` — 512 characters or fewer.
</ResponseField>

### Policy document

<ResponseField name="policy_document_mode" type="string" required>
  **Policy document format.** Build the policy with structured statements or provide a complete JSON document.

  * Default: `structured`
  * Allowed values: `structured` (Structured statements), `json` (JSON document)
</ResponseField>

<ResponseField name="policy_statements" type="object_array" required>
  **Policy statements.** Define permissions this policy grants or denies. Each statement matches Action or NotAction values against Resource or NotResource ARNs and can add conditions to narrow access. Prefer explicit actions and resource ARNs over wildcards.

  * Default: `[]`
  * Shown when: `{"policy_document_mode":"structured"}`

  <Expandable title="item fields">
    <ResponseField name="sid" type="string">
      **SID.** Optional IAM statement ID.
    </ResponseField>

    <ResponseField name="effect" type="string" required>
      **Effect.** Whether this statement allows or denies the listed actions.

      * Default: `Allow`
      * Allowed values: `Allow`, `Deny`
    </ResponseField>

    <ResponseField name="action_match_mode" type="string" required>
      **Action matching.** Match the listed actions or every applicable action except those listed.

      * Default: `Action`
      * Allowed values: `Action` (Listed actions), `NotAction` (All except listed actions)
    </ResponseField>

    <ResponseField name="actions" type="string_array" required>
      **Actions.** IAM actions granted or denied by this statement.

      * Shown when: `{"action_match_mode":"Action"}`
    </ResponseField>

    <ResponseField name="not_actions" type="string_array" required>
      **Excluded actions (NotAction).** IAM actions excluded from this statement's match. NotAction can create broad permissions and should be used carefully.

      * Shown when: `{"action_match_mode":"NotAction"}`
    </ResponseField>

    <ResponseField name="resource_match_mode" type="string" required>
      **Resource matching.** Match the listed resources or every applicable resource except those listed.

      * Default: `Resource`
      * Allowed values: `Resource` (Listed resources), `NotResource` (All except listed resources)
    </ResponseField>

    <ResponseField name="resources" type="string_array" required>
      **Resources.** Resource ARNs covered by this statement. Use wildcards only when the AWS service requires them.

      * Shown when: `{"resource_match_mode":"Resource"}`
    </ResponseField>

    <ResponseField name="not_resources" type="string_array" required>
      **Excluded resources (NotResource).** Resource ARNs excluded from this statement's match. NotResource can create broad permissions and should be used carefully.

      * Shown when: `{"resource_match_mode":"NotResource"}`
    </ResponseField>

    <ResponseField name="conditions" type="object_array">
      **Conditions.** Optional IAM conditions that further restrict this statement.

      * Default: `[]`

      <Expandable title="item fields">
        <ResponseField name="test" type="string" required>
          **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`
        </ResponseField>

        <ResponseField name="variable" type="string" required>
          **Condition key.** IAM context key evaluated by the condition.
        </ResponseField>

        <ResponseField name="values" type="string_array" required>
          **Condition values.** Allowed or matched values for the condition key.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="policy_json" type="text" required>
  **Policy JSON.** Complete IAM policy JSON document. This is used instead of structured statements.

  * Pattern: `^\s*\{[\s\S]*"Version"[\s\S]*"Statement"[\s\S]*\}\s*$` — Include a JSON object with Version and Statement properties.
  * Shown when: `{"policy_document_mode":"json"}`
</ResponseField>

### Misc

<ResponseField name="tags" type="keyvalue">
  **Tags.** A map of tags to assign to all resources. Default tags are `Owner`, `ProjectGivenId`, `EnvironmentGivenId`, `ModuleGivenId`, `ModuleId`
</ResponseField>

### Terraform settings

<ResponseField name="opentofu_version" type="string">
  **OpenTofu version override.** Override the environment's default version for this module
</ResponseField>

<ResponseField name="ravion_state_backend_workspace" type="string">
  **Ravion Terraform workspace name.** Override Terraform state backend workspace name. Defaults to project + environment + module given ids.

  * Immutable after creation
</ResponseField>

<ResponseField name="advanced_terraform_variables" type="object">
  **Advanced Terraform variables.** Optional raw Terraform variable overrides for advanced module inputs or one-off overrides. Values here override the generated variables above.

  * Default: `{}`
</ResponseField>

<ResponseField name="execution_environment_id" type="string">
  **Terraform execution environment.** Override the execution environment for Terraform runners. Must use the same AWS account as selected above.
</ResponseField>