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
- Select your project from the project switcher
- Click Services in the left sidebar
- 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
Use lowercase letters, numbers, and hyphens. The name becomes part of the internal hostname.
Valkey Version
Select the Valkey version:
| Version | Recommendation |
|---|---|
| 9.0 | Current supported 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:
| Shards | Description |
|---|---|
| 1 | Single shard, development use |
| 2-3 | Small production clusters |
| 4-6 | Large production clusters |
The default is 3 shards.
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.
The storage class (standard or performance) cannot be changed after the instance is created. Choose the storage class you need now.
- 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:
| Class | Description | Best For |
|---|---|---|
| Eco | Shared resources | Development and testing |
| Standard | Balanced performance | General production caches |
| Production | Dedicated resources | Critical caches requiring guaranteed performance |
Flavor
Choose a flavor that defines CPU and memory allocation:
| Flavor | Description |
|---|---|
| Small | Light workloads |
| Medium | Standard production |
| Large | High-traffic applications |
| XLarge | Enterprise-scale caching |
The exact resource values for each flavor vary by compute class. Pricing is shown when selecting a flavor.
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
1Giper shard (or10Giwhen persistence is explicitly enabled). Choose a larger size if your dataset requires it. - Storage Class:
standard(5,000 IOPS) orperformance(15,000 IOPS) — default isstandard - Storage can be increased later without downtime, but cannot be reduced
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:
- Toggle Public Access to ON
- Add CIDR ranges to the allowlist, with an optional note per entry to identify its purpose
- Only listed IPs can connect from outside your project
- 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
- Review your configuration
- Click Create
- Wait for provisioning (~15 seconds)
Instance Detail Tabs
Once created, your Valkey cache detail view has the following tabs:
| Tab | Description |
|---|---|
| Overview | Status, connection information, configuration summary |
| Logs | Real-time and historical cache logs |
| Alerts | View alerts related to this cache instance |
| Observability | Memory, connections, and command metrics |
After Creation
View Connection Details
- Go to your cache instance
- Click the Overview tab
- 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();