Celerity Cache

celerity/cache

Spec Version: v2026-02-27-draft Ecosystem Compatibility: v0 (Current) / v1 (Preview)

blueprint transform: celerity-2026-02-27-draft

The celerity/cache resource type defines an in-memory cache for a Celerity application. Celerity supports Redis OSS-compatible in-memory databases and abstracts the difference between single-instance and cluster topologies.

For Celerity applications, using a cache provides:

• Low-latency data access: In-memory caches provide sub-millisecond read and write latency for frequently accessed data.
• Reduced database load: Caching query results, session data or computed values reduces the load on your primary data stores.
• Session management: Caches are commonly used for managing user sessions, rate limiting and temporary state.
• Topology abstraction: Celerity abstracts the difference between single-instance and cluster mode Redis deployments, allowing you to switch between them without application code changes.

Specification

The specification is the structure of the resource definition that comes under the spec field of the resource in a blueprint. The rest of this section lists fields that are available to configure the celerity/cache resource followed by examples of different configurations for the resource and how the cache behaves in target environments along with additional documentation.

name

A unique name to use for the cache. If a name is not provided, a unique name will be generated based on the blueprint that the cache is defined in.

type

string

clusterMode

Whether to deploy the cache as a cluster with multiple shards and replicas, or as a single instance.

Cluster mode provides higher availability and throughput by distributing data across multiple shards. Single-instance mode is simpler and more cost-effective for development and smaller workloads.

The Celerity SDK cache abstraction handles the difference between single-instance and cluster mode connections transparently — your application code does not need to change when switching modes.

✅ Available in v0

type

boolean

default value

false

engineVersion

The Valkey engine version to use for the cache. Valkey is fully compatible with Redis OSS clients.

✅ Available in v0

type

string

default value

8.2

authMode

The authentication method used to connect to the cache at runtime. This determines how handlers obtain credentials when connecting to the cache.

✅ Available in v0 (AWS) / 🚀 Planned for v1 (Google Cloud, Azure)

type

string

allowed values

password | iam

default value

password

Annotations

There are no annotations required for linking other resources to a celerity/cache resource or modifying the behaviour of a cache resource.

linkSelector.byLabel can be used to target caches from other resource types.

Outputs

Outputs are computed values that are accessible via the {resourceName}.spec.* field accessor in a blueprint substitution. For example, if the resource name is sessionCache, the output would be accessible via ${sessionCache.spec.id}.

id

The ID of the created cache in the target environment.

type

string

examples

arn:aws:elasticache:us-east-1:123456789012:replicationgroup:session-cache (AWS)

projects/my-project/locations/us-central1/instances/session-cache (Google Cloud)

/subscriptions/.../resourceGroups/.../providers/Microsoft.Cache/redis/session-cache (Azure)

host

The primary endpoint for the cache. For cluster mode, this is the configuration endpoint.

type

string

port

The port number for the cache connection.

type

number

default value

6379

Data Types

The celerity/cache resource type does not define custom data types in the blueprint specification. Cache data is stored as Redis-compatible key-value pairs using the Redis data type system (strings, lists, sets, sorted sets, hashes, streams).

Linked From

celerity/handler

When a handler links to a cache, the handler will be configured with permissions and environment variables (or secret store entries) that enable it to connect to the cache. The Celerity SDK provides a cache abstraction covering all core Redis data structures and a credentials provider for direct Redis client access.

✅ Available in v0

Read more about Celerity handlers

celerity/vpc

When a VPC links to a cache, the cache will be placed within the VPC's private subnets. Caches require VPC placement for secure network access.

✅ Available in v0

Read more about Celerity VPCs

Links To

The celerity/cache resource type does not link to other resources.

Examples

Minimal Cache

Blueprint Language

version "2025-11-02"
transform "celerity-2026-02-27-draft"

resource sessionCache: celerity/cache {
    metadata {
        displayName = "Session Cache"
    }

    spec {
        name = "sessions"
    }
}

YAML

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    sessionCache:
        type: "celerity/cache"
        metadata:
            displayName: "Session Cache"
        spec:
            name: "sessions"

Cache with VPC and Handler Link

Blueprint Language

version "2025-11-02"
transform "celerity-2026-02-27-draft"

resource appVpc: celerity/vpc {
    metadata {
        displayName = "Application VPC"
        labels = {
            application = "myapp"
        }
    }

    select by label {
        application = "myapp"
    }

    spec {
        preset = "standard"
    }
}

resource sessionCache: celerity/cache {
    metadata {
        displayName = "Session Cache"
        labels = {
            application = "myapp"
        }
    }

    spec {
        name = "sessions"
    }
}

resource getSessionHandler: celerity/handler {
    metadata {
        displayName = "Get Session"
        labels = {
            application = "myapp"
        }
        annotations = {
            "celerity.handler.http" = true,
            "celerity.handler.http.method" = "GET",
            "celerity.handler.http.path" = "/session"
        }
    }

    select by label {
        application = "myapp"
    }

    spec {
        handler = "handlers.getSession"
        runtime = "nodejs24.x"
    }
}

resource api: celerity/api {
    metadata {
        displayName = "API"
        labels = {
            application = "myapp"
        }
    }

    select by label {
        application = "myapp"
    }

    spec {
        protocols = ["http"]
    }
}

YAML

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    appVpc:
        type: "celerity/vpc"
        metadata:
            displayName: "Application VPC"
            labels:
                application: "myapp"
        linkSelector:
            byLabel:
                application: "myapp"
        spec:
            preset: "standard"

    sessionCache:
        type: "celerity/cache"
        metadata:
            displayName: "Session Cache"
            labels:
                application: "myapp"
        spec:
            name: "sessions"

    getSessionHandler:
        type: "celerity/handler"
        metadata:
            displayName: "Get Session"
            labels:
                application: "myapp"
            annotations:
                celerity.handler.http: true
                celerity.handler.http.method: "GET"
                celerity.handler.http.path: "/session"
        linkSelector:
            byLabel:
                application: "myapp"
        spec:
            handler: "handlers.getSession"
            runtime: "nodejs24.x"

    api:
        type: "celerity/api"
        metadata:
            displayName: "API"
            labels:
                application: "myapp"
        linkSelector:
            byLabel:
                application: "myapp"
        spec:
            protocols: ["http"]

Cluster Mode Cache

Blueprint Language

version "2025-11-02"
transform "celerity-2026-02-27-draft"

resource productCache: celerity/cache {
    metadata {
        displayName = "Product Cache"
        labels = {
            application = "catalog"
        }
    }

    spec {
        name = "products"
        clusterMode = true
        engineVersion = "8.0"
    }
}

YAML

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    productCache:
        type: "celerity/cache"
        metadata:
            displayName: "Product Cache"
            labels:
                application: "catalog"
        spec:
            name: "products"
            clusterMode: true
            engineVersion: "8.0"

Cache with IAM Authentication

✅ Available in v0

Blueprint Language

version "2025-11-02"
transform "celerity-2026-02-27-draft"

resource sessionCache: celerity/cache {
    metadata {
        displayName = "Session Cache"
        labels = {
            application = "myapp"
        }
    }

    spec {
        name = "sessions"
        authMode = "iam"
        clusterMode = true
    }
}

YAML

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    sessionCache:
        type: "celerity/cache"
        metadata:
            displayName: "Session Cache"
            labels:
                application: "myapp"
        spec:
            name: "sessions"
            authMode: "iam"
            clusterMode: true

When authMode is set to "iam", handlers that link to this cache are automatically granted the IAM permissions required for token-based cache authentication on the target cloud provider. The SDK generates short-lived tokens at runtime — no static passwords are stored or rotated.

Target Environments

Local Development

✅ Available in v0

In the local development environment, caches are backed by a Valkey instance. The same Valkey instance is shared across cache resources and config stores in the local development environment, with namespace isolation to prevent key collisions.

When celerity dev run starts, cache resources are automatically available and connection configuration is injected into your handlers.

AWS

✅ Available in v0

In the AWS environment, caches are backed by Amazon ElastiCache for Redis.

Single Instance Mode

A single ElastiCache replication group with one primary node. Suitable for development, staging and workloads that do not require high availability.

Cluster Mode

An ElastiCache replication group with cluster mode enabled, distributing data across multiple shards with automatic failover. Suitable for production workloads requiring high availability and throughput.

Networking

Caches are placed within the VPC's private subnets when linked to a celerity/vpc resource. Security groups are configured to allow traffic from Lambda functions (or ECS/EKS tasks) to the cache port.

The app deploy configuration can be used to configure the cache with Amazon ElastiCache specific settings such as node type, number of replicas and encryption at rest.

IAM Authentication

✅ Available in v0

When authMode is set to "iam", Celerity enables IAM Authentication on the ElastiCache replication group. An IAM-enabled ElastiCache user is created with the appropriate access string, and the handler's execution role (Lambda or ECS task role) is granted the elasticache:Connect permission scoped to the cache resource and user. The SDK generates short-lived authentication tokens via SigV4 presigned requests at runtime instead of using a static AUTH token.

IAM authentication is supported for both single-instance and cluster mode configurations. Transit encryption (TLS) is always enabled on the replication group: both authMode values require it, so it is not configurable.

Google Cloud

🚀 Planned for v1 - The Google Cloud deployment target is planned for v1, it may become available in a future v0 evolution.

Caches will be provisioned using Google Cloud Memorystore for Valkey.

When authMode is set to "iam", Celerity enables IAM Authentication on the Memorystore instance. The handler's service account is granted the necessary Memorystore IAM roles. The SDK uses OAuth2 access tokens for authentication at runtime.

Azure

🚀 Planned for v1 - The Azure deployment target is planned for v1, it may become available in a future v0 evolution.

Caches will be provisioned using Azure Cache for Redis.

When authMode is set to "iam", Celerity enables Entra ID Authentication on the Azure Cache for Redis instance. The handler's managed identity is granted cache access, and the SDK fetches access tokens from Entra ID at runtime.

App Deploy Configuration

Configuration specific to a target environment can be defined for celerity/cache resources in the app deploy configuration file.

This section lists the configuration options that can be set in the deployTarget.config object in the app deploy configuration file.

AWS Configuration Options

✅ Available in v0

aws.elasticache.<cacheName>.nodeType

The ElastiCache node type to use for the cache. This determines the compute and memory capacity of each cache node. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

string

default value

cache.t3.micro

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.nodeType": "cache.r6g.large"
        }
    }
}

aws.elasticache.<cacheName>.numReplicas

The number of read replicas per shard. In single-instance mode, this creates replicas of the primary node. In cluster mode, this creates replicas per shard. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

number

default value

0 (single-instance mode) / 1 (cluster mode)

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.numReplicas": 2
        }
    }
}

aws.elasticache.<cacheName>.numShards

The number of shards in the cluster. Only applicable when clusterMode is true. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

number

default value

3

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.numShards": 3
        }
    }
}

aws.elasticache.<cacheName>.automaticFailover

Whether to enable automatic failover for the replication group. Requires at least one replica. Automatically enabled when clusterMode is true. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

boolean

default value

false (single-instance mode) / true (cluster mode)

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.automaticFailover": true
        }
    }
}

aws.elasticache.<cacheName>.atRestEncryption

Whether to enable encryption at rest for the cache. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

boolean

default value

true

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.atRestEncryption": true
        }
    }
}

aws.elasticache.<cacheName>.snapshotRetentionDays

The number of days to retain automatic snapshots (backups) of the cache. Set to 0 to disable automatic snapshots. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

number

default value

0

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.snapshotRetentionDays": 7
        }
    }
}

aws.elasticache.<cacheName>.evictionPolicy

The eviction policy to use when the cache reaches its memory limit. This maps to the Redis maxmemory-policy configuration parameter. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

string

allowed values

allkeys-lru, allkeys-lfu, allkeys-random, volatile-lru, volatile-lfu, volatile-random, volatile-ttl, noeviction

default value

allkeys-lru

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.evictionPolicy": "volatile-ttl"
        }
    }
}

Google Cloud Configuration Options

🚀 Planned for v1 - The Google Cloud deployment targets are planned for v1, they may become available in a future v0 evolution.

Azure Configuration Options

🚀 Planned for v1 - The Azure deployment targets are planned for v1, they may become available in a future v0 evolution.

SDK Operations

The Celerity SDKs provide a cache abstraction covering all five core Redis data structures - strings (key-value), hashes, lists, sets and sorted sets. The full contract, covering every operation, cluster-mode behaviour, transactions and the credentials provider for direct client access, is specified in Cache SDK Operations.

In outline:

• Key-value: get, set with a TTL and conditional flags, delete, ttl, getSet, append, and the mget / mset / mdelete batch forms.
• Key management: exists, expire, persist, type, rename and scan.
• Counters: incr, decr and incrFloat, applied by the cache rather than by the handler.
• Structures: hashes, lists, sets and sorted sets, each with the operations the structure is worth using for.
• Transactions: a group of writes applied as one, queued through a builder.
• Credentials provider: connection details for your own client, which is how pub/sub, streams, WATCH and Lua scripting are reached.

The abstraction handles connection setup and routes single-key operations in both single-instance and cluster mode. Multi-key operations in cluster mode depend on keys sharing a hash slot; see Cluster mode.

For language-specific documentation, see Node.js SDK - Cache, Python SDK - Cache and Go SDK - Cache.