Skip to content
Keyvector
Dev notes

Deploy to your AWS account

deploy/keyvector.yaml creates:

  • the vector bucket and index (optional);
  • a dead-letter queue;
  • the IAM roles;
  • an ECS Fargate service running Keyvector, with the model in the same task when you choose TEI.

Before you start

Section titled “Before you start”

  1. Turn on the table’s change stream with new and old images (see the Quick start).

  2. Push the image to a registry the task can pull from:

    Terminal window
    aws ecr create-repository --repository-name keyvector
    docker build --platform linux/amd64 -t keyvector .
    docker tag keyvector <account>.dkr.ecr.<region>.amazonaws.com/keyvector:0.1.0
    aws ecr get-login-password | docker login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com
    docker push <account>.dkr.ecr.<region>.amazonaws.com/keyvector:0.1.0

  3. Pick subnets that can reach AWS APIs, through a NAT gateway or VPC endpoints for:

    • Keyspaces and Keyspaces Streams
    • DynamoDB, S3 Vectors and SQS
    • CloudWatch Logs and ECR
    • Bedrock, if you use it

    With TEI, the model is downloaded from huggingface.co at start, so the subnets also need internet access. To avoid that, bake the model into your own image.

Create the stack

Section titled “Create the stack”
Terminal window
aws cloudformation deploy \
  --stack-name keyvector-movies \
  --template-file deploy/keyvector.yaml \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
    KeyspaceName=media TableName=movies \
    TextColumns=title,overview MetadataColumns=genre,release_date \
    Embedder=tei EmbedderModel=sentence-transformers/all-MiniLM-L6-v2 Dimensions=384 \
    VectorBucketName=my-vectors VectorIndexName=movies \
    Image=<account>.dkr.ecr.<region>.amazonaws.com/keyvector:0.1.0 \
    VpcId=vpc-... SubnetIds=subnet-...,subnet-...

The vector bucket and index are kept if the stack is deleted. Pass CreateVectorBucket=false or CreateVectorIndex=false to use existing ones.

One-off tasks

Section titled “One-off tasks”

Backfill, redrive and check run as one-off tasks from the same task definition:

Terminal window
aws ecs run-task --cluster keyvector-movies --launch-type FARGATE \
  --task-definition <TaskDefinition output> \
  --network-configuration 'awsvpcConfiguration={subnets=[subnet-...],securityGroups=[<SecurityGroup output>]}' \
  --overrides '{"containerOverrides":[{"name":"keyvector","command":["backfill","--skip-existing"]}]}'

Sizing

Section titled “Sizing”
  • First start: KCL creates its lease tables and an index on them, and assigns no shard until that index is active. That takes about 12 minutes the first time and is immediate after.
  • Workers: KCL spreads the stream’s shards over the tasks. Running more tasks than shards adds nothing.
  • TEI on CPU: all-MiniLM-L6-v2 embeds hundreds of short texts per second per vCPU. For high write rates, run TEI on a GPU and point EmbedderUrl at it.