Skip to content

Commit 56ad249

Browse files
joshrotenbergjoshrotenberg
authored
Merge pull request #389 from joshrotenberg/docs/cookbook-poc
docs: add cookbook section with task-oriented recipes (POC)
2 parents ea42d00 + 1396a83 commit 56ad249

File tree

5 files changed

+842
-0
lines changed

5 files changed

+842
-0
lines changed

‎docs/src/SUMMARY.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,15 @@
1212
- [Shell Completions](./getting-started/shell-completions.md)
1313
- [Quick Start Guide](./getting-started/quickstart.md)
1414

15+
# Cookbook
16+
17+
- [Overview](./cookbook/README.md)
18+
- [Redis Cloud]()
19+
- [Create Your First Database](./cookbook/cloud/create-first-database.md)
20+
- [Redis Enterprise]()
21+
- [Create a Database](./cookbook/enterprise/create-database.md)
22+
- [Generate Support Package](./cookbook/enterprise/support-package.md)
23+
1524
# Redis Cloud
1625

1726
- [Overview](./cloud/overview.md)

‎docs/src/cookbook/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Cookbook
2+
3+
Task-oriented recipes for common redisctl operations. Each recipe provides complete, copy-paste ready examples to accomplish specific tasks.
4+
5+
## Quick Start
6+
7+
New to redisctl? Start here:
8+
- [Create Your First Redis Cloud Database](cloud/create-first-database.md)
9+
- [Create Your First Redis Enterprise Database](enterprise/create-database.md)
10+
11+
## Redis Cloud Recipes
12+
13+
### Getting Started
14+
- [Create Your First Database](cloud/create-first-database.md) - ⏱️ 5 minutes
15+
16+
### Networking
17+
- Setup VPC Peering (coming soon)
18+
- Configure Private Service Connect (coming soon)
19+
20+
### Security
21+
- Configure ACL Security (coming soon)
22+
- Manage SSL/TLS Certificates (coming soon)
23+
24+
### Operations
25+
- Backup and Restore Workflow (coming soon)
26+
- Database Migration (coming soon)
27+
28+
## Redis Enterprise Recipes
29+
30+
### Getting Started
31+
- [Create a Database](enterprise/create-database.md) - ⏱️ 5 minutes
32+
33+
### Operations
34+
- [Generate and Upload Support Package](enterprise/support-package.md) - ⏱️ 10 minutes
35+
- Configure Database Replication (coming soon)
36+
37+
### Cluster Management
38+
- Cluster Health Check (coming soon)
39+
- Node Management (coming soon)
40+
41+
## How to Use These Recipes
42+
43+
Each recipe includes:
44+
- ⏱️ **Time estimate** - How long it takes
45+
- 📋 **Prerequisites** - What you need before starting
46+
- ⚡ **Quick command** - One-liner when possible
47+
- 📝 **Step-by-step** - Detailed walkthrough
48+
- ✅ **Expected output** - What success looks like
49+
- 🔗 **Next steps** - Related recipes
50+
- ❌ **Troubleshooting** - Common errors and fixes
51+
52+
## Contributing Recipes
53+
54+
Have a recipe to share? See our [contribution guide](../developer/contributing.md).
55+
56+
## Need More Detail?
57+
58+
These recipes are designed for quick wins. For comprehensive command documentation, see:
59+
- [Cloud Command Reference](../cloud/README.md)
60+
- [Enterprise Command Reference](../enterprise/README.md)

‎docs/src/cookbook/cloud/create-first-database.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# Create Your First Redis Cloud Database
2+
3+
⏱️ **Time:** 5-10 minutes
4+
📋 **Prerequisites:**
5+
- Redis Cloud account ([sign up](https://redis.io/try-free/))
6+
- redisctl installed ([installation guide](../../getting-started/installation.md))
7+
- Profile configured with Cloud credentials ([authentication guide](../../getting-started/authentication.md))
8+
9+
## Quick Command
10+
11+
If you already have a subscription, create a database with one command:
12+
13+
```bash
14+
redisctl cloud database create \
15+
--subscription-id YOUR_SUBSCRIPTION_ID \
16+
--data '{"name": "my-first-db", "memoryLimitInGb": 1}' \
17+
--wait
18+
```
19+
20+
## Step-by-Step Guide
21+
22+
### 1. Verify Your Setup
23+
24+
First, check that redisctl can connect to Redis Cloud:
25+
26+
```bash
27+
redisctl cloud subscription list -o table
28+
```
29+
30+
**What you should see:**
31+
```
32+
┌────┬─────────────────┬────────┬────────────┐
33+
│ ID │ Name │ Status │ Provider │
34+
├────┼─────────────────┼────────┼────────────┤
35+
│ 42 │ my-subscription │ active │ AWS │
36+
└────┴─────────────────┴────────┴────────────┘
37+
```
38+
39+
**Troubleshooting:**
40+
- ❌ "401 Unauthorized" → Check your API credentials with `redisctl profile get`
41+
- ❌ Empty table → Create a subscription first (see [subscription guide](../cloud/subscriptions.md))
42+
43+
### 2. Choose Your Database Configuration
44+
45+
Decide on your database specifications. Here's a minimal configuration:
46+
47+
```json
48+
{
49+
"name": "my-first-db",
50+
"memoryLimitInGb": 1,
51+
"protocol": "redis"
52+
}
53+
```
54+
55+
**Common options:**
56+
- `memoryLimitInGb`: Memory size (1-100+ GB)
57+
- `protocol`: `redis` or `memcached`
58+
- `dataPersistence`: `none`, `aof-every-1-second`, `snapshot-every-1-hour`
59+
- `replication`: `true` for high availability
60+
61+
### 3. Create the Database
62+
63+
Use the subscription ID from step 1:
64+
65+
```bash
66+
redisctl cloud database create \
67+
--subscription-id 42 \
68+
--data '{
69+
"name": "my-first-db",
70+
"memoryLimitInGb": 1,
71+
"protocol": "redis",
72+
"dataPersistence": "aof-every-1-second",
73+
"replication": true
74+
}' \
75+
--wait \
76+
--wait-timeout 300
77+
```
78+
79+
**What's happening:**
80+
- `--wait`: Waits for database to become active
81+
- `--wait-timeout 300`: Waits up to 5 minutes
82+
- Without `--wait`: Returns immediately with task ID
83+
84+
**What you should see:**
85+
86+
```json
87+
{
88+
"taskId": "abc123...",
89+
"status": "processing"
90+
}
91+
...
92+
Database creation completed successfully!
93+
{
94+
"database_id": 12345,
95+
"name": "my-first-db",
96+
"status": "active",
97+
"public_endpoint": "redis-12345.c123.us-east-1-1.ec2.cloud.redislabs.com:12345"
98+
}
99+
```
100+
101+
### 4. Get Your Connection Details
102+
103+
Retrieve your database credentials:
104+
105+
```bash
106+
redisctl cloud database get \
107+
--subscription-id 42 \
108+
--database-id 12345 \
109+
-o json \
110+
-q '{endpoint: public_endpoint, password: password}'
111+
```
112+
113+
**Output:**
114+
```json
115+
{
116+
"endpoint": "redis-12345.c123.us-east-1-1.ec2.cloud.redislabs.com:12345",
117+
"password": "your-password-here"
118+
}
119+
```
120+
121+
### 5. Test Your Connection
122+
123+
Using redis-cli:
124+
125+
```bash
126+
redis-cli -h redis-12345.c123.us-east-1-1.ec2.cloud.redislabs.com \
127+
-p 12345 \
128+
-a your-password-here \
129+
PING
130+
```
131+
132+
Expected response: `PONG`
133+
134+
## Advanced Options
135+
136+
### Using a JSON File
137+
138+
For complex configurations, use a file:
139+
140+
```bash
141+
# Create database-config.json
142+
cat > database-config.json << 'EOF'
143+
{
144+
"name": "production-db",
145+
"memoryLimitInGb": 10,
146+
"protocol": "redis",
147+
"dataPersistence": "aof-every-1-second",
148+
"replication": true,
149+
"throughputMeasurement": {
150+
"by": "operations-per-second",
151+
"value": 25000
152+
},
153+
"dataEvictionPolicy": "volatile-lru",
154+
"modules": [
155+
{"name": "RedisJSON"}
156+
]
157+
}
158+
EOF
159+
160+
# Create database
161+
redisctl cloud database create \
162+
--subscription-id 42 \
163+
--data @database-config.json \
164+
--wait
165+
```
166+
167+
### JSON Output for Automation
168+
169+
Use `-o json` for scripts:
170+
171+
```bash
172+
DB_INFO=$(redisctl cloud database create \
173+
--subscription-id 42 \
174+
--data '{"name": "api-cache", "memoryLimitInGb": 2}' \
175+
--wait \
176+
-o json)
177+
178+
DB_ID=$(echo "$DB_INFO" | jq -r '.database_id')
179+
echo "Created database: $DB_ID"
180+
```
181+
182+
## Common Issues
183+
184+
### Database Creation Times Out
185+
186+
```
187+
Error: Database creation timed out after 300 seconds
188+
```
189+
190+
**Solution:** Some regions take longer. Increase timeout:
191+
```bash
192+
redisctl cloud database create ... --wait --wait-timeout 600
193+
```
194+
195+
### Insufficient Subscription Capacity
196+
197+
```
198+
Error: Subscription has insufficient capacity
199+
```
200+
201+
**Solution:** Either:
202+
1. Delete unused databases: `redisctl cloud database delete ...`
203+
2. Upgrade subscription: Contact Redis support or use the web console
204+
205+
### Invalid Configuration
206+
207+
```
208+
Error: 400 Bad Request - Invalid memory limit
209+
```
210+
211+
**Solution:** Check subscription limits:
212+
```bash
213+
redisctl cloud subscription get --subscription-id 42 -q 'pricing'
214+
```
215+
216+
## Next Steps
217+
218+
Now that you have a database:
219+
220+
- 🔒 [Configure ACL Security](configure-acls.md) - Secure your database with access controls
221+
- 🌐 [Set Up VPC Peering](setup-vpc-peering.md) - Connect to your private network
222+
- 💾 [Configure Backups](backup-restore.md) - Protect your data
223+
- 📊 [Monitor Performance](../../guides/monitoring.md) - Track your database metrics
224+
225+
## See Also
226+
227+
- [Cloud Database Command Reference](../../cloud/core-resources/databases.md) - Complete command documentation
228+
- [Database Configuration Guide](../../cloud/database-configuration.md) - All configuration options
229+
- [Redis Cloud Pricing](https://redis.io/pricing/) - Understand costs

0 commit comments

Comments
 (0)