cdk-immukv 0.1.22

AWS CDK constructs for ImmuKV - Immutable key-value store using S3 versioning

cdk-immukv

AWS CDK constructs for deploying ImmuKV infrastructure.

Installation

TypeScript/JavaScript

npm install cdk-immukv

Python

pip install cdk-immukv

Usage

Basic Setup

TypeScript

import * as cdk from "aws-cdk-lib";
import { ImmuKV } from "cdk-immukv";

const app = new cdk.App();
const stack = new cdk.Stack(app, "MyStack");

new ImmuKV(stack, "ImmuKV", {
  bucketName: "my-immukv-bucket",
  s3Prefix: "myapp/",
});

Python

import aws_cdk as cdk
from cdk_immukv import ImmuKV

app = cdk.App()
stack = cdk.Stack(app, "MyStack")

ImmuKV(stack, "ImmuKV",
    bucket_name="my-immukv-bucket",
    s3_prefix="myapp/",
)

S3 Event Notifications

You can optionally configure S3 event notifications to trigger when log entries are created. This supports Lambda functions, SNS topics, and SQS queues.

All notification destinations can be configured using the onLogEntryCreated property. Destinations can be in the same stack or different stacks - the Construct pattern handles this cleanly.

TypeScript - Lambda Trigger

import * as cdk from "aws-cdk-lib";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as s3n from "aws-cdk-lib/aws-s3-notifications";
import { ImmuKV } from "cdk-immukv";

const app = new cdk.App();
const stack = new cdk.Stack(app, "MyStack");

// Create a Lambda function
const processorFn = new lambda.Function(stack, "LogProcessor", {
  runtime: lambda.Runtime.PYTHON_3_11,
  handler: "index.handler",
  code: lambda.Code.fromAsset("lambda"),
});

// Configure ImmuKV to trigger the Lambda on log entry creation
new ImmuKV(stack, "ImmuKV", {
  bucketName: "my-immukv-bucket",
  onLogEntryCreated: new s3n.LambdaDestination(processorFn),
});

TypeScript - SNS Topic

import * as cdk from "aws-cdk-lib";
import * as sns from "aws-cdk-lib/aws-sns";
import * as s3n from "aws-cdk-lib/aws-s3-notifications";
import { ImmuKV } from "cdk-immukv";

const app = new cdk.App();
const stack = new cdk.Stack(app, "MyStack");

// Create SNS topic
const topic = new sns.Topic(stack, "LogEntryTopic");

// Configure ImmuKV to publish to SNS on log entry creation
new ImmuKV(stack, "ImmuKV", {
  bucketName: "my-immukv-bucket",
  onLogEntryCreated: new s3n.SnsDestination(topic),
});

TypeScript - SQS Queue

import * as cdk from "aws-cdk-lib";
import * as sqs from "aws-cdk-lib/aws-sqs";
import * as s3n from "aws-cdk-lib/aws-s3-notifications";
import { ImmuKV } from "cdk-immukv";

const app = new cdk.App();
const stack = new cdk.Stack(app, "MyStack");

// Create SQS queue
const queue = new sqs.Queue(stack, "LogEntryQueue");

// Configure ImmuKV to send to SQS on log entry creation
new ImmuKV(stack, "ImmuKV", {
  bucketName: "my-immukv-bucket",
  onLogEntryCreated: new s3n.SqsDestination(queue),
});

Python - Lambda Trigger

import aws_cdk as cdk
from aws_cdk import aws_lambda as lambda_
from aws_cdk.aws_s3_notifications import LambdaDestination
from cdk_immukv import ImmuKV

app = cdk.App()
stack = cdk.Stack(app, "MyStack")

# Create Lambda function
processor_fn = lambda_.Function(stack, "LogProcessor",
    runtime=lambda_.Runtime.PYTHON_3_11,
    handler="index.handler",
    code=lambda_.Code.from_asset("lambda"),
)

# Configure ImmuKV with Lambda trigger
ImmuKV(stack, "ImmuKV",
    bucket_name="my-immukv-bucket",
    on_log_entry_created=LambdaDestination(processor_fn),
)

API

The ImmuKV construct accepts the following properties:

• bucketName (optional): Name for the S3 bucket. If not specified, an auto-generated bucket name will be used.
• s3Prefix (optional): Prefix for S3 keys
• onLogEntryCreated (optional): S3 notification destination for log entry events
• logVersionRetention (optional): Duration to retain old log versions
• logVersionsToRetain (optional): Number of old log versions to retain
• keyVersionRetention (optional): Duration to retain old key object versions
• keyVersionsToRetain (optional): Number of old key versions to retain per key
• useKmsEncryption (optional): Enable KMS encryption instead of S3-managed encryption (default: false)
• oidcProviders (optional): Array of OIDC identity providers for web identity federation. Each provider has an issuerUrl (e.g., 'https://accounts.google.com') and clientIds (audiences to trust). When specified, creates IAM OIDC providers and a federated IAM role.
• oidcReadOnly (optional): Whether federated users get read-only access instead of read-write (default: false)

ImmuKV Class

The ImmuKV construct exposes the following public properties:

• bucket: The S3 bucket used for ImmuKV storage
• readWritePolicy: IAM managed policy for read/write access
• readOnlyPolicy: IAM managed policy for read-only access
• federatedRole (optional): The IAM role for OIDC-federated users, created when oidcProviders is specified

License

MIT