@aws-cdk/aws-elasticache-alpha

ElastiCache CDK Construct Library

Version 2.273.0-alpha.0

Separate package

@aws-cdk/aws-elasticache-alpha is not part of aws-cdk-lib — install it separately:

npm install @aws-cdk/aws-elasticache-alpha
pip install aws-cdk.aws-elasticache-alpha

This module is experimental (alpha): its API may change in any release, without a major version bump.

---

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

---

This module has constructs for Amazon ElastiCache.

• The ServerlessCache construct facilitates the creation and management of serverless cache.
• The User and UserGroup constructs facilitate the creation and management of users for the cache.

Serverless Cache

Amazon ElastiCache Serverless is a serverless option that automatically scales cache capacity based on application traffic patterns. You can create a serverless cache using the ServerlessCache construct:

const vpc = new ec2.Vpc(this, 'VPC');

const cache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  vpc,
});

vpc = ec2.Vpc(self, "VPC")

cache = elasticache.ServerlessCache(self, "ServerlessCache",
    vpc=vpc
)

Vpc vpc = new Vpc(this, "VPC");

ServerlessCache cache = ServerlessCache.Builder.create(this, "ServerlessCache")
        .vpc(vpc)
        .build();

var vpc = new Vpc(this, "VPC");

var cache = new ServerlessCache(this, "ServerlessCache", new ServerlessCacheProps {
    Vpc = vpc
});

vpc := ec2.NewVpc(this, jsii.String("VPC"))

cache := elasticache.NewServerlessCache(this, jsii.String("ServerlessCache"), &ServerlessCacheProps{
	Vpc: Vpc,
})

Connecting to serverless cache

To control who can access the serverless cache by the security groups, use the .connections attribute.

The serverless cache has a default port 6379.

This example allows an EC2 instance to connect to the serverless cache:

declare const serverlessCache: elasticache.ServerlessCache;
declare const instance: ec2.Instance;

// allow the EC2 instance to connect to serverless cache on default port 6379
serverlessCache.connections.allowDefaultPortFrom(instance);

# serverless_cache: elasticache.ServerlessCache
# instance: ec2.Instance


# allow the EC2 instance to connect to serverless cache on default port 6379
serverless_cache.connections.allow_default_port_from(instance)

ServerlessCache serverlessCache;
Instance instance;


// allow the EC2 instance to connect to serverless cache on default port 6379
serverlessCache.connections.allowDefaultPortFrom(instance);

ServerlessCache serverlessCache;
Instance instance;


// allow the EC2 instance to connect to serverless cache on default port 6379
serverlessCache.Connections.AllowDefaultPortFrom(instance);

var serverlessCache ServerlessCache
var instance Instance


// allow the EC2 instance to connect to serverless cache on default port 6379
serverlessCache.Connections.AllowDefaultPortFrom(instance)

Using a custom engine version

The named CacheEngine and UserEngine static members cover the versions available at the time of the most recent CDK release. If ElastiCache releases a new engine version before it is added as a named member, use the .of(...) factory to target it without waiting for a CDK update:

declare const vpc: ec2.Vpc;

new elasticache.ServerlessCache(this, 'ServerlessCache', {
  // Use any engine/version combination supported by ElastiCache:
  engine: elasticache.CacheEngine.of('valkey', '9'),
  vpc,
});

# vpc: ec2.Vpc


elasticache.ServerlessCache(self, "ServerlessCache",
    # Use any engine/version combination supported by ElastiCache:
    engine=elasticache.CacheEngine.of("valkey", "9"),
    vpc=vpc
)

Vpc vpc;


ServerlessCache.Builder.create(this, "ServerlessCache")
        // Use any engine/version combination supported by ElastiCache:
        .engine(CacheEngine.of("valkey", "9"))
        .vpc(vpc)
        .build();

Vpc vpc;


new ServerlessCache(this, "ServerlessCache", new ServerlessCacheProps {
    // Use any engine/version combination supported by ElastiCache:
    Engine = CacheEngine.Of("valkey", "9"),
    Vpc = vpc
});

var vpc Vpc


elasticache.NewServerlessCache(this, jsii.String("ServerlessCache"), &ServerlessCacheProps{
	// Use any engine/version combination supported by ElastiCache:
	Engine: elasticache.CacheEngine_Of(jsii.String("valkey"), jsii.String("9")),
	Vpc: Vpc,
})

The same pattern applies to UserEngine.of(engineType) for users and user groups.

Cache usage limits

You can configure usage limits on both cache data storage and ECPU/second for your cache to control costs and ensure predictable performance.

Configuration options:

• Maximum limits: Ensure your cache usage never exceeds the configured maximum
• Minimum limits: Reserve a baseline level of resources for consistent performance
• Both: Define a range where your cache usage will operate

For more infomation, see Setting scaling limits to manage costs.

declare const vpc: ec2.Vpc;

const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  vpc,
  cacheUsageLimits: {
    // cache data storage limits (GB)
    dataStorageMinimumSize: Size.gibibytes(2), // minimum: 1GB
    dataStorageMaximumSize: Size.gibibytes(3), // maximum: 5000GB
    // rate limits (ECPU/second)
    requestRateLimitMinimum: 1000, // minimum: 1000
    requestRateLimitMaximum: 10000, // maximum: 15000000
  },
});

# vpc: ec2.Vpc


serverless_cache = elasticache.ServerlessCache(self, "ServerlessCache",
    engine=elasticache.CacheEngine.VALKEY_LATEST,
    vpc=vpc,
    cache_usage_limits=elasticache.CacheUsageLimitsProperty(
        # cache data storage limits (GB)
        data_storage_minimum_size=Size.gibibytes(2),  # minimum: 1GB
        data_storage_maximum_size=Size.gibibytes(3),  # maximum: 5000GB
        # rate limits (ECPU/second)
        request_rate_limit_minimum=1000,  # minimum: 1000
        request_rate_limit_maximum=10000
    )
)

Vpc vpc;


ServerlessCache serverlessCache = ServerlessCache.Builder.create(this, "ServerlessCache")
        .engine(CacheEngine.VALKEY_LATEST)
        .vpc(vpc)
        .cacheUsageLimits(CacheUsageLimitsProperty.builder()
                // cache data storage limits (GB)
                .dataStorageMinimumSize(Size.gibibytes(2)) // minimum: 1GB
                .dataStorageMaximumSize(Size.gibibytes(3)) // maximum: 5000GB
                // rate limits (ECPU/second)
                .requestRateLimitMinimum(1000) // minimum: 1000
                .requestRateLimitMaximum(10000)
                .build())
        .build();

Vpc vpc;


var serverlessCache = new ServerlessCache(this, "ServerlessCache", new ServerlessCacheProps {
    Engine = CacheEngine.VALKEY_LATEST,
    Vpc = vpc,
    CacheUsageLimits = new CacheUsageLimitsProperty {
        // cache data storage limits (GB)
        DataStorageMinimumSize = Size.Gibibytes(2),  // minimum: 1GB
        DataStorageMaximumSize = Size.Gibibytes(3),  // maximum: 5000GB
        // rate limits (ECPU/second)
        RequestRateLimitMinimum = 1000,  // minimum: 1000
        RequestRateLimitMaximum = 10000
    }
});

var vpc Vpc


serverlessCache := elasticache.NewServerlessCache(this, jsii.String("ServerlessCache"), &ServerlessCacheProps{
	Engine: elasticache.CacheEngine_VALKEY_LATEST(),
	Vpc: Vpc,
	CacheUsageLimits: &CacheUsageLimitsProperty{
		// cache data storage limits (GB)
		DataStorageMinimumSize: awscdk.Size_Gibibytes(jsii.Number(2)),
		 // minimum: 1GB
		DataStorageMaximumSize: awscdk.Size_*Gibibytes(jsii.Number(3)),
		 // maximum: 5000GB
		// rate limits (ECPU/second)
		RequestRateLimitMinimum: jsii.Number(1000),
		 // minimum: 1000
		RequestRateLimitMaximum: jsii.Number(10000),
	},
})

Backups and restore

You can enable automatic backups for serverless cache. When automatic backups are enabled, ElastiCache creates a backup of the cache on a daily basis.

Also you can set the backup window for any time when it's most convenient. If you don't specify a backup window, ElastiCache assigns one automatically.

For more information, see Scheduling automatic backups.

To enable automatic backups, set the backupRetentionLimit property. You can also specify the snapshot creation time by setting backupTime property:

declare const vpc: ec2.Vpc;

const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  backup: {
    // enable automatic backups and set the retention period to 6 days
    backupRetentionLimit: 6,
    // set the backup window to 9:00 AM UTC
    backupTime: events.Schedule.cron({
      hour: '9',
      minute: '0',
    }),
  },
  vpc,
});

# vpc: ec2.Vpc


serverless_cache = elasticache.ServerlessCache(self, "ServerlessCache",
    backup=elasticache.BackupSettings(
        # enable automatic backups and set the retention period to 6 days
        backup_retention_limit=6,
        # set the backup window to 9:00 AM UTC
        backup_time=events.Schedule.cron(
            hour="9",
            minute="0"
        )
    ),
    vpc=vpc
)

Vpc vpc;


ServerlessCache serverlessCache = ServerlessCache.Builder.create(this, "ServerlessCache")
        .backup(BackupSettings.builder()
                // enable automatic backups and set the retention period to 6 days
                .backupRetentionLimit(6)
                // set the backup window to 9:00 AM UTC
                .backupTime(Schedule.cron(CronOptions.builder()
                        .hour("9")
                        .minute("0")
                        .build()))
                .build())
        .vpc(vpc)
        .build();

Vpc vpc;


var serverlessCache = new ServerlessCache(this, "ServerlessCache", new ServerlessCacheProps {
    Backup = new BackupSettings {
        // enable automatic backups and set the retention period to 6 days
        BackupRetentionLimit = 6,
        // set the backup window to 9:00 AM UTC
        BackupTime = Schedule.Cron(new CronOptions {
            Hour = "9",
            Minute = "0"
        })
    },
    Vpc = vpc
});

var vpc Vpc


serverlessCache := elasticache.NewServerlessCache(this, jsii.String("ServerlessCache"), &ServerlessCacheProps{
	Backup: &BackupSettings{
		// enable automatic backups and set the retention period to 6 days
		BackupRetentionLimit: jsii.Number(6),
		// set the backup window to 9:00 AM UTC
		BackupTime: events.Schedule_Cron(&CronOptions{
			Hour: jsii.String("9"),
			Minute: jsii.String("0"),
		}),
	},
	Vpc: Vpc,
})

You can create a final backup by setting backupNameBeforeDeletion property.

declare const vpc: ec2.Vpc;

const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  backup: {
    // set a backup name before deleting a cache
    backupNameBeforeDeletion: "my-final-backup-name",
  },
  vpc,
});

# vpc: ec2.Vpc


serverless_cache = elasticache.ServerlessCache(self, "ServerlessCache",
    engine=elasticache.CacheEngine.VALKEY_LATEST,
    backup=elasticache.BackupSettings(
        # set a backup name before deleting a cache
        backup_name_before_deletion="my-final-backup-name"
    ),
    vpc=vpc
)

Vpc vpc;


ServerlessCache serverlessCache = ServerlessCache.Builder.create(this, "ServerlessCache")
        .engine(CacheEngine.VALKEY_LATEST)
        .backup(BackupSettings.builder()
                // set a backup name before deleting a cache
                .backupNameBeforeDeletion("my-final-backup-name")
                .build())
        .vpc(vpc)
        .build();

Vpc vpc;


var serverlessCache = new ServerlessCache(this, "ServerlessCache", new ServerlessCacheProps {
    Engine = CacheEngine.VALKEY_LATEST,
    Backup = new BackupSettings {
        // set a backup name before deleting a cache
        BackupNameBeforeDeletion = "my-final-backup-name"
    },
    Vpc = vpc
});

var vpc Vpc


serverlessCache := elasticache.NewServerlessCache(this, jsii.String("ServerlessCache"), &ServerlessCacheProps{
	Engine: elasticache.CacheEngine_VALKEY_LATEST(),
	Backup: &BackupSettings{
		// set a backup name before deleting a cache
		BackupNameBeforeDeletion: jsii.String("my-final-backup-name"),
	},
	Vpc: Vpc,
})

You can restore from backups by setting snapshot ARNs to backupArnsToRestore property:

declare const vpc: ec2.Vpc;

const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  backup: {
    // set the backup(s) to restore
    backupArnsToRestore: ['arn:aws:elasticache:us-east-1:123456789012:serverlesscachesnapshot:my-final-backup-name'],
  },
  vpc,
});

# vpc: ec2.Vpc


serverless_cache = elasticache.ServerlessCache(self, "ServerlessCache",
    engine=elasticache.CacheEngine.VALKEY_LATEST,
    backup=elasticache.BackupSettings(
        # set the backup(s) to restore
        backup_arns_to_restore=["arn:aws:elasticache:us-east-1:123456789012:serverlesscachesnapshot:my-final-backup-name"]
    ),
    vpc=vpc
)

Vpc vpc;


ServerlessCache serverlessCache = ServerlessCache.Builder.create(this, "ServerlessCache")
        .engine(CacheEngine.VALKEY_LATEST)
        .backup(BackupSettings.builder()
                // set the backup(s) to restore
                .backupArnsToRestore(List.of("arn:aws:elasticache:us-east-1:123456789012:serverlesscachesnapshot:my-final-backup-name"))
                .build())
        .vpc(vpc)
        .build();

Vpc vpc;


var serverlessCache = new ServerlessCache(this, "ServerlessCache", new ServerlessCacheProps {
    Engine = CacheEngine.VALKEY_LATEST,
    Backup = new BackupSettings {
        // set the backup(s) to restore
        BackupArnsToRestore = new [] { "arn:aws:elasticache:us-east-1:123456789012:serverlesscachesnapshot:my-final-backup-name" }
    },
    Vpc = vpc
});

var vpc Vpc


serverlessCache := elasticache.NewServerlessCache(this, jsii.String("ServerlessCache"), &ServerlessCacheProps{
	Engine: elasticache.CacheEngine_VALKEY_LATEST(),
	Backup: &BackupSettings{
		// set the backup(s) to restore
		BackupArnsToRestore: []*string{
			jsii.String("arn:aws:elasticache:us-east-1:123456789012:serverlesscachesnapshot:my-final-backup-name"),
		},
	},
	Vpc: Vpc,
})

Encryption at rest

At-rest encryption is always enabled for Serverless Cache. There are two encryption options:

• Default: When no kmsKey is specified (left as undefined), AWS owned KMS keys are used automatically
• Customer Managed Key: Create a KMS key first, then pass it to the cache via the kmsKey property

Customer Managed Key for encryption at rest

ElastiCache supports symmetric Customer Managed key (CMK) for encryption at rest.

For more information, see Using customer managed keys from AWS KMS.

To use CMK, set your CMK to the kmsKey property:

import { Key } from 'aws-cdk-lib/aws-kms';

declare const kmsKey: Key;
declare const vpc: ec2.Vpc;

const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  serverlessCacheName: 'my-serverless-cache',
  vpc,
  // set Customer Managed Key
  kmsKey,
});

from aws_cdk.aws_kms import Key

# kms_key: Key
# vpc: ec2.Vpc


serverless_cache = elasticache.ServerlessCache(self, "ServerlessCache",
    engine=elasticache.CacheEngine.VALKEY_LATEST,
    serverless_cache_name="my-serverless-cache",
    vpc=vpc,
    # set Customer Managed Key
    kms_key=kms_key
)

import software.amazon.awscdk.services.kms.Key;

Key kmsKey;
Vpc vpc;


ServerlessCache serverlessCache = ServerlessCache.Builder.create(this, "ServerlessCache")
        .engine(CacheEngine.VALKEY_LATEST)
        .serverlessCacheName("my-serverless-cache")
        .vpc(vpc)
        // set Customer Managed Key
        .kmsKey(kmsKey)
        .build();

using Amazon.CDK.AWS.KMS;

Key kmsKey;
Vpc vpc;


var serverlessCache = new ServerlessCache(this, "ServerlessCache", new ServerlessCacheProps {
    Engine = CacheEngine.VALKEY_LATEST,
    ServerlessCacheName = "my-serverless-cache",
    Vpc = vpc,
    // set Customer Managed Key
    KmsKey = kmsKey
});

import "github.com/aws/aws-cdk-go/awscdk"

var kmsKey Key
var vpc Vpc


serverlessCache := elasticache.NewServerlessCache(this, jsii.String("ServerlessCache"), &ServerlessCacheProps{
	Engine: elasticache.CacheEngine_VALKEY_LATEST(),
	ServerlessCacheName: jsii.String("my-serverless-cache"),
	Vpc: Vpc,
	// set Customer Managed Key
	KmsKey: KmsKey,
})

Metrics and monitoring

You can monitor your serverless cache using CloudWatch Metrics via the metric method.

For more information about serverless cache metrics, see Serverless metrics and events for Valkey and Redis OSS and Serverless metrics and events for Memcached.

declare const serverlessCache: elasticache.ServerlessCache;

// The 5 minutes average of the total number of successful read-only key lookups in the cache.
const cacheHits = serverlessCache.metricCacheHitCount();

// The 5 minutes average of the total number of bytes used by the data stored in the cache.
const bytesUsedForCache = serverlessCache.metricDataStored();

// The 5 minutes average of the total number of ElastiCacheProcessingUnits (ECPUs) consumed by the requests executed on the cache.
const elastiCacheProcessingUnits = serverlessCache.metricProcessingUnitsConsumed();

// Create an alarm for ECPUs.
elastiCacheProcessingUnits.createAlarm(this, 'ElastiCacheProcessingUnitsAlarm', {
  threshold: 50,
  evaluationPeriods: 1,
});

# serverless_cache: elasticache.ServerlessCache


# The 5 minutes average of the total number of successful read-only key lookups in the cache.
cache_hits = serverless_cache.metric_cache_hit_count()

# The 5 minutes average of the total number of bytes used by the data stored in the cache.
bytes_used_for_cache = serverless_cache.metric_data_stored()

# The 5 minutes average of the total number of ElastiCacheProcessingUnits (ECPUs) consumed by the requests executed on the cache.
elasti_cache_processing_units = serverless_cache.metric_processing_units_consumed()

# Create an alarm for ECPUs.
elasti_cache_processing_units.create_alarm(self, "ElastiCacheProcessingUnitsAlarm",
    threshold=50,
    evaluation_periods=1
)

ServerlessCache serverlessCache;


// The 5 minutes average of the total number of successful read-only key lookups in the cache.
Metric cacheHits = serverlessCache.metricCacheHitCount();

// The 5 minutes average of the total number of bytes used by the data stored in the cache.
Metric bytesUsedForCache = serverlessCache.metricDataStored();

// The 5 minutes average of the total number of ElastiCacheProcessingUnits (ECPUs) consumed by the requests executed on the cache.
Metric elastiCacheProcessingUnits = serverlessCache.metricProcessingUnitsConsumed();

// Create an alarm for ECPUs.
elastiCacheProcessingUnits.createAlarm(this, "ElastiCacheProcessingUnitsAlarm", CreateAlarmOptions.builder()
        .threshold(50)
        .evaluationPeriods(1)
        .build());

ServerlessCache serverlessCache;


// The 5 minutes average of the total number of successful read-only key lookups in the cache.
var cacheHits = serverlessCache.MetricCacheHitCount();

// The 5 minutes average of the total number of bytes used by the data stored in the cache.
var bytesUsedForCache = serverlessCache.MetricDataStored();

// The 5 minutes average of the total number of ElastiCacheProcessingUnits (ECPUs) consumed by the requests executed on the cache.
var elastiCacheProcessingUnits = serverlessCache.MetricProcessingUnitsConsumed();

// Create an alarm for ECPUs.
elastiCacheProcessingUnits.CreateAlarm(this, "ElastiCacheProcessingUnitsAlarm", new CreateAlarmOptions {
    Threshold = 50,
    EvaluationPeriods = 1
});

var serverlessCache ServerlessCache


// The 5 minutes average of the total number of successful read-only key lookups in the cache.
cacheHits := serverlessCache.MetricCacheHitCount()

// The 5 minutes average of the total number of bytes used by the data stored in the cache.
bytesUsedForCache := serverlessCache.MetricDataStored()

// The 5 minutes average of the total number of ElastiCacheProcessingUnits (ECPUs) consumed by the requests executed on the cache.
elastiCacheProcessingUnits := serverlessCache.MetricProcessingUnitsConsumed()

// Create an alarm for ECPUs.
elastiCacheProcessingUnits.CreateAlarm(this, jsii.String("ElastiCacheProcessingUnitsAlarm"), &CreateAlarmOptions{
	Threshold: jsii.Number(50),
	EvaluationPeriods: jsii.Number(1),
})

Import an existing serverless cache

To import an existing ServerlessCache, use the ServerlessCache.fromServerlessCacheAttributes method:

declare const securityGroup: ec2.SecurityGroup;

const importedServerlessCache = elasticache.ServerlessCache.fromServerlessCacheAttributes(this, 'ImportedServerlessCache', {
  serverlessCacheName: 'my-serverless-cache',
  securityGroups: [securityGroup],
});

# security_group: ec2.SecurityGroup


imported_serverless_cache = elasticache.ServerlessCache.from_serverless_cache_attributes(self, "ImportedServerlessCache",
    serverless_cache_name="my-serverless-cache",
    security_groups=[security_group]
)

SecurityGroup securityGroup;


IServerlessCache importedServerlessCache = ServerlessCache.fromServerlessCacheAttributes(this, "ImportedServerlessCache", ServerlessCacheAttributes.builder()
        .serverlessCacheName("my-serverless-cache")
        .securityGroups(List.of(securityGroup))
        .build());

SecurityGroup securityGroup;


var importedServerlessCache = ServerlessCache.FromServerlessCacheAttributes(this, "ImportedServerlessCache", new ServerlessCacheAttributes {
    ServerlessCacheName = "my-serverless-cache",
    SecurityGroups = new [] { securityGroup }
});

var securityGroup SecurityGroup


importedServerlessCache := elasticache.ServerlessCache_FromServerlessCacheAttributes(this, jsii.String("ImportedServerlessCache"), &ServerlessCacheAttributes{
	ServerlessCacheName: jsii.String("my-serverless-cache"),
	SecurityGroups: []ISecurityGroup{
		securityGroup,
	},
})

User and User Group

Setup required properties and create:

const newDefaultUser = new elasticache.NoPasswordUser(this, 'NoPasswordUser', {
  userId: 'default',
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),
})

const userGroup = new elasticache.UserGroup(this, 'UserGroup', {
  users: [newDefaultUser],
});

new_default_user = elasticache.NoPasswordUser(self, "NoPasswordUser",
    user_id="default",
    access_control=elasticache.AccessControl.from_access_string("on ~* +@all")
)

user_group = elasticache.UserGroup(self, "UserGroup",
    users=[new_default_user]
)

NoPasswordUser newDefaultUser = NoPasswordUser.Builder.create(this, "NoPasswordUser")
        .userId("default")
        .accessControl(AccessControl.fromAccessString("on ~* +@all"))
        .build();

UserGroup userGroup = UserGroup.Builder.create(this, "UserGroup")
        .users(List.of(newDefaultUser))
        .build();

var newDefaultUser = new NoPasswordUser(this, "NoPasswordUser", new NoPasswordUserProps {
    UserId = "default",
    AccessControl = AccessControl.FromAccessString("on ~* +@all")
});

var userGroup = new UserGroup(this, "UserGroup", new UserGroupProps {
    Users = new [] { newDefaultUser }
});

newDefaultUser := elasticache.NewNoPasswordUser(this, jsii.String("NoPasswordUser"), &NoPasswordUserProps{
	UserId: jsii.String("default"),
	AccessControl: elasticache.AccessControl_FromAccessString(jsii.String("on ~* +@all")),
})

userGroup := elasticache.NewUserGroup(this, jsii.String("UserGroup"), &UserGroupProps{
	Users: []IUser{
		newDefaultUser,
	},
})

RBAC

In Valkey 7.2 and onward and Redis OSS 6.0 onward you can use a feature called Role-Based Access Control (RBAC). RBAC is also the only way to control access to serverless caches.

RBAC enables you to control cache access through user groups. These user groups are designed as a way to organize access to caches.

For more information, see Role-Based Access Control (RBAC).

To enable RBAC for ElastiCache with Valkey or Redis OSS, you take the following steps:

• Create users.
• Create a user group and add users to the user group.
• Assign the user group to a cache.

Create users

First, you need to create users by using IamUser, PasswordUser or NoPasswordUser construct.

With RBAC, you create users and assign them specific permissions by using accessString property.

For more information, see Specifying Permissions Using an Access String.

You can create an IAM-enabled user by using IamUser construct:

const user = new elasticache.IamUser(this, 'User', {
  // set user engine
  engine: elasticache.UserEngine.REDIS,

  // set user id
  userId: 'my-user',

  // set username
  userName: 'my-user',

  // set access string
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),
});

user = elasticache.IamUser(self, "User",
    # set user engine
    engine=elasticache.UserEngine.REDIS,

    # set user id
    user_id="my-user",

    # set username
    user_name="my-user",

    # set access string
    access_control=elasticache.AccessControl.from_access_string("on ~* +@all")
)

IamUser user = IamUser.Builder.create(this, "User")
        // set user engine
        .engine(UserEngine.REDIS)

        // set user id
        .userId("my-user")

        // set username
        .userName("my-user")

        // set access string
        .accessControl(AccessControl.fromAccessString("on ~* +@all"))
        .build();

var user = new IamUser(this, "User", new IamUserProps {
    // set user engine
    Engine = UserEngine.REDIS,

    // set user id
    UserId = "my-user",

    // set username
    UserName = "my-user",

    // set access string
    AccessControl = AccessControl.FromAccessString("on ~* +@all")
});

user := elasticache.NewIamUser(this, jsii.String("User"), &IamUserProps{
	// set user engine
	Engine: elasticache.UserEngine_REDIS(),

	// set user id
	UserId: jsii.String("my-user"),

	// set username
	UserName: jsii.String("my-user"),

	// set access string
	AccessControl: elasticache.AccessControl_FromAccessString(jsii.String("on ~* +@all")),
})

NOTE: IAM-enabled users must have matching user id and username. For more information, see Limitations. The construct can set automatically the username to be the same as the user id.

If you want to create a password authenticated user, use PasswordUser construct:

const user = new elasticache.PasswordUser(this, 'User', {
  // set user engine
  engine: elasticache.UserEngine.VALKEY,

  // set user id
  userId: 'my-user-id',

  // set access string
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),

  // set username
  userName: 'my-user-name',

  // set up to two passwords
  passwords: [
    // "SecretIdForPassword" is the secret id for the password
    SecretValue.secretsManager('SecretIdForPassword'),
    // "AnotherSecretIdForPassword" is the secret id for the password
    SecretValue.secretsManager('AnotherSecretIdForPassword'),
  ],
});

user = elasticache.PasswordUser(self, "User",
    # set user engine
    engine=elasticache.UserEngine.VALKEY,

    # set user id
    user_id="my-user-id",

    # set access string
    access_control=elasticache.AccessControl.from_access_string("on ~* +@all"),

    # set username
    user_name="my-user-name",

    # set up to two passwords
    passwords=[
        # "SecretIdForPassword" is the secret id for the password
        SecretValue.secrets_manager("SecretIdForPassword"),
        # "AnotherSecretIdForPassword" is the secret id for the password
        SecretValue.secrets_manager("AnotherSecretIdForPassword")
    ]
)

PasswordUser user = PasswordUser.Builder.create(this, "User")
        // set user engine
        .engine(UserEngine.VALKEY)

        // set user id
        .userId("my-user-id")

        // set access string
        .accessControl(AccessControl.fromAccessString("on ~* +@all"))

        // set username
        .userName("my-user-name")

        // set up to two passwords
        .passwords(List.of(SecretValue.secretsManager("SecretIdForPassword"), SecretValue.secretsManager("AnotherSecretIdForPassword")))
        .build();

var user = new PasswordUser(this, "User", new PasswordUserProps {
    // set user engine
    Engine = UserEngine.VALKEY,

    // set user id
    UserId = "my-user-id",

    // set access string
    AccessControl = AccessControl.FromAccessString("on ~* +@all"),

    // set username
    UserName = "my-user-name",

    // set up to two passwords
    Passwords = new [] { SecretValue.SecretsManager("SecretIdForPassword"), SecretValue.SecretsManager("AnotherSecretIdForPassword") }
});

user := elasticache.NewPasswordUser(this, jsii.String("User"), &PasswordUserProps{
	// set user engine
	Engine: elasticache.UserEngine_VALKEY(),

	// set user id
	UserId: jsii.String("my-user-id"),

	// set access string
	AccessControl: elasticache.AccessControl_FromAccessString(jsii.String("on ~* +@all")),

	// set username
	UserName: jsii.String("my-user-name"),

	// set up to two passwords
	Passwords: []SecretValue{
		awscdk.SecretValue_SecretsManager(jsii.String("SecretIdForPassword")),
		awscdk.SecretValue_*SecretsManager(jsii.String("AnotherSecretIdForPassword")),
	},
})

You can also create a no password required user by using NoPasswordUser construct:

const user = new elasticache.NoPasswordUser(this, 'User', {
  // set user engine
  engine: elasticache.UserEngine.REDIS,

  // set user id
  userId: 'my-user-id',

  // set access string
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),

  // set username
  userName: 'my-user-name',
});

user = elasticache.NoPasswordUser(self, "User",
    # set user engine
    engine=elasticache.UserEngine.REDIS,

    # set user id
    user_id="my-user-id",

    # set access string
    access_control=elasticache.AccessControl.from_access_string("on ~* +@all"),

    # set username
    user_name="my-user-name"
)

NoPasswordUser user = NoPasswordUser.Builder.create(this, "User")
        // set user engine
        .engine(UserEngine.REDIS)

        // set user id
        .userId("my-user-id")

        // set access string
        .accessControl(AccessControl.fromAccessString("on ~* +@all"))

        // set username
        .userName("my-user-name")
        .build();

var user = new NoPasswordUser(this, "User", new NoPasswordUserProps {
    // set user engine
    Engine = UserEngine.REDIS,

    // set user id
    UserId = "my-user-id",

    // set access string
    AccessControl = AccessControl.FromAccessString("on ~* +@all"),

    // set username
    UserName = "my-user-name"
});

user := elasticache.NewNoPasswordUser(this, jsii.String("User"), &NoPasswordUserProps{
	// set user engine
	Engine: elasticache.UserEngine_REDIS(),

	// set user id
	UserId: jsii.String("my-user-id"),

	// set access string
	AccessControl: elasticache.AccessControl_FromAccessString(jsii.String("on ~* +@all")),

	// set username
	UserName: jsii.String("my-user-name"),
})

NOTE: NoPasswordUser is only available for Redis Cache.

Default user

ElastiCache automatically creates a default user with both a user ID and username set to default. This default user cannot be modified or deleted. The user is created as a no password authentication user.

This user is intended for compatibility with the default behavior of previous Redis OSS versions and has an access string that permits it to call all commands and access all keys.

To use this automatically created default user in CDK, you can import it using NoPasswordUser.fromUserAttributes method. For more information on import methods, see the Import an existing user and user group section.

To add proper access control to a cache, replace the default user with a new one that is either disabled by setting the accessString to off -@all or secured with a strong password.

To change the default user, create a new default user with the username set to default. You can then swap it with the original default user.

For more information, see Applying RBAC to a Cache for ElastiCache with Valkey or Redis OSS.

If you want to create a new default user, userName must be default and userId must not be default by using NoPasswordUser or PasswordUser:

// use the original `default` user by using import method
const defaultUser = elasticache.NoPasswordUser.fromUserAttributes(this, 'DefaultUser', {
  // userId and userName must be 'default'
  userId: 'default',
});

// create a new default user
const newDefaultUser = new elasticache.NoPasswordUser(this, 'NewDefaultUser', {
  // new default user id must not be 'default'
  userId: 'new-default',
  // new default username must be 'default'
  userName: 'default',
  // set access string
  accessControl: elasticache.AccessControl.fromAccessString("on ~* +@all"),
});

# use the original `default` user by using import method
default_user = elasticache.NoPasswordUser.from_user_attributes(self, "DefaultUser",
    # userId and userName must be 'default'
    user_id="default"
)

# create a new default user
new_default_user = elasticache.NoPasswordUser(self, "NewDefaultUser",
    # new default user id must not be 'default'
    user_id="new-default",
    # new default username must be 'default'
    user_name="default",
    # set access string
    access_control=elasticache.AccessControl.from_access_string("on ~* +@all")
)

// use the original `default` user by using import method
IUser defaultUser = NoPasswordUser.fromUserAttributes(this, "DefaultUser", UserBaseAttributes.builder()
        // userId and userName must be 'default'
        .userId("default")
        .build());

// create a new default user
NoPasswordUser newDefaultUser = NoPasswordUser.Builder.create(this, "NewDefaultUser")
        // new default user id must not be 'default'
        .userId("new-default")
        // new default username must be 'default'
        .userName("default")
        // set access string
        .accessControl(AccessControl.fromAccessString("on ~* +@all"))
        .build();

// use the original `default` user by using import method
var defaultUser = NoPasswordUser.FromUserAttributes(this, "DefaultUser", new UserBaseAttributes {
    // userId and userName must be 'default'
    UserId = "default"
});

// create a new default user
var newDefaultUser = new NoPasswordUser(this, "NewDefaultUser", new NoPasswordUserProps {
    // new default user id must not be 'default'
    UserId = "new-default",
    // new default username must be 'default'
    UserName = "default",
    // set access string
    AccessControl = AccessControl.FromAccessString("on ~* +@all")
});

// use the original `default` user by using import method
defaultUser := elasticache.NoPasswordUser_FromUserAttributes(this, jsii.String("DefaultUser"), &UserBaseAttributes{
	// userId and userName must be 'default'
	UserId: jsii.String("default"),
})

// create a new default user
newDefaultUser := elasticache.NewNoPasswordUser(this, jsii.String("NewDefaultUser"), &NoPasswordUserProps{
	// new default user id must not be 'default'
	UserId: jsii.String("new-default"),
	// new default username must be 'default'
	UserName: jsii.String("default"),
	// set access string
	AccessControl: elasticache.AccessControl_FromAccessString(jsii.String("on ~* +@all")),
})

NOTE: You can't create a new default user using IamUser because an IAM-enabled user's username and user ID cannot be different.

Add users to the user group

Next, use the UserGroup construct to create a user group and add users to it. Ensure that you include either the original default user or a new default user:

declare const newDefaultUser: elasticache.IUser;
declare const user: elasticache.IUser;
declare const anotherUser: elasticache.IUser;

const userGroup = new elasticache.UserGroup(this, 'UserGroup', {
  // add users including default user
  users: [newDefaultUser, user],
});

// you can also add a user by using addUser method
userGroup.addUser(anotherUser);

# new_default_user: elasticache.IUser
# user: elasticache.IUser
# another_user: elasticache.IUser


user_group = elasticache.UserGroup(self, "UserGroup",
    # add users including default user
    users=[new_default_user, user]
)

# you can also add a user by using addUser method
user_group.add_user(another_user)

IUser newDefaultUser;
IUser user;
IUser anotherUser;


UserGroup userGroup = UserGroup.Builder.create(this, "UserGroup")
        // add users including default user
        .users(List.of(newDefaultUser, user))
        .build();

// you can also add a user by using addUser method
userGroup.addUser(anotherUser);

IUser newDefaultUser;
IUser user;
IUser anotherUser;


var userGroup = new UserGroup(this, "UserGroup", new UserGroupProps {
    // add users including default user
    Users = new [] { newDefaultUser, user }
});

// you can also add a user by using addUser method
userGroup.AddUser(anotherUser);

var newDefaultUser IUser
var user IUser
var anotherUser IUser


userGroup := elasticache.NewUserGroup(this, jsii.String("UserGroup"), &UserGroupProps{
	// add users including default user
	Users: []IUser{
		newDefaultUser,
		user,
	},
})

// you can also add a user by using addUser method
userGroup.AddUser(anotherUser)

Assign user group

Finally, assign a user group to cache:

declare const vpc: ec2.Vpc;
declare const userGroup: elasticache.UserGroup;

const serverlessCache = new elasticache.ServerlessCache(this, 'ServerlessCache', {
  engine: elasticache.CacheEngine.VALKEY_LATEST,
  serverlessCacheName: 'my-serverless-cache',
  vpc,
  // assign User Group
  userGroup,
});

# vpc: ec2.Vpc
# user_group: elasticache.UserGroup


serverless_cache = elasticache.ServerlessCache(self, "ServerlessCache",
    engine=elasticache.CacheEngine.VALKEY_LATEST,
    serverless_cache_name="my-serverless-cache",
    vpc=vpc,
    # assign User Group
    user_group=user_group
)

Vpc vpc;
UserGroup userGroup;


ServerlessCache serverlessCache = ServerlessCache.Builder.create(this, "ServerlessCache")
        .engine(CacheEngine.VALKEY_LATEST)
        .serverlessCacheName("my-serverless-cache")
        .vpc(vpc)
        // assign User Group
        .userGroup(userGroup)
        .build();

Vpc vpc;
UserGroup userGroup;


var serverlessCache = new ServerlessCache(this, "ServerlessCache", new ServerlessCacheProps {
    Engine = CacheEngine.VALKEY_LATEST,
    ServerlessCacheName = "my-serverless-cache",
    Vpc = vpc,
    // assign User Group
    UserGroup = userGroup
});

var vpc Vpc
var userGroup UserGroup


serverlessCache := elasticache.NewServerlessCache(this, jsii.String("ServerlessCache"), &ServerlessCacheProps{
	Engine: elasticache.CacheEngine_VALKEY_LATEST(),
	ServerlessCacheName: jsii.String("my-serverless-cache"),
	Vpc: Vpc,
	// assign User Group
	UserGroup: UserGroup,
})

Grant permissions to IAM-enabled users

If you create IAM-enabled users, "elasticache:Connect" action must be allowed for the users and cache.

NOTE: You don't need grant permissions to no password required users or password authentication users.

For more information, see Authenticating with IAM.

To grant permissions, you can use the grantConnect method in IamUser and ServerlessCache constructs:

declare const user: elasticache.IamUser;
declare const serverlessCache: elasticache.ServerlessCache;
declare const role: iam.Role;

// grant "elasticache:Connect" action permissions to role
user.grantConnect(role);
serverlessCache.grants.connect(role);

# user: elasticache.IamUser
# serverless_cache: elasticache.ServerlessCache
# role: iam.Role


# grant "elasticache:Connect" action permissions to role
user.grant_connect(role)
serverless_cache.grants.connect(role)

IamUser user;
ServerlessCache serverlessCache;
Role role;


// grant "elasticache:Connect" action permissions to role
user.grantConnect(role);
serverlessCache.grants.connect(role);

IamUser user;
ServerlessCache serverlessCache;
Role role;


// grant "elasticache:Connect" action permissions to role
user.GrantConnect(role);
serverlessCache.Grants.Connect(role);

var user IamUser
var serverlessCache ServerlessCache
var role Role


// grant "elasticache:Connect" action permissions to role
user.GrantConnect(role)
serverlessCache.Grants.Connect(role)

Import an existing user and user group

You can import an existing user and user group by using import methods:

const stack = new Stack();

const importedIamUser = elasticache.IamUser.fromUserId(this, 'ImportedIamUser', 'my-iam-user-id');

const importedPasswordUser = elasticache.PasswordUser.fromUserAttributes(stack, 'ImportedPasswordUser', {
  userId: 'my-password-user-id',
});

const importedNoPasswordUser = elasticache.NoPasswordUser.fromUserAttributes(stack, 'ImportedNoPasswordUser', {
  userId: 'my-no-password-user-id',
});

const importedUserGroup = elasticache.UserGroup.fromUserGroupAttributes(this, 'ImportedUserGroup', {
  userGroupName: 'my-user-group-name'
});

stack = Stack()

imported_iam_user = elasticache.IamUser.from_user_id(self, "ImportedIamUser", "my-iam-user-id")

imported_password_user = elasticache.PasswordUser.from_user_attributes(stack, "ImportedPasswordUser",
    user_id="my-password-user-id"
)

imported_no_password_user = elasticache.NoPasswordUser.from_user_attributes(stack, "ImportedNoPasswordUser",
    user_id="my-no-password-user-id"
)

imported_user_group = elasticache.UserGroup.from_user_group_attributes(self, "ImportedUserGroup",
    user_group_name="my-user-group-name"
)

Stack stack = new Stack();

IUser importedIamUser = IamUser.fromUserId(this, "ImportedIamUser", "my-iam-user-id");

IUser importedPasswordUser = PasswordUser.fromUserAttributes(stack, "ImportedPasswordUser", UserBaseAttributes.builder()
        .userId("my-password-user-id")
        .build());

IUser importedNoPasswordUser = NoPasswordUser.fromUserAttributes(stack, "ImportedNoPasswordUser", UserBaseAttributes.builder()
        .userId("my-no-password-user-id")
        .build());

IUserGroup importedUserGroup = UserGroup.fromUserGroupAttributes(this, "ImportedUserGroup", UserGroupAttributes.builder()
        .userGroupName("my-user-group-name")
        .build());

var stack = new Stack();

var importedIamUser = IamUser.FromUserId(this, "ImportedIamUser", "my-iam-user-id");

var importedPasswordUser = PasswordUser.FromUserAttributes(stack, "ImportedPasswordUser", new UserBaseAttributes {
    UserId = "my-password-user-id"
});

var importedNoPasswordUser = NoPasswordUser.FromUserAttributes(stack, "ImportedNoPasswordUser", new UserBaseAttributes {
    UserId = "my-no-password-user-id"
});

var importedUserGroup = UserGroup.FromUserGroupAttributes(this, "ImportedUserGroup", new UserGroupAttributes {
    UserGroupName = "my-user-group-name"
});

stack := awscdk.Newstack()

importedIamUser := elasticache.IamUser_FromUserId(this, jsii.String("ImportedIamUser"), jsii.String("my-iam-user-id"))

importedPasswordUser := elasticache.PasswordUser_FromUserAttributes(stack, jsii.String("ImportedPasswordUser"), &UserBaseAttributes{
	UserId: jsii.String("my-password-user-id"),
})

importedNoPasswordUser := elasticache.NoPasswordUser_FromUserAttributes(stack, jsii.String("ImportedNoPasswordUser"), &UserBaseAttributes{
	UserId: jsii.String("my-no-password-user-id"),
})

importedUserGroup := elasticache.UserGroup_FromUserGroupAttributes(this, jsii.String("ImportedUserGroup"), &UserGroupAttributes{
	UserGroupName: jsii.String("my-user-group-name"),
})

Types

Name	Kind	Summary
IamUser	Construct (L2)	Define an ElastiCache user with IAM authentication.
NoPasswordUser	Construct (L2)	Define an ElastiCache user with no password authentication.
PasswordUser	Construct (L2)	Define an ElastiCache user with password authentication.
ServerlessCache	Construct (L2)	A serverless ElastiCache cache.
ServerlessCacheBase	Construct (L2)	Base class for ServerlessCache constructs.
UserBase	Construct (L2)	Base class for ElastiCache users.
UserGroup	Construct (L2)	An ElastiCache UserGroup.
UserGroupBase	Construct (L2)	Base class for UserGroup constructs.
AccessControl	Class	Access control configuration for ElastiCache users.
BackupSettings	Struct	Backup configuration for ServerlessCache.
CacheEngine	Class	Supported cache engines together with available versions.
CacheUsageLimitsProperty	Struct	Usage limits configuration for ServerlessCache.
IamUserProps	Struct	Properties for defining an ElastiCache user with IAM authentication.
IServerlessCache	Interface	Represents a Serverless ElastiCache cache.
IUser	Interface	Represents an ElastiCache base user.
IUserGroup	Interface	Represents an ElastiCache UserGroup.
NoPasswordUserProps	Struct	Properties for defining an ElastiCache user with no password authentication.
PasswordUserProps	Struct	Properties for defining an ElastiCache user with password authentication.
ServerlessCacheAttributes	Struct	Attributes that can be specified when importing a ServerlessCache.
ServerlessCacheGrants	Facade	Collection of grant methods for a IServerlessCacheRef.
ServerlessCacheProps	Struct	Properties for defining a ServerlessCache.
UserBaseAttributes	Struct	Attributes for importing an existing ElastiCache user.
UserBaseProps	Struct	Properties for defining an ElastiCache base user.
UserEngine	Class	Engine type for ElastiCache users and user groups.
UserGroupAttributes	Struct	Attributes that can be specified when importing a UserGroup.
UserGroupProps	Struct	Properties for defining an ElastiCache UserGroup.