Fjall Docs — deploy AWS infrastructure into your own account

Overview

The Secret resource stores sensitive values such as database passwords and API keys in AWS Secrets Manager. Each secret it creates is encrypted with its own Customer Managed Key (CMK), and accepts a generated password, a JSON object of SecretValue references, or a plain string. Fjall creates these secrets for you inside the database, compute and pattern constructs. Declare one directly when an application needs a credential no other construct owns.

Resource Class

import {
  Secret,
  resolveImportedSecret,
  type SecretImport,
} from "@fjall/components-infrastructure/lib/resources/aws/secrets/secret";

The deep lib/... path is a published subpath of the package. Secrets constructs are not re-exported from the package root, so this import is the only one that compiles.

This page covers using the construct class directly. The scaffolded fjall/<app>/infrastructure.ts that fjall create app writes never does that: it imports App and the *Factory symbols from the package root, and fjall add edits it through the codemod engine. For runtime secrets you set yourself, use fjall secrets, which writes SSM Parameter Store SecureStrings rather than Secrets Manager entries.

Basic Usage

Generated Password

Prefer this shape. The value is generated inside AWS and never appears in your CDK source, the synthesised template, or any deploy artefact.

const dbSecret = new Secret(this, "DatabasePassword", {
  secretName: "api-db-password",
  generateSecretString: {
    secretStringTemplate: JSON.stringify({ username: "admin" }),
    generateStringKey: "password",
    excludePunctuation: true,
    includeSpace: false,
    passwordLength: 32,
  },
});

JSON Secret from Existing Values

Use secretObjectValue with SecretValue references when the value already lives somewhere secure, such as an SSM SecureString parameter.

const configSecret = new Secret(this, "AppConfig", {
  secretName: "api-configuration",
  secretObjectValue: {
    apiUrl: SecretValue.unsafePlainText("https://api.example.com"),
    stripeKey: SecretValue.ssmSecure("/api/stripe-key"),
  },
});

Plain String (Escape Hatch)

secretStringValue is wrapped in SecretValue.unsafePlainText, so the value is embedded verbatim in the synthesised CloudFormation template and every synth artefact. The construct raises a synth-time warning (@fjall/components-infrastructure:secrets:plainTextSecretValue) whenever you use it. Anyone with read access to the template, the deploy artefact, or the CloudFormation stack can recover the value.Use generateSecretString, or secretObjectValue with SecretValue.ssmSecure(...), instead.

const legacyKey = new Secret(this, "LegacyKey", {
  secretName: "legacy-api-key",
  secretStringValue: "super-secret-key",
});

secretStringValue wins over generateSecretString. Supplying both silently ignores the generator.

Configuration Options

Core Properties

Property	Type	Description	Default
`secretName`	`string`	Name of the secret in Secrets Manager	required
`description`	`string`	Secret description	-
`aliasName`	`string`	KMS alias for the wrapper-minted CMK	`cmk/${id}`
`replicaRegions`	`string[]`	Regions to replicate the secret into, used by Global Aurora	-
`importExisting`	`boolean`	Reference an existing secret by name instead of creating one	`false`

KMS aliases are unique per account and region. If your construct id is not account-unique (a fixed-name id inside a pattern deployed once per application, for example), pass an application-scoped aliasName or the second deployment fails.

Secret Value Options (use one)

Property	Type	Description
`generateSecretString`	`SecretStringGenerator`	Generate the value inside AWS
`secretObjectValue`	`{ [key: string]: SecretValue }`	JSON object built from `SecretValue` references
`secretStringValue`	`string`	Plain text, embedded in the template. Escape hatch.

Importing an Existing Secret

importExisting: true changes the construct’s behaviour: it references the secret by name and creates no CMK, so secretsCustomerManagedKey stays undefined. Every value option is ignored.

const replicated = new Secret(this, "ReplicaSecret", {
  secretName: "api-db-password",
  importExisting: true,
});

Default Features

Every secret the construct creates gets:

KMS encryption with its own Customer Managed Key
Automatic key and alias creation, alias cmk/${id}
Key rotation enabled on the CMK
getImport() for cross-stack consumption

CMK Removal Policy

The CMK is minted with protects: "stack-scoped", which resolves through the env-aware default rather than an unconditional RETAIN:

Environment	CMK removal policy
`production`	`RETAIN`
`staging`, `development`, `platform`, `compliance`, `root`	`DESTROY`, with a 30-day pending window

The 30-day pending window matches Secrets Manager’s own 30-day recovery window, so a secret deleted with its stack stays recoverable for as long as the key does. See KMS Key for the full protects contract.

Generated Passwords

Excluding Characters

const passwordSecret = new Secret(this, "UserPassword", {
  secretName: "api-user-password",
  generateSecretString: {
    passwordLength: 16,
    excludeCharacters: ' %+~`#$&*()|[]{}:;<>?!\'"/@"\\\\',
  },
});

Database Password with Username

const dbSecret = new Secret(this, "DBCredentials", {
  secretName: "api-rds-credentials",
  generateSecretString: {
    secretStringTemplate: JSON.stringify({
      username: "postgres",
      engine: "postgres",
    }),
    generateStringKey: "password",
    excludePunctuation: true,
    passwordLength: 30,
  },
});

API Key Generation

const apiKeySecret = new Secret(this, "APIKey", {
  secretName: "api-external-key",
  generateSecretString: {
    includeSpace: false,
    passwordLength: 40,
    excludeCharacters: '/@"\\\\ ',
    requireEachIncludedType: false,
  },
});

Consuming a Secret from Another Stack

getImport(field?) returns a SecretImport, the shape every Fjall compute construct accepts in its secretsImport map.

const dbSecret = new Secret(this, "Database", {
  secretName: "api-db-creds",
  generateSecretString: {
    secretStringTemplate: JSON.stringify({ username: "admin" }),
    generateStringKey: "password",
  },
});

// { id: "DatabaseSecret", name: <resolved secret name>, field: "password" }
const passwordImport = dbSecret.getImport("password");

// Whole secret, no field
const wholeImport = dbSecret.getImport();

The `SecretImport` Shape

Field	Type	Description
`id`	`string`	Construct id for the imported secret. Required.
`name`	`string`	Secret name. Resolved to its complete ARN at deploy time.
`arn`	`string`	Complete ARN. Escape hatch for cross-account or cross-region secrets.
`field`	`string`	Import a single JSON field instead of the whole value.

Supply exactly one of name or arn. Hand-write an import when the secret is managed outside your stack:

const externalSecret: SecretImport = {
  id: "StripeKey",
  name: "prod/stripe",
  field: "secretKey",
};

Deploy-Time ARN Resolution

resolveImportedSecret(scope, id, secretImport) turns a SecretImport into an ISecret whose ARN carries the AWS 6-character suffix. It resolves in three steps:

An explicit arn on the import.
The fjallResolvedSecretArns context map, which @fjall/deploy-core writes at deploy time after a DescribeSecret on every name.
Secret.fromSecretNameV2 as an offline cdk synth fallback.

Step 3 renders a suffixless partial ARN, which real Secrets Manager rejects with AccessDenied at task launch. A Fjall deploy always runs step 2, so the suffixless shape never reaches a deployed task definition. Do not hand-roll fromSecretNameV2 in your own constructs.

Integration with Resources

With RDS

Database constructs create and own their credentials secret. Read it with getCredentials(), which returns the same Secret wrapper.

const credentials = database.getCredentials();

const usernameImport = credentials.getImport("username");
const passwordImport = credentials.getImport("password");

With ECS

Pass imports through a container’s secretsImport map. Fjall resolves each one and injects it as an environment variable at task launch.

{
  name: "api",
  containers: [
    {
      name: "app",
      port: 3000,
      environment: {
        DATABASE_URL_BASE: database.getConnectionString(),
      },
      secretsImport: {
        DATABASE_USER: database.getCredentials().getImport("username"),
        DATABASE_PASSWORD: database.getCredentials().getImport("password"),
        STRIPE_KEY: paymentSecret.getImport("secretKey"),
      },
    },
  ],
}

With Lambda

LambdaFunction takes the same map.

const worker = new LambdaFunction(this, "Worker", {
  code: Code.fromAsset("lambda"),
  handler: "index.handler",
  runtime: Runtime.NODEJS_24_X,
  secretsImport: {
    DATABASE_PASSWORD: database.getCredentials().getImport("password"),
  },
});

Working against raw CDK instead, grant read access on the underlying ISecret:

const secret = new Secret(this, "WorkerSecret", {
  secretName: "worker-config",
  generateSecretString: { passwordLength: 32 },
});

secret.secret.grantRead(workerRole);

KMS Encryption

Default CMK Creation

const secret = new Secret(this, "ApiKey", {
  secretName: "api-key",
  generateSecretString: { passwordLength: 32 },
});

// Creates a nested CustomerManagedKey with construct id
// "ApiKeyCustomerManagedKey":
//   - description: "ApiKeyCustomerManagedKey KMS Key"
//   - alias: "cmk/ApiKey"
//   - key rotation: enabled
//   - removal policy: RETAIN in production, DESTROY (30-day pending
//     window) in every other environment

Access the CMK

secretsCustomerManagedKey is optional, because a secret created with importExisting: true has no key. Narrow it before use, or strictNullChecks rejects the read.

const cmk = secret.secretsCustomerManagedKey;
if (cmk !== undefined) {
  const kmsKey = cmk.key;
  const kmsAlias = cmk.alias;
}

Secret Rotation

Attach CDK’s SecretRotation to the underlying ISecret. Database constructs do this for you.

new SecretRotation(this, "Rotation", {
  application: SecretRotationApplication.POSTGRES_ROTATION,
  secret: dbSecret.secret,
  target: database,
  vpc: vpc,
});

Factory Pattern

Secret.build returns a factory that a StackBuilder invokes.

const secretFactory = Secret.build("ApiSecret", {
  secretName: "api-credentials",
  description: "External API credentials",
  generateSecretString: { passwordLength: 40 },
});

const secret = secretFactory(stackBuilder);

IAM Permissions

Grant Read Access

secret.secret.grantRead(lambdaRole);
secret.secret.grantRead(ecsTaskRole);

grantRead also grants kms:Decrypt on the CMK through the Secrets Manager service principal, so no separate key grant is needed.

Custom Permissions

role.addToPolicy(
  new PolicyStatement({
    actions: ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],
    resources: [secret.secret.secretArn],
    conditions: {
      StringEquals: {
        "secretsmanager:VersionStage": "AWSCURRENT",
      },
    },
  }),
);

Outputs

The nested CustomerManagedKey construct emits both CloudFormation outputs. Their names key off the CMK construct id, ${id}CustomerManagedKey, run through toPascalCase. Call that name.

Output key	Export name	Value
`${name}Arn`	`${stackName}${name}KeyArn`	CMK ARN
`${name}AliasArn`	`${stackName}${name}KeyAliasArn`	CMK alias ARN

Export names carry the emitting stack’s name as a prefix, because CloudFormation export names are unique per account and region. The output key is not prefixed. Build a cross-stack import from Stack.of(this).stackName, never from the bare ${name}KeyArn string.

For a Secret with id ApiKey in a stack named AcmeApiStorage:

Fn.importValue("AcmeApiStorageApiKeyCustomerManagedKeyKeyArn");

Complete Example

import { Secret } from "@fjall/components-infrastructure/lib/resources/aws/secrets/secret";
import { SecretValue } from "aws-cdk-lib";

// Application configuration, sourced from SSM SecureString parameters
const appConfig = new Secret(this, "AppConfiguration", {
  secretName: `${props.appName}-config`,
  description: "Application configuration and credentials",
  secretObjectValue: {
    stripeKey: SecretValue.ssmSecure(`/${props.appName}/stripe-key`),
    sendgridKey: SecretValue.ssmSecure(`/${props.appName}/sendgrid-key`),
  },
});

// Database credentials, generated inside AWS
const dbCredentials = new Secret(this, "DatabaseCredentials", {
  secretName: `${props.appName}-db-credentials`,
  description: "RDS master credentials",
  generateSecretString: {
    secretStringTemplate: JSON.stringify({
      username: "dbadmin",
      engine: "postgres",
    }),
    generateStringKey: "password",
    excludePunctuation: true,
    passwordLength: 32,
  },
});

// Inject into an ECS service
const service = {
  name: "api",
  containers: [
    {
      name: "app",
      port: 3000,
      environment: {
        APP_NAME: props.appName,
      },
      secretsImport: {
        STRIPE_KEY: appConfig.getImport("stripeKey"),
        SENDGRID_KEY: appConfig.getImport("sendgridKey"),
        DB_PASSWORD: dbCredentials.getImport("password"),
      },
    },
  ],
};

Best Practices

Generate values in AWS. Reach for generateSecretString first, SecretValue.ssmSecure second, secretStringValue never.
Inject through secretsImport, not environment. Environment variables land in the task definition in clear text.
Import a single field with getImport("password") rather than handing a whole JSON blob to a container.
Pass an application-scoped aliasName whenever the construct id repeats across applications in one account and region.
Rotate database credentials on a 30 to 90 day schedule.
Apply least-privilege IAM. Grant on the exact secret ARN, not a wildcard.
Separate secrets by purpose so a single grant does not expose unrelated credentials.
Monitor access with CloudTrail.

Cost

AWS list price, us-east-1:

$0.40 per secret per month
$0.05 per 10,000 API calls
$1** per month for the CMK, rising to about **$ 3 as key rotation mints its first two versions

Cost Saving Tips

Combine related values into one JSON secret rather than minting a secret per field. Each secret carries its own monthly charge and its own CMK.

// One secret, three fields, one monthly charge
const dbConfig = new Secret(this, "DBConfig", {
  secretName: "api-db-config",
  generateSecretString: {
    secretStringTemplate: JSON.stringify({
      username: "admin",
      host: "db.internal",
    }),
    generateStringKey: "password",
  },
});

Cache resolved values in long-lived Lambda handlers so repeated invocations do not re-charge per API call, and keep non-sensitive configuration in SSM Parameter Store standard parameters, which are free.

Security Considerations

Least-Privilege Access

const readOnlyPolicy = new PolicyStatement({
  actions: ["secretsmanager:GetSecretValue"],
  resources: [secret.secret.secretArn],
  principals: [readOnlyRole],
});

const conditionalPolicy = new PolicyStatement({
  actions: ["secretsmanager:GetSecretValue"],
  resources: [secret.secret.secretArn],
  conditions: {
    IpAddress: {
      "aws:SourceIp": ["10.0.0.0/8"],
    },
  },
});

Non-Production Key Deletion

Outside production, the CMK resolves to DESTROY. Deleting a staging stack schedules the key for deletion with a 30-day window, after which anything still encrypted with it becomes permanently unreadable. If a secret must survive its stack, create its key separately with protects: "outlives-stack".

Troubleshooting

Symptom	Cause and fix
`AccessDenied` at ECS task launch	The task role was granted a suffixless partial ARN. Route the import through `secretsImport`, which resolves the complete ARN at deploy time.
`No export named ...`	The export name is missing its stack prefix. Compose it from `Stack.of(this).stackName`.
`Object is possibly 'undefined'`	`secretsCustomerManagedKey` is optional. Narrow it before reading `.key` or `.alias`.
Alias already exists	Two constructs share an id in one account and region. Pass an application-scoped `aliasName`.
Secret not found	Verify the secret name and the region the stack deploys into.
KMS access error	Grant the principal key usage on the CMK, or use `grantRead`, which grants both.
Rotation failures	Check the rotation Lambda’s VPC placement and its network path to the database.
Plain-text warning at synth	A `secretStringValue` is in use. Switch to `generateSecretString` or `SecretValue.ssmSecure`.

Next Steps

KMS Key

Configure the customer-managed key that encrypts each secret.

IAM Role

Grant roles least-privilege read access to secrets.

RDS Instance

Manage database credentials with generated secrets.

ECS Cluster

Inject secrets into container tasks with secretsImport.

fjall secrets

Manage application secrets from the CLI in SSM Parameter Store.

Lambda Function

Inject secrets into Lambda handlers at runtime.

​Overview

​Resource Class

​Basic Usage

​Generated Password

​JSON Secret from Existing Values

​Plain String (Escape Hatch)

​Configuration Options

​Core Properties

​Secret Value Options (use one)

​Importing an Existing Secret

​Default Features

​CMK Removal Policy

​Generated Passwords

​Excluding Characters

​Database Password with Username

​API Key Generation

​Consuming a Secret from Another Stack

​The SecretImport Shape

​Deploy-Time ARN Resolution

​Integration with Resources

​With RDS

​With ECS

​With Lambda

​KMS Encryption

​Default CMK Creation

​Access the CMK

​Secret Rotation

​Factory Pattern

​IAM Permissions

​Grant Read Access

​Custom Permissions

​Outputs

​Complete Example

​Best Practices

​Cost

​Cost Saving Tips

​Security Considerations

​Least-Privilege Access

​Non-Production Key Deletion

​Troubleshooting

​Next Steps

KMS Key

IAM Role

RDS Instance

ECS Cluster

fjall secrets

Lambda Function

Overview

Resource Class

Basic Usage

Generated Password

JSON Secret from Existing Values

Plain String (Escape Hatch)

Configuration Options

Core Properties

Secret Value Options (use one)

Importing an Existing Secret

Default Features

CMK Removal Policy

Generated Passwords

Excluding Characters

Database Password with Username

API Key Generation

Consuming a Secret from Another Stack

The `SecretImport` Shape

Deploy-Time ARN Resolution

Integration with Resources

With RDS

With ECS

With Lambda

KMS Encryption

Default CMK Creation

Access the CMK

Secret Rotation

Factory Pattern

IAM Permissions

Grant Read Access

Custom Permissions

Outputs

Complete Example

Best Practices

Cost

Cost Saving Tips

Security Considerations

Least-Privilege Access

Non-Production Key Deletion

Troubleshooting

Next Steps