UNDERSTANDING AWS SECRETS MANAGER IN SWAMP

Swamp has two separate ways to work with AWS Secrets Manager, and they answer different questions. The @swamp/aws-sm extension answers the question "where do my secret values live?" It is a vault provider, so Secrets Manager becomes a place Swamp stores values and reads them back through vault.get(). The @swamp/aws/secretsmanager extension answers a different question: "how is my Secrets Manager account configured?" It provides behavior types that treat secrets, rotation schedules, resource policies and secret target attachments as infrastructure to create, update and keep track of.

The two can be used independently. A team might use only the vault, with secrets created through the console, or only the behavior types, with values consumed by applications outside Swamp. The split is easier to understand once you see that one extension handles values and the other handles configuration.

The vault side

A vault of type @swamp/aws-sm needs only a region and, optionally, a profile. Vault keys map directly to Secrets Manager secret names, including path-style names such as myapp/production/db-password. This means the names you see in the AWS console are the names you pass to vault.get(), with no translation layer to remember.

Annotations map onto native Secrets Manager features rather than onto a separate metadata store. Notes go into the secret's Description field and labels become resource tags. URLs are written into the Description field as a trailing swamp:url= line. They would fit more naturally in a tag, but AWS tag values reject characters such as ? and &, which are common in URLs. Older secrets with a swamp:url tag are still read. Because annotations use native features, the metadata stays visible to anyone looking at the secret in AWS, not only to Swamp.

Deletion uses Secrets Manager's default 30-day recovery window. A deleted secret is scheduled for deletion and can be restored during that window. Its name cannot be reused until the window ends. In practice, deleting and then recreating a key under the same name fails for a month. This is AWS behaviour that Swamp does not hide.

The behavior side

The @swamp/aws/secretsmanager extension provides four behavior types: secret, rotation-schedule, resource-policy and secret-target-attachment. They share a shape. Each requires a name global argument, which is the instance name that identifies the behavior in the factory pattern. Each has the same six methods: create, get, update, delete, sync and list. The page Behaviors, Types, and Methods covers the general relationship between a type and its methods. Reuse a Behavior with the Factory Pattern shows how one definition can stand for many instances.

The remaining arguments follow the AWS resource properties closely, for example SecretId, RotationRules, ResourcePolicy and ReplicaRegions. This makes the AWS documentation for each property a useful companion. The cost is that the arguments use AWS's capitalisation instead of a Swamp-specific vocabulary.

Where results go

Every method writes resource state as data: SecretsManager Secret resource state, RotationSchedule resource state, and so on. A create records what was made. A sync reads the current state back from AWS and records it again. This matters when someone changes a rotation rule or policy in the console, because a later sync brings the recorded state back in line with reality. That state can be queried with swamp data query like any other data. The Data Layer describes how that data is versioned and kept.

Keeping values out of the repository

The secret type accepts both SecretString and GenerateSecretString. SecretString takes the literal value, which would then sit in a behavior definition under version control. GenerateSecretString describes the value instead: its length and which character classes to exclude. AWS generates the value, so it never passes through the repository. For passwords that only a database and an application need to know, the generated form is usually the better choice.

The two extensions also meet here. A secret created by the secret behavior type has a Secrets Manager name, and vault keys are secret names. So a vault of type @swamp/aws-sm in the same region can read that secret back by name. Other behaviors can then reference it through vault.get() instead of copying it anywhere.

Credential decisions

Neither extension stores AWS credentials in its own configuration, but they leave several choices open. By default, both use the AWS credential chain: environment variables, ~/.aws/credentials, or an attached IAM role. This suits CI runners and instances with roles, where the environment already sets the identity.

A vault can instead be pinned to a named profile. A configured profile takes precedence over environment-variable credentials. The vault then keeps the same identity even when a shell exports other credentials for a different task. Some teams prefer this so that whoever happens to be running a command cannot change where secrets are read from. Others prefer the default chain because it lets the same repository run unchanged in different accounts. Profiles that assume a role and SSO profiles are supported. credential_process profiles may not be. Authenticate to AWS with SSO covers the SSO sign-in.

The behavior types offer a per-behavior option: accessKeyId, secretAccessKey and sessionToken global arguments, which override the environment. Wiring them with vault.get() keeps the keys in a vault and out of the definition. Short-lived credentials stored this way go stale, and Auto-Refresh Cloud Credentials addresses that. A behavior's region defaults to us-east-1. Setting it explicitly avoids confusion when the vault and the behaviors point at different regions.

Composing the pieces

The resource types depend on one another. A rotation schedule and a resource policy both name a secret through SecretId, so the secret has to exist first. A workflow captures that order: create the secret, then attach the policy, then apply the rotation schedule. The sequence then runs the same way every time, not from memory. See Create and Run a Workflow.

Once behaviors and workflows read values through a Secrets Manager vault, the next question is who read what, and when. Enable and Query the Vault Audit Trail records vault reads. AWS's own logging of Secrets Manager calls records access from the AWS side.