AWS Secrets Manager

The aws ingredient stores encryption and vault-signing keys in AWS Secrets Manager. Application variables stay in your repository vault. ramenv uses the AWS Rust SDK’s default credential provider chain for initialization and runtime operations.

Local SSO setup

Configure an IAM Identity Center profile once, then sign in:

aws configure sso --profile dev
aws sso login --profile dev
export AWS_PROFILE=dev
ramenv init --ingredient aws

For a monorepo, replace the last command with ramenv init workspace --ingredient aws.

Initialization prompts for a Secrets Manager region, such as us-east-1, and saves it as provider_location in .ramenv.keyrefs.toml. The saved region takes precedence over the SDK’s default region; changing AWS_REGION does not move the keys.

Refresh an expired SSO session with aws sso login --profile dev. For access-key profiles, use aws configure --profile dev; prefer SSO or temporary role credentials over long-lived keys.

Credential selection

The SDK searches in this order:

1. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, with AWS_SESSION_TOKEN for temporary credentials.
2. Shared profiles selected by AWS_PROFILE, or default. Profiles may use SSO, access keys, assume-role settings, or credential_process.
3. Web identity configuration, including AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE.
4. Container credential endpoints, including ECS task roles and EKS Pod Identity.
5. EC2 instance metadata through IMDSv2.

Environment credentials override AWS_PROFILE. Unset stale access-key variables before using an SSO profile. Shared profiles can also take precedence over workload identities.

AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE override shared file locations. AWS_EC2_METADATA_DISABLED=true disables EC2 metadata credential lookup. There is no RAMENV_AWS_CREDENTIAL setting.

If authorization fails, ramenv keeps using the selected profile or role. Check that identity and its permissions.

Required permissions

Operation	IAM permission
Create key secrets	secretsmanager:CreateSecret
Write a new key version	secretsmanager:PutSecretValue
Read a pinned key version	secretsmanager:GetSecretValue
Remove key secrets	secretsmanager:DeleteSecret

Scope access to the intended account, region, and ramenv resources. Resource policies, service control policies, and explicit denies still apply. Customer-managed KMS keys may require additional KMS permissions and a compatible key policy.

An identity that only reads existing keys needs read permissions. Grant provisioning or deletion permissions to identities that manage workspace keys.

Deploy with a workload role

Use an attached instance, task, or workload role and let the platform supply temporary credentials. Do not package personal AWS profiles or access keys in the deployment. Remove higher-priority credentials if the workload must use its attached role.

See deployment for the files to ship and how to gate startup with validation.

Versions and deletion

Key refs use ARN#VersionId. ramenv reads the exact saved version and checks references against the saved region. Updates write a new version and save its reference after pending remote operations succeed.

Removing an environment schedules deletion of the entire key secret with AWS’s default recovery window. ramenv does not force immediate deletion. A pending-deletion secret must be restored or permanently deleted before its name can be reused. A secret already missing is treated as successfully deleted.

Diagnose failures

• Expired session: sign in again with the intended profile.
• Unexpected identity: inspect environment credentials before changing IAM policies.
• AccessDeniedException: check permissions in the workspace’s saved region, including KMS and policy restrictions. No alternative role is tried after this error.
• Credential endpoint failure: repair the SDK credential source; ramenv adds no custom fallback.

For resolver details, see the source authentication guide and the AWS Rust SDK credential documentation.