Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Overview

The Secret resource stores sensitive values such as database passwords, API keys, and other credentials. Each secret is encrypted with a Customer Managed Key (CMK) and accepts simple strings or JSON objects.

Resource Class

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

Basic Usage

Simple Secret

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

Generated Password

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

JSON Secret

const configSecret = new Secret(this, "AppConfig", {
  secretName: "app-configuration",
  secretObjectValue: {
    apiUrl: SecretValue.unsafePlainText("https://api.example.com"),
    apiKey: SecretValue.unsafePlainText("key-123"),
    environment: SecretValue.unsafePlainText("production"),
  },
});

Configuration Options

Core Properties

Property	Type	Description
`secretName`	`string`	Name of the secret
`description`	`string`	Secret description
`aliasName`	`string`	KMS key alias name

Secret Value Options (use one)

Property	Type	Description
`secretStringValue`	`string`	Plain text secret value
`secretObjectValue`	`{[key: string]: SecretValue}`	JSON object with multiple values
`generateSecretString`	`SecretStringGenerator`	Generate random password

Default Features

Every secret includes:

KMS encryption with Customer Managed Key
Automatic key creation with alias cmk/${id}
Key retention on stack deletion (RETAIN policy)
Import/export capabilities

Generated Passwords

Basic Password Generation

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

Database Password with Username

const dbSecret = new Secret(this, "DBCredentials", {
  secretName: "rds-credentials",
  generateSecretString: {
    secretStringTemplate: JSON.stringify({
      username: "postgres",
      engine: "postgres",
      host: "myapp-db.cluster-abc123.us-east-1.rds.amazonaws.com",
    }),
    generateStringKey: "password",
    excludePunctuation: true,
    passwordLength: 30,
  },
});

API Key Generation

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

Import/Export Pattern

Export for Cross-Stack Usage

const secret = new Secret(this, "SharedSecret", {
  secretName: "shared-credentials",
});

// Get import configuration
const importConfig = secret.getImport();
// Returns: { id: string, name: string, field?: string }

// Export for other stacks
new CfnOutput(this, "SecretImport", {
  value: JSON.stringify(importConfig),
});

Import Specific Field

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

// Import just the password field
const passwordImport = dbSecret.getImport("password");

Integration with Resources

With RDS

// Used automatically in RDS constructs
const database = new RdsInstance(this, "Database", {
  databaseName: "myapp",
  // Secret created automatically
});

// Access the credentials
const credentials = database.getCredentials();
const passwordImport = credentials.getImport("password");

With ECS

const appSecret = new Secret(this, "AppSecrets", {
  secretName: "app-secrets",
  secretObjectValue: {
    dbPassword: SecretValue.unsafePlainText("temp"),
    apiKey: SecretValue.unsafePlainText("temp"),
  },
});

const container = taskDefinition.addContainer("app", {
  secrets: {
    DB_PASSWORD: EcsSecret.fromSecretsManager(appSecret, "dbPassword"),
    API_KEY: EcsSecret.fromSecretsManager(appSecret, "apiKey"),
  },
});

With Lambda

const secret = new Secret(this, "LambdaSecret", {
  secretName: "lambda-config",
});

const fn = new Function(this, "MyFunction", {
  environment: {
    SECRET_ARN: secret.secret.secretArn,
  },
});

// Grant read permission
secret.secret.grantRead(fn);

KMS Encryption

Default CMK Creation

const secret = new Secret(this, "MySecret", {
  secretName: "my-secret",
});

// Automatically creates:
// - KMS key with description "${id} KMS Key"
// - Key alias: "cmk/${id}"
// - Retention policy: RETAIN

Access the CMK

const secret = new Secret(this, "EncryptedSecret", {
  secretName: "encrypted",
});

// Access the key
const kmsKey = secret.secretsCustomerManagedKey.key;
const kmsAlias = secret.secretsCustomerManagedKey.alias;

Secret Rotation

Enable Rotation

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

// Add rotation (typically done in database constructs)
new SecretRotation(this, "Rotation", {
  application: SecretRotationApplication.POSTGRES_ROTATION,
  secret: dbSecret.secret,
  target: database,
  vpc: vpc,
});

Factory Pattern

Using StackBuilder

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

const secret = secretFactory(stackBuilder);

IAM Permissions

Grant Read Access

const secret = new Secret(this, "ReadableSecret", {
  secretName: "app-config",
});

// Grant read to a role
secret.secret.grantRead(lambdaRole);

// Grant read to a service
secret.secret.grantRead(ecsTaskRole);

Custom Permissions

const secret = new Secret(this, "CustomSecret", {
  secretName: "restricted",
});

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

Outputs

The nested CustomerManagedKey construct creates the KMS key outputs. Export names key off the CMK construct id (${id}CustomerManagedKey), run through toPascalCase, so the value below is name = toPascalCase($CustomerManagedKey):

// Key ARN output
{
  key: `${name}Arn`,
  value: this.key.keyArn,
  exportName: `${name}KeyArn`
}

// Alias ARN output
{
  key: `${name}AliasArn`,
  value: this.alias.aliasArn,
  exportName: `${name}KeyAliasArn`
}

Complete Example

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

// Application configuration secret
const appConfig = new Secret(this, "AppConfiguration", {
  secretName: `${props.appName}-config-${props.environment}`,
  description: "Application configuration and credentials",
  secretObjectValue: {
    // Database
    dbHost: SecretValue.unsafePlainText(database.getHostEndpoint()),
    dbName: SecretValue.unsafePlainText("production"),

    // External APIs
    stripeKey: SecretValue.unsafePlainText("sk_live_xxx"),
    sendgridKey: SecretValue.unsafePlainText("SG.xxx"),

    // Feature flags
    maintenanceMode: SecretValue.unsafePlainText("false"),
    debugEnabled: SecretValue.unsafePlainText("false"),
  },
});

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

// API key for external service
const apiKey = new Secret(this, "ExternalAPIKey", {
  secretName: "payment-processor-key",
  secretStringValue: props.paymentApiKey, // From environment
  description: "Payment processor API key",
});

// Grant permissions
const appRole = new Role(this, "AppRole", {
  assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com"),
});

appConfig.secret.grantRead(appRole);
dbCredentials.secret.grantRead(appRole);
apiKey.secret.grantRead(appRole);

// Use in ECS task
const container = taskDefinition.addContainer("app", {
  environment: {
    APP_NAME: props.appName,
    ENVIRONMENT: props.environment,
  },
  secrets: {
    // From app config
    DB_HOST: EcsSecret.fromSecretsManager(appConfig.secret, "dbHost"),
    DB_NAME: EcsSecret.fromSecretsManager(appConfig.secret, "dbName"),

    // From db credentials
    DB_PASSWORD: EcsSecret.fromSecretsManager(dbCredentials.secret, "password"),

    // From API key
    PAYMENT_API_KEY: EcsSecret.fromSecretsManager(apiKey.secret),
  },
});

// Export for other stacks
new CfnOutput(this, "AppConfigImport", {
  value: JSON.stringify(appConfig.getImport()),
  description: "Import configuration for app secrets",
});

Best Practices

Never hardcode secrets. Store them in Secrets Manager.
Use generated passwords for databases.
Rotate secrets every 30 to 90 days.
Apply least-privilege IAM policies.
Separate secrets by purpose. Do not mix unrelated secrets.
Tag secrets for cost allocation and compliance.
Monitor access with CloudTrail.

Cost Optimisation

Pricing

$0.40 per secret per month
$0.05 per 10,000 API calls

Cost Saving Tips

Combine related secrets in JSON objects

// Instead of multiple secrets
const dbUser = new Secret(this, "DBUser", { secretName: "db-user" });
const dbPass = new Secret(this, "DBPass", { secretName: "db-pass" });
const dbHost = new Secret(this, "DBHost", { secretName: "db-host" });

// Use one secret with JSON
const dbConfig = new Secret(this, "DBConfig", {
  secretName: "db-config",
  secretObjectValue: {
    username: SecretValue.unsafePlainText("admin"),
    password: SecretValue.unsafePlainText("pass"),
    host: SecretValue.unsafePlainText("db.example.com"),
  },
});

Cache secrets in Lambda functions
Use Parameter Store for non-sensitive config

Security Considerations

Secret Value Security

// Avoid: logs the secret in CloudFormation
const bad = new Secret(this, "Bad", {
  secretStringValue: "my-password", // Visible in templates!
});

// Better: generate the value, or pass it via environment
const good = new Secret(this, "Good", {
  generateSecretString: { passwordLength: 32 },
});

// Best: reference an existing value with SecretValue.ssmSecure
const best = new Secret(this, "Best", {
  secretObjectValue: {
    apiKey: SecretValue.ssmSecure("/myapp/api-key"),
  },
});

Access Patterns

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

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

Troubleshooting

Symptom	Cause and fix
Access denied	Check IAM permissions and resource policies.
Secret not found	Verify the secret name and region.
KMS access error	Grant the principal key-usage permissions on the CMK.
Rotation failures	Check the rotation Lambda function and network access.

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 at runtime.

​Overview

​Resource Class

​Basic Usage

​Simple Secret

​Generated Password

​JSON Secret

​Configuration Options

​Core Properties

​Secret Value Options (use one)

​Default Features

​Generated Passwords

​Basic Password Generation

​Database Password with Username

​API Key Generation

​Import/Export Pattern

​Export for Cross-Stack Usage

​Import Specific Field

​Integration with Resources

​With RDS

​With ECS

​With Lambda

​KMS Encryption

​Default CMK Creation

​Access the CMK

​Secret Rotation

​Enable Rotation

​Factory Pattern

​Using StackBuilder

​IAM Permissions

​Grant Read Access

​Custom Permissions

​Outputs

​Complete Example

​Best Practices

​Cost Optimisation

​Pricing

​Cost Saving Tips

​Security Considerations

​Secret Value Security

​Access Patterns

​Troubleshooting

​Next Steps