Guides & Examples

9 minute read

Guides Overview

Guides complement reference documentation by walking users through common scenarios, best practices, and real-world use cases.

Guide Types

Getting Started Guide

Help new users create their first resources:

---
page_title: "Getting Started with CacheCloud"
description: |-
  Create your first cache in 5 minutes.
---

# Getting Started with CacheCloud

This guide walks you through creating your first Redis cache using the CacheCloud provider.

## Prerequisites

- Terraform 1.0 or later
- CacheCloud account and API key
- Basic understanding of Terraform

## Step 1: Install the Provider

Create a new directory and `main.tf`:

```terraform
terraform {
  required_version = ">= 1.0"
  
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      version = "~> 1.0"
    }
  }
}

Step 2: Configure Authentication

Set your API key:

export CACHECLOUD_API_KEY="your-api-key-here"

Configure the provider:

provider "cachecloud" {
  region = "us-east-1"
}

Step 3: Create a Cache

Add a basic Redis cache:

resource "cachecloud_cache" "my_first_cache" {
  name      = "my-first-cache"
  engine    = "redis"
  version   = "7.0"
  node_type = "cache.t3.micro"
  
  tags = {
    Environment = "learning"
  }
}

Step 4: Output Connection Details

output "cache_endpoint" {
  description = "Connection endpoint for the cache"
  value       = cachecloud_cache.my_first_cache.endpoint
}

output "cache_port" {
  description = "Connection port"
  value       = cachecloud_cache.my_first_cache.port
}

Step 5: Apply Configuration

# Initialize Terraform
terraform init

# Review the plan
terraform plan

# Create the cache
terraform apply

After a few minutes, you’ll see:

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

cache_endpoint = "my-first-cache.abc123.cache.example.com"
cache_port = 6379

Step 6: Test the Cache

Connect using redis-cli:

redis-cli -h my-first-cache.abc123.cache.example.com -p 6379

# Test basic commands
127.0.0.1:6379> SET mykey "Hello World"
OK
127.0.0.1:6379> GET mykey
"Hello World"

Step 7: Cleanup

When you’re done:

terraform destroy

Next Steps

Authentication Guide

---
page_title: "Authentication Methods"
description: |-
  Configure authentication for the CacheCloud provider.
---

# Authentication Methods

The CacheCloud provider supports multiple authentication methods for different environments and use cases.

## API Key Authentication

### Environment Variable (Recommended)

The most common and secure method:

```bash
export CACHECLOUD_API_KEY="cc_live_1234567890abcdef"

provider "cachecloud" {}

Pros:

  • ✅ Keeps secrets out of code
  • ✅ Easy to rotate
  • ✅ Works with CI/CD

Cons:

  • ❌ Must set for each shell session
  • ❌ Can be accidentally logged

Terraform Variables

Use with encrypted state:

variable "cachecloud_api_key" {
  type      = string
  sensitive = true
}

provider "cachecloud" {
  api_key = var.cachecloud_api_key
}

Set via environment:

export TF_VAR_cachecloud_api_key="cc_live_1234567890abcdef"
terraform apply

Or via CLI:

terraform apply -var="cachecloud_api_key=cc_live_1234567890abcdef"

Credentials File

For multiple environments:

# ~/.cachecloud/credentials
[default]
api_key = cc_live_prod_key
region = us-east-1

[staging]
api_key = cc_live_staging_key
region = us-west-2

[development]
api_key = cc_live_dev_key
region = us-west-2

# Production
provider "cachecloud" {
  alias   = "prod"
  profile = "default"
}

# Staging
provider "cachecloud" {
  alias   = "staging"
  profile = "staging"
}

IAM Role Authentication

For AWS-based deployments:

provider "cachecloud" {
  auth_method = "iam"
  role_arn    = "arn:aws:iam::123456789012:role/CacheCloudTerraformRole"
}

IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cachecloud:*"
      ],
      "Resource": "*"
    }
  ]
}

Trust Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

OAuth 2.0 Authentication

For enterprise SSO integration:

provider "cachecloud" {
  auth_method   = "oauth"
  client_id     = var.oauth_client_id
  client_secret = var.oauth_client_secret
  token_url     = "https://auth.example.com/oauth/token"
  scopes        = ["cachecloud.read", "cachecloud.write"]
}

Service Account Authentication

For Kubernetes environments:

provider "cachecloud" {
  auth_method = "service_account"
  
  # Automatically uses in-cluster service account
  # Or specify token explicitly:
  # service_account_token = var.sa_token
}

Choosing an Authentication Method

Method Use Case Security Complexity
API Key (env var) CI/CD, local development ⭐⭐⭐⭐ ⭐
API Key (file) Multiple environments ⭐⭐⭐ ⭐⭐
IAM Role AWS infrastructure ⭐⭐⭐⭐⭐ ⭐⭐⭐
OAuth 2.0 Enterprise SSO ⭐⭐⭐⭐ ⭐⭐⭐⭐
Service Account Kubernetes ⭐⭐⭐⭐ ⭐⭐⭐

Best Practices

1. Never Commit Secrets

❌ Bad:

provider "cachecloud" {
  api_key = "cc_live_1234567890abcdef"  # Hard-coded!
}

✅ Good:

provider "cachecloud" {
  api_key = var.cachecloud_api_key  # From variable
}

2. Use Different Keys per Environment

locals {
  api_keys = {
    prod    = var.prod_api_key
    staging = var.staging_api_key
    dev     = var.dev_api_key
  }
}

provider "cachecloud" {
  api_key = local.api_keys[var.environment]
}

3. Rotate Keys Regularly

# Generate new key
NEW_KEY=$(cachecloud api-keys create --output json | jq -r '.key')

# Update environment
export CACHECLOUD_API_KEY="$NEW_KEY"

# Test
terraform plan

# Revoke old key
cachecloud api-keys revoke <old-key-id>

4. Least Privilege

Create keys with minimal permissions:

cachecloud api-keys create \
  --name "terraform-prod" \
  --scopes "cache:read,cache:write" \
  --resources "region:us-east-1"

Troubleshooting

Invalid API Key

Error: authentication failed: invalid API key

Solutions:

  • Verify key is correctly set: echo $CACHECLOUD_API_KEY
  • Check key hasn’t expired
  • Ensure key has correct permissions

Region Mismatch

Error: resource not found

Solutions:

  • Verify region matches resource location
  • Check API endpoint configuration ```

High Availability Guide

---
page_title: "High Availability Configuration"
description: |-
  Configure highly available cache clusters.
---

# High Availability Configuration

This guide covers configuring CacheCloud caches for high availability and fault tolerance.

## Multi-AZ Deployment

Deploy caches across multiple availability zones:

```terraform
resource "cachecloud_cache" "ha_cache" {
  name      = "ha-cache"
  engine    = "redis"
  node_type = "cache.m5.large"
  num_nodes = 3
  
  # Enable multi-AZ
  multi_az_enabled = true
  
  # Automatic failover
  automatic_failover_enabled = true
  
  # Spread across AZs
  availability_zones = [
    "us-east-1a",
    "us-east-1b",
    "us-east-1c"
  ]
}

Replication

Configure read replicas:

resource "cachecloud_cache" "primary" {
  name      = "primary-cache"
  engine    = "redis"
  node_type = "cache.m5.large"
  
  # Primary with replicas
  num_nodes = 3  # 1 primary + 2 replicas
  
  replication_enabled = true
}

output "write_endpoint" {
  value = cachecloud_cache.primary.endpoint
}

output "read_endpoint" {
  value = cachecloud_cache.primary.reader_endpoint
}

Cluster Mode

For horizontal scaling:

resource "cachecloud_cache" "cluster" {
  name      = "redis-cluster"
  engine    = "redis"
  node_type = "cache.m5.large"
  
  # Enable cluster mode
  cluster_mode_enabled = true
  
  # Shard configuration
  num_shards         = 3
  replicas_per_shard = 2
  
  # Multi-AZ for each shard
  multi_az_enabled = true
}

Complete HA Example

# Production-ready HA configuration
resource "cachecloud_cache" "production" {
  name      = "prod-api-cache"
  engine    = "redis"
  version   = "7.0"
  node_type = "cache.m5.xlarge"
  
  # Cluster configuration
  cluster_mode_enabled = true
  num_shards          = 3
  replicas_per_shard  = 2
  
  # High availability
  multi_az_enabled           = true
  automatic_failover_enabled = true
  
  # Backup for disaster recovery
  backup_enabled        = true
  backup_retention_days = 30
  
  # Maintenance
  maintenance_window = "sun:03:00-sun:05:00"
  
  # Monitoring
  monitoring_enabled = true
  
  alarm_cpu_threshold    = 75
  alarm_memory_threshold = 80
  alarm_evictions        = true
  
  # Notifications
  notification_topic_arn = aws_sns_topic.cache_alerts.arn
  
  tags = {
    Environment = "production"
    HA          = "enabled"
  }
}

# SNS topic for alerts
resource "aws_sns_topic" "cache_alerts" {
  name = "cache-alerts"
}

resource "aws_sns_topic_subscription" "email" {
  topic_arn = aws_sns_topic.cache_alerts.arn
  protocol  = "email"
  endpoint  = "ops@example.com"
}

Testing Failover

# Simulate node failure
cachecloud cache fail-node \
  --cache-id cache-123456 \
  --node-id node-1

# Monitor failover
watch "cachecloud cache describe --id cache-123456 --format json | jq '.status'"

# Verify write operations continue
redis-cli -h prod-cache.example.com SET test "failover-test"

Best Practices

  1. Use Multi-AZ: Always enable for production
  2. Monitor Health: Set up CloudWatch alarms
  3. Test Failover: Regularly test failure scenarios
  4. Size Appropriately: Ensure nodes can handle full load during failover
  5. Backup Regularly: Enable automated backups ```

Migration Guide

---
page_title: "Migration Guide"
description: |-
  Migrate from self-managed caches to CacheCloud.
---

# Migration Guide

This guide covers migrating from self-managed Redis/Memcached to CacheCloud.

## Prerequisites

- Source cache accessible
- Backup of source data
- Network connectivity between source and destination
- Minimal downtime window planned

## Migration Strategies

### Strategy 1: Dual Write (Zero Downtime)

1. **Create Target Cache**

```terraform
resource "cachecloud_cache" "target" {
  name      = "migrated-cache"
  engine    = "redis"
  version   = "7.0"
  node_type = "cache.m5.large"
  num_nodes = 2
  
  multi_az_enabled = true
}
  1. Configure Application for Dual Write
import redis

# Source cache
source = redis.Redis(host='old-cache.internal', port=6379)

# Target cache (CacheCloud)
target = redis.Redis(
    host=terraform.output('cache_endpoint'),
    port=6379
)

def set_value(key, value):
    # Write to both caches
    source.set(key, value)
    target.set(key, value)
    
def get_value(key):
    # Read from target, fallback to source
    value = target.get(key)
    if value is None:
        value = source.get(key)
        if value is not None:
            # Backfill target
            target.set(key, value)
    return value
  1. Migrate Historical Data
# Using redis-cli
redis-cli --rdb old-cache.internal > dump.rdb

# Restore to target
redis-cli -h target-cache.example.com --pipe < dump.rdb
  1. Switch to Target Only
def set_value(key, value):
    target.set(key, value)  # Only target now
    
def get_value(key):
    return target.get(key)  # Only target now

Strategy 2: Snapshot and Restore

  1. Create Snapshot
# Create RDB snapshot
redis-cli -h old-cache.internal BGSAVE
  1. Create Target Cache
resource "cachecloud_cache" "target" {
  name      = "migrated-cache"
  engine    = "redis"
  version   = "7.0"
  node_type = "cache.m5.large"
}
  1. Restore Snapshot
# Upload to S3
aws s3 cp dump.rdb s3://my-bucket/cache-backup/

# Restore via CacheCloud
cachecloud cache restore \
  --cache-id cache-123456 \
  --snapshot-location s3://my-bucket/cache-backup/dump.rdb
  1. Switch Application
# Update DNS or configuration
export REDIS_HOST=migrated-cache.example.com

Complete Example

# Target cache configuration
resource "cachecloud_cache" "migrated" {
  name      = "prod-cache-migrated"
  engine    = "redis"
  version   = "7.0"
  node_type = "cache.m5.xlarge"
  num_nodes = 3
  
  # Match source configuration
  port = 6379
  
  # Production settings
  multi_az_enabled           = true
  automatic_failover_enabled = true
  backup_enabled             = true
  
  # Network - same VPC as source
  vpc_id     = var.vpc_id
  subnet_ids = var.subnet_ids
  
  tags = {
    MigratedFrom = "self-managed"
    MigrationDate = "2026-06-30"
  }
}

# DNS for gradual cutover
resource "aws_route53_record" "cache" {
  zone_id = var.zone_id
  name    = "cache.internal.example.com"
  type    = "CNAME"
  ttl     = 60  # Low TTL for quick updates
  
  # Initially points to old cache
  # records = [var.old_cache_endpoint]
  
  # After migration, update to new cache
  records = [cachecloud_cache.migrated.endpoint]
}

Validation

# Compare key counts
redis-cli -h old-cache INFO keyspace
redis-cli -h new-cache INFO keyspace

# Sample key comparison
redis-cli -h old-cache --scan --pattern "user:*" | head -100 > old-keys.txt
redis-cli -h new-cache --scan --pattern "user:*" | head -100 > new-keys.txt
diff old-keys.txt new-keys.txt

# Performance test
redis-benchmark -h new-cache -t set,get -n 100000

Rollback Plan

# Keep old infrastructure during migration
resource "aws_elasticache_cluster" "old" {
  count = var.migration_complete ? 0 : 1
  # ... existing configuration
}

locals {
  active_cache_endpoint = var.migration_complete ? (
    cachecloud_cache.migrated.endpoint
  ) : (
    aws_elasticache_cluster.old[0].cache_nodes[0].address
  )
}

output "cache_endpoint" {
  value = local.active_cache_endpoint
}


## Best Practices Documentation

```markdown
## Documentation Best Practices

### 1. User-Focused Writing

Write for your audience:

- **Beginners**: Step-by-step instructions
- **Intermediate**: Common patterns and best practices
- **Advanced**: Architecture and optimization

### 2. Code Quality

```markdown
# ✅ Good: Complete, runnable example
```terraform
terraform {
  required_providers {
    cachecloud = {
      source  = "example/cachecloud"
      version = "~> 1.0"
    }
  }
}

provider "cachecloud" {
  api_key = var.api_key
}

resource "cachecloud_cache" "example" {
  name      = "example-cache"
  engine    = "redis"
  node_type = "cache.t3.micro"
}

❌ Bad: Incomplete snippet

resource "cachecloud_cache" "example" {
  name = "example"
}


### 3. Visual Aids

Include diagrams for complex concepts:

```markdown
## Architecture

┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ │ │ │ │ │ │ Application │─────▶│ CacheCloud │─────▶│ Redis │ │ │ │ (Primary) │ │ Cluster │ │ │ │ │ │ │ └─────────────┘ └──────────────┘ └─────────────┘ │ │ Replication ▼ ┌──────────────┐ │ CacheCloud │ │ (Replica) │ └──────────────┘

4. Troubleshooting Sections

Address common issues:

## Troubleshooting

### Connection Timeout

**Symptom:**

Error: timeout waiting for cache to become available


**Causes:**
- Network connectivity issues
- Security group rules
- Large cache creation time

**Solutions:**
1. Check security group allows traffic on cache port
2. Verify subnet routing
3. Increase timeout in provider configuration:
   ```terraform
   provider "cachecloud" {
     timeout = 60  # seconds
   }

```

Key Takeaways

  • ✅ Create guides for common workflows
  • ✅ Provide step-by-step getting started guide
  • ✅ Document authentication comprehensively
  • ✅ Include migration guides
  • ✅ Show complete, working examples
  • ✅ Add troubleshooting sections
  • ✅ Use diagrams for complex concepts
  • ✅ Organize guides by user journey
  • ✅ Keep examples up to date
  • ✅ Test all code examples

What’s Next?

Learn best practices for writing and maintaining provider documentation.

Next: Documentation Best Practices →

Previous: ← Provider Configuration Docs
Next: Documentation Best Practices →

Last updated: June 30, 2026

Updated:

You may also enjoy