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

> Generates a random value and stores it in SSM Parameter Store or Secrets Manager without it ever appearing in Terraform state.

**Type:** `rvn-aws-secret` · **Latest version:** `1.0.0`

## Readme

Generates a random value, such as an API key, master key, or session secret, and stores it in SSM Parameter Store or Secrets Manager. The value never appears in Terraform state, plans, Ravion, or your project config.

### Overview

Use this module when an app needs a secret that nobody has to type in or copy around. The module generates the value during apply and writes it directly to AWS. It only outputs the parameter or secret ARN and name, so other modules can reference the secret without ever seeing it.

### Using the secret in a service

Pass the `arn` output to an ECS service as a runtime secret:

```yaml theme={null}
secrets:
  - name: MEILI_MASTER_KEY
    valueFrom: << modules.meilisearch-master-key.output.arn >>
```

ECS reads the value when each task starts. ECS services created with Ravion can already read parameters and secrets in the same AWS account and region.

### Stores

| Store               | Resource                          | Default encryption   | Notes                                                                                                                                                 |
| ------------------- | --------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| SSM Parameter Store | Standard `SecureString` parameter | `aws/ssm`            | Free. Regional only.                                                                                                                                  |
| Secrets Manager     | Secret with one version           | `aws/secretsmanager` | About \$0.40 per secret per Region per month plus API calls. Optional replication to other Regions. Deleted secrets are kept for the recovery window. |

### Replication

Secrets Manager replicas are read-only copies kept in sync by Secrets Manager with the same name as the primary secret. Their ARN differs only by Region, so use the `replica_arns` output for services running in each replica Region.

When you provide a customer managed KMS key, replicas use it only when you provide an alias that exists in each replica Region. Key IDs and ARNs are Region-specific, so replicas fall back to the AWS managed key.

### Rotation

Increase Rotation version to generate a new value and overwrite the stored one. Changes to Length or Special characters only take effect on the next rotation, so the current value never changes unexpectedly. Services pick up the new value the next time their tasks start, for example on their next deploy.

### Configuration

| Setting                | Required             | Default                                   | Notes                                                           |
| ---------------------- | -------------------- | ----------------------------------------- | --------------------------------------------------------------- |
| AWS account            | Yes                  | None                                      | AWS account where the secret is stored.                         |
| Region                 | Yes                  | None                                      | AWS Region where the secret is stored.                          |
| Store                  | Yes                  | SSM Parameter Store                       | Parameter Store or Secrets Manager.                             |
| Name                   | Yes                  | `ravion/<project>/<environment>/<module>` | Parameter Store names get a leading slash.                      |
| Length                 | Yes                  | 32                                        | 16 to 512 characters.                                           |
| Special characters     | No                   | Off                                       | Letters and numbers only by default.                            |
| Rotation version       | Yes                  | 1                                         | Increase to rotate the value.                                   |
| KMS key                | No                   | AWS managed key                           | Customer managed key for encryption.                            |
| Recovery window (days) | Secrets Manager only | 30                                        | 7 to 30.                                                        |
| Replica regions        | Secrets Manager only | None                                      | Additional Regions that receive a copy.                         |
| Tags                   | No                   | Standard Ravion tags                      | Additional tags merged with Ravion ownership and identity tags. |

### Design decisions

The value is generated with an ephemeral resource and written through write-only arguments. OpenTofu never persists ephemeral values or write-only arguments, so the value exists only in Parameter Store or Secrets Manager. This requires OpenTofu 1.11 or later.

Store, name, AWS account, and Region are immutable because changing them creates a different parameter or secret, and services referencing the old ARN would lose access.

### Learn more

* [SSM Parameter Store SecureString parameters](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-securestring.html)
* [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)
* [Passing secrets to ECS tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html)
* [OpenTofu ephemeral resources](https://opentofu.org/docs/language/ephemerality/)
* [Source module](https://github.com/ravionhq/modules/tree/rvn-aws-secret@1.0.0/security/secret)

## Inputs reference

All inputs for `rvn-aws-secret` version `1.0.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>

### Secret

<ResponseField name="store" type="string" required>
  **Store.** Parameter Store is free and regional. Secrets Manager costs about \$0.40 per secret per Region per month and can replicate to other Regions.

  * Default: `parameter_store`
  * Allowed values: `parameter_store` (SSM Parameter Store), `secrets_manager` (Secrets Manager)
  * Immutable after creation
</ResponseField>

<ResponseField name="name" type="string" required>
  **Name.** Parameter Store adds a leading slash and doesn't allow + = @ or names starting with aws or ssm. Can't be changed later.

  * Default: `ravion/<<project.given_id>>/<<environment.given_id>>/<<module.given_id>>`
  * Immutable after creation
  * Pattern: `^/?[A-Za-z0-9_.+=@-]+(/[A-Za-z0-9_.+=@-]+)*$` — Up to 512 letters, numbers, and . \_ - + = @ /, with no empty path segments.
</ResponseField>

<ResponseField name="length" type="number" required>
  **Length.** Characters in the generated value, from 16 to 512. Applies on the next rotation.

  * Default: `32`
  * Min: `16`
  * Max: `512`
</ResponseField>

<ResponseField name="recovery_window_in_days" type="number" required>
  **Recovery window (days).** How long a deleted secret can be restored before AWS removes it for good.

  * Default: `30`
  * Min: `7`
  * Max: `30`
  * Shown when: `{"store":"secrets_manager"}`
</ResponseField>

<ResponseField name="replica_regions" type="string_array">
  **Replica regions.** Additional Regions that receive a copy of the secret. Services in those Regions use the replica ARN from the replica\_arns output.

  * Default: `[]`
  * Shown when: `{"store":"secrets_manager"}`
</ResponseField>

<ResponseField name="special_characters" type="boolean">
  **Special characters.** Leave off for values used in URLs, headers, or connection strings. Applies on the next rotation.

  * Default: `false`
</ResponseField>

<ResponseField name="rotation_version" type="number" required>
  **Rotation version.** Increase to replace the stored value. Services pick it up when their tasks next start.

  * Default: `1`
  * Min: `1`
</ResponseField>

<ResponseField name="kms_key_id" type="string">
  **KMS key.** Customer managed key for encryption. Leave blank to use the AWS managed key.
</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>