Skip to main content

Create a Cache Instance

Deploy a high-performance cache in under a minute.

Prerequisites​

  • A project created in your organization
  • At least one container that will use the cache

Step-by-Step Guide​

1. Navigate to Services​

  1. Select your project from the project switcher
  2. Click Services in the left sidebar
  3. Click Create Service and select Valkey

2. Basic Configuration​

Cache Name​

Enter a unique name for your cache:

Valid: my-cache, session-store, api-cache
Invalid: My Cache, cache_prod, cache.main
Naming

Use lowercase letters, numbers, and hyphens. The name becomes part of the internal hostname.

Valkey Version​

Select the Valkey version:

VersionRecommendation
9.0Current supported version
Version

Currently, only Valkey 9.0 is available. Future versions will be added as they are validated.

3. Cluster Configuration​

Configure the number of shards for your cache cluster:

ShardsDescription
1Single shard, development use
2-3Small production clusters
4-6Large production clusters

The default is 3 shards.

Cluster size is permanent

The number of shards cannot be changed after the instance is created. Changing the number of shards requires migrating data to a new instance. Storage, unlike cluster size, can still be grown afterwards.

Storage class is permanent

The storage class (standard or performance) cannot be changed after the instance is created. Choose the storage class you need now.

Cluster Sizing
  • Start with 1 shard for development
  • Use 3 shards for production workloads
  • Maximum 6 shards per cache instance
  • Each shard is an independent primary without replicas or automatic failover

4. Compute Configuration​

Compute Class​

Select a compute class based on your needs:

ClassDescriptionBest For
EcoShared resourcesDevelopment and testing
StandardBalanced performanceGeneral production caches
ProductionDedicated resourcesCritical caches requiring guaranteed performance

Flavor​

Choose a flavor that defines CPU and memory allocation:

FlavorDescription
SmallLight workloads
MediumStandard production
LargeHigh-traffic applications
XLargeEnterprise-scale caching

The exact resource values for each flavor vary by compute class. Pricing is shown when selecting a flavor.

Sizing Tip

Start with Eco / Small for development. You can upgrade flavor and compute class later without data loss.

5. Storage Configuration​

Every Valkey shard uses a persistent volume with periodic RDB snapshots.

  • Storage Size: Default is 1Gi per shard (or 10Gi when persistence is explicitly enabled). Choose a larger size if your dataset requires it.
  • Storage Class: standard (5,000 IOPS) or performance (15,000 IOPS) — default is standard
  • Storage can be increased later without downtime, but cannot be reduced
Storage class is permanent

The storage class cannot be changed after creation. Choose the class that fits your I/O requirements now.

6. Security Configuration (Optional)​

Authentication​

Enable password authentication for your cache:

  • Toggle Authentication to enable
  • Set a strong password (minimum 8 characters)
  • Required if enabling public access
  • The password can be changed after creation

Public Access​

Enable external access to your cache:

  1. Toggle Public Access to ON
  2. Add CIDR ranges to the allowlist, with an optional note per entry to identify its purpose
  3. Only listed IPs can connect from outside your project
Public Access Requirements
  • Authentication must be enabled to use public access
  • Always configure the IP allowlist
  • Never expose your cache without IP restrictions
  • Public connections are unencrypted — TLS is not available for Valkey

7. Create the Cache​

  1. Review your configuration
  2. Click Create
  3. Wait for provisioning (~15 seconds)

Instance Detail Tabs​

Once created, your Valkey cache detail view has the following tabs:

TabDescription
OverviewStatus, connection information, configuration summary
LogsReal-time and historical cache logs
AlertsView alerts related to this cache instance
ObservabilityMemory, connections, and command metrics

After Creation​

View Connection Details​

  1. Go to your cache instance
  2. Click the Overview tab
  3. View:
    • Host
    • Port
    • Password
    • Connection string

Connection String Format​

The connection string uses internal DNS format {service-name}.{namespace}:

redis://default:[email protected]:6379

The namespace is automatically assigned to your project. You can find the full connection string in the cache Overview tab under "Connection Information".

Test Connection​

From a container in the same project:

# Using redis-cli (replace with your actual hostname)
redis-cli -h my-cache.my-project-abc123 -a YOUR_PASSWORD

# Test with PING
127.0.0.1:6379> PING
PONG

Connection Examples​

Node.js (ioredis)​

const Redis = require('ioredis');

const redis = new Redis({
host: 'my-cache.my-project-abc123', // {service-name}.{namespace}
port: 6379,
password: process.env.REDIS_PASSWORD,
retryDelayOnFailover: 100,
maxRetriesPerRequest: 3
});

// Test connection
redis.ping().then(console.log); // PONG

// Basic operations
await redis.set('key', 'value');
const value = await redis.get('key');

Node.js (redis)​

import { createClient } from 'redis';

const client = createClient({
url: process.env.REDIS_URL
// redis://default:PASSWORD@host:6379
});

await client.connect();

await client.set('key', 'value');
const value = await client.get('key');

Python (redis-py)​

import redis
import os

r = redis.Redis(
host='my-cache.my-project-abc123', # {service-name}.{namespace}
port=6379,
password=os.environ['REDIS_PASSWORD'],
decode_responses=True
)

# Test connection
print(r.ping()) # True

# Basic operations
r.set('key', 'value')
value = r.get('key')

Go (go-redis)​

import (
"context"
"os"
"github.com/redis/go-redis/v9"
)

ctx := context.Background()

rdb := redis.NewClient(&redis.Options{
Addr: "my-cache.my-project-abc123:6379", // {service-name}.{namespace}
Password: os.Getenv("REDIS_PASSWORD"),
DB: 0,
})

// Test connection
pong, err := rdb.Ping(ctx).Result()

// Basic operations
err = rdb.Set(ctx, "key", "value", 0).Err()
val, err := rdb.Get(ctx, "key").Result()

PHP (predis)​

<?php
require 'vendor/autoload.php';

$client = new Predis\Client([
'scheme' => 'tcp',
'host' => 'my-cache.my-project-abc123', // {service-name}.{namespace}
'port' => 6379,
'password' => getenv('REDIS_PASSWORD'),
]);

// Test connection
echo $client->ping(); // PONG

// Basic operations
$client->set('key', 'value');
$value = $client->get('key');

Ruby (redis-rb)​

require 'redis'

redis = Redis.new(
host: 'my-cache.my-project-abc123', # {service-name}.{namespace}
port: 6379,
password: ENV['REDIS_PASSWORD']
)

# Test connection
redis.ping # => "PONG"

# Basic operations
redis.set('key', 'value')
value = redis.get('key')

Configure Your Application​

Environment Variable​

Add the connection URL to your container (format: {service-name}.{namespace}):

REDIS_URL=redis://default:[email protected]:6379

Or separate variables:

REDIS_HOST=my-cache.my-project-abc123
REDIS_PORT=6379
REDIS_PASSWORD=your-password

Framework Integration​

Express.js Sessions​

const session = require('express-session');
const RedisStore = require('connect-redis').default;
const Redis = require('ioredis');

const redisClient = new Redis(process.env.REDIS_URL);

app.use(session({
store: new RedisStore({ client: redisClient }),
secret: 'your-secret',
resave: false,
saveUninitialized: false,
cookie: { secure: true, maxAge: 86400000 }
}));

Django Cache​

# settings.py
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.redis.RedisCache',
'LOCATION': os.environ['REDIS_URL'],
}
}

Laravel Cache​

// .env
CACHE_DRIVER=redis
REDIS_HOST=my-cache.my-project-abc123
REDIS_PASSWORD=your-password
REDIS_PORT=6379

// config/database.php
'redis' => [
'client' => 'predis',
'default' => [
'host' => env('REDIS_HOST'),
'password' => env('REDIS_PASSWORD'),
'port' => env('REDIS_PORT'),
'database' => 0,
],
],

Rails Cache​

# config/environments/production.rb
config.cache_store = :redis_cache_store, {
url: ENV['REDIS_URL'],
pool_size: 5,
pool_timeout: 5
}

Connection Pooling​

Why Use Connection Pooling?​

  • Reduces connection overhead
  • Improves performance
  • Handles connection failures gracefully

ioredis with Pool​

const Redis = require('ioredis');

// ioredis handles pooling internally
const redis = new Redis({
host: 'my-cache.my-project-abc123', // {service-name}.{namespace}
port: 6379,
password: process.env.REDIS_PASSWORD,
lazyConnect: true,
maxRetriesPerRequest: 3,
retryStrategy(times) {
return Math.min(times * 50, 2000);
}
});

Python with Connection Pool​

import redis

pool = redis.ConnectionPool(
host='my-cache.my-project-abc123', # {service-name}.{namespace}
port=6379,
password=os.environ['REDIS_PASSWORD'],
max_connections=10
)

r = redis.Redis(connection_pool=pool)

Troubleshooting​

Connection Refused​

  • Verify the cache is running
  • Check hostname and port
  • Ensure container is in the same project

Authentication Failed​

NOAUTH Authentication required
  • Check password is correct
  • Copy password from Connection tab

Connection Timeout​

  • Check network connectivity
  • Verify cache isn't overloaded
  • Check for firewall issues

Memory Full​

OOM command not allowed when used memory > 'maxmemory'
  • Upgrade to larger instance
  • Review expiration policies
  • Check for memory leaks
# Check memory usage
redis-cli -h host -a password INFO memory

Best Practices​

1. Use Environment Variables​

Never hardcode passwords:

// Good
const password = process.env.REDIS_PASSWORD;

// Bad
const password = 'my-secret-password';

2. Handle Connection Errors​

redis.on('error', (err) => {
console.error('Redis error:', err);
});

redis.on('connect', () => {
console.log('Connected to Redis');
});

3. Set Reasonable Timeouts​

const redis = new Redis({
connectTimeout: 5000,
commandTimeout: 5000,
...
});

4. Use Pipelines for Multiple Commands​

// Slow - individual commands
await redis.set('key1', 'value1');
await redis.set('key2', 'value2');
await redis.set('key3', 'value3');

// Fast - pipelined
const pipeline = redis.pipeline();
pipeline.set('key1', 'value1');
pipeline.set('key2', 'value2');
pipeline.set('key3', 'value3');
await pipeline.exec();

Next Steps​