AWS SECRETS MANAGER WITH SWAMP
Swamp works with AWS Secrets Manager through two extensions. Each one covers a different part of the service.
The first extension, @swamp/aws-sm, is a vault provider. A vault of type
@swamp/aws-sm reads, writes and deletes secrets stored in Secrets Manager.
Behaviors use the stored values through
${{ vault.get('<vault-name>', '<key>') }} expressions, so the values never
appear in behavior definitions. Vault keys map directly to Secrets Manager
secret names, including path-style names such as myapp/production/db-password.
The vault also supports annotations: notes and URLs are kept in the secret's
Description field and labels become resource tags. Deleting a secret uses the
default 30-day recovery window. The vault's configuration has a required
region key and an optional profile key. Without a profile, the vault uses
the default AWS credential chain. With a profile, it always authenticates as
that profile, whatever credentials the shell exports. The manual page
Use AWS Secrets Manager covers the basic
vault setup, and
Pin a Secrets Manager vault to a named AWS profile
covers the profile variant.
The second extension, @swamp/aws/secretsmanager, provides behavior types that
manage Secrets Manager resources as infrastructure. It has four types:
@swamp/aws/secretsmanager/secret,
@swamp/aws/secretsmanager/rotation-schedule,
@swamp/aws/secretsmanager/resource-policy and
@swamp/aws/secretsmanager/secret-target-attachment. Each type has create,
get, update, delete, sync and list methods. Each method writes the
resource's state as data, which you can query later. The secret type accepts a
GenerateSecretString object, which makes AWS generate the secret value so the
value never has to be written into the repository. The how-to guides cover
scheduling automatic rotation
for an existing secret and
attaching a resource policy
that grants one IAM role read access.
Get started
curl -fsSL https://swamp-club.com/install.sh | sh swamp repo init swamp extension pull @swamp/aws-sm swamp extension pull @swamp/aws/secretsmanagerCredentials
Neither extension keeps AWS credentials in its configuration. The vault uses the
default credential chain or a named profile. The behavior types also use the
default credential chain. They accept optional accessKeyId, secretAccessKey
and sessionToken global arguments, which can be wired from a vault with
vault.get(). A behavior's region defaults to us-east-1 unless you set it.
If your organisation signs in to AWS through IAM Identity Center, see
Authenticate to AWS with SSO.
Where to start
If you are new to these extensions, Getting started with AWS Secrets Manager sets up a repository and pulls the behavior types into it. Understanding AWS Secrets Manager in Swamp explains how the vault and the behavior types split the work and where their state is recorded. The extensions reference lists every argument and method.
AWS Secrets Manager documentation
Getting started with AWS Secrets Manager
Pull the @swamp/aws/secretsmanager extension, define a secret behavior with a generated password, validate it offline, and run create to provision it in AWS.
Tutorials →Pin a Secrets Manager vault to a named AWS profile
Create an @swamp/aws-sm vault pinned to a named AWS profile so it keeps its identity regardless of shell credentials, then write a secret and list the keys.
How-to Guides →Schedule automatic rotation for a Secrets Manager secret
Define a rotation-schedule behavior that rotates an existing secret every 30 days with a Lambda function, validate the definition, and apply it with create.
How-to Guides →Attach a resource policy to a Secrets Manager secret
Write a resource-policy behavior that grants one IAM role read access to a secret, pass the policy document as JSON, validate it, and attach it with create.
How-to Guides →AWS Secrets Manager extensions
Every Swamp extension for AWS Secrets Manager: behavior types, global arguments, methods, vault settings and the data each writes, from the live registry.
Reference →Understanding AWS Secrets Manager in Swamp
How the @swamp/aws-sm vault and the @swamp/aws/secretsmanager behavior types divide the work, where state lands as data, and credential choices teams make.
Explanation →