Data Source Documentation

9 minute read

Data Source Documentation Overview

Data sources enable Terraform configurations to query and use information from external systems. Good documentation helps users understand how to filter and use this data effectively.

Page Structure

---
page_title: "Data Source: cachecloud_cache"
subcategory: ""
description: |-
  Get information about a CacheCloud cache.
---

# cachecloud_cache (Data Source)

[Description]

## Example Usage

[Examples]

## Schema

[Argument Reference]

[Attribute Reference]

Writing Descriptions

Data Source Description

Explain what data can be queried and common use cases:

# cachecloud_cache (Data Source)

Use this data source to get information about an existing CacheCloud cache. You can query caches by name, ID, or tags.

This data source is useful for:
- **Looking up cache endpoints** for application configuration
- **Referencing existing caches** in Terraform configurations
- **Validating cache existence** before creating dependent resources
- **Reading cache metadata** for monitoring and alerting

**Note:** This data source returns information about a single cache. To list multiple caches, use the `cachecloud_caches` data source.

When to Use

Help users understand appropriate scenarios:

## Use Cases

### Shared Infrastructure

Reference caches managed outside Terraform:

```terraform
data "cachecloud_cache" "shared" {
  name = "shared-session-cache"
}

resource "aws_ssm_parameter" "cache_endpoint" {
  name  = "/app/cache/endpoint"
  value = data.cachecloud_cache.shared.endpoint
}

Environment Configuration

Configure applications based on existing caches:

data "cachecloud_cache" "prod" {
  tags = {
    Environment = "production"
    Application = "api"
  }
}

resource "kubernetes_config_map" "app_config" {
  metadata {
    name = "app-config"
  }
  
  data = {
    CACHE_ENDPOINT = data.cachecloud_cache.prod.endpoint
    CACHE_PORT     = data.cachecloud_cache.prod.port
  }
}

Validation

Ensure dependencies exist before creating resources:

data "cachecloud_cache" "required" {
  name = var.cache_name
}

resource "cachecloud_cache_user" "app" {
  cache_id = data.cachecloud_cache.required.id
  username = "app-user"
}

## Example Usage

### Basic Query

```markdown
## Example Usage

### Query by Name

```terraform
data "cachecloud_cache" "example" {
  name = "my-cache"
}

output "cache_endpoint" {
  value = data.cachecloud_cache.example.endpoint
}

### Query with Multiple Filters

```markdown
### Query by ID

```terraform
data "cachecloud_cache" "by_id" {
  id = "cache-123456"
}

Query by Tags

data "cachecloud_cache" "by_tags" {
  tags = {
    Environment = "production"
    Application = "api"
  }
}

Query with Filter

data "cachecloud_cache" "redis_prod" {
  filter {
    name   = "engine"
    values = ["redis"]
  }
  
  filter {
    name   = "status"
    values = ["available"]
  }
  
  tags = {
    Environment = "production"
  }
}

### Complete Example

```markdown
### Complete Configuration

```terraform
# Look up existing cache
data "cachecloud_cache" "session_cache" {
  name = "prod-session-cache"
}

# Use cache information in application deployment
resource "kubernetes_deployment" "web_app" {
  metadata {
    name = "web-app"
  }
  
  spec {
    replicas = 3
    
    template {
      spec {
        container {
          name  = "app"
          image = "myapp:latest"
          
          env {
            name  = "REDIS_HOST"
            value = data.cachecloud_cache.session_cache.endpoint
          }
          
          env {
            name  = "REDIS_PORT"
            value = tostring(data.cachecloud_cache.session_cache.port)
          }
          
          env {
            name  = "REDIS_TLS_ENABLED"
            value = tostring(data.cachecloud_cache.session_cache.encryption_in_transit_enabled)
          }
        }
      }
    }
  }
}

# Store endpoint in parameter store
resource "aws_ssm_parameter" "cache_endpoint" {
  name        = "/app/cache/endpoint"
  description = "Session cache endpoint"
  type        = "String"
  value       = data.cachecloud_cache.session_cache.endpoint
}

# Create CloudWatch alarm based on cache
resource "aws_cloudwatch_metric_alarm" "cache_cpu" {
  alarm_name          = "cache-high-cpu"
  comparison_operator = "GreaterThanThreshold"
  evaluation_periods  = "2"
  metric_name         = "CPUUtilization"
  namespace           = "CacheCloud"
  period              = "120"
  statistic           = "Average"
  threshold           = "75"
  
  dimensions = {
    CacheId = data.cachecloud_cache.session_cache.id
  }
}

## Schema Documentation

### Arguments (Filters)

Document how to query the data source:

```markdown
## Schema

### Optional

- `id` (String) The unique identifier of the cache. Conflicts with `name`.
- `name` (String) The name of the cache. Conflicts with `id`.
- `tags` (Map of String) Map of tags to filter caches. All specified tags must match.
- `filter` (Block List) Custom filters to narrow results. See [Filter](#filter) below.

### Filter

The `filter` block supports:

- `name` (String) The name of the filter field. Valid values: `engine`, `status`, `node_type`, `version`.
- `values` (List of String) The values to filter by. Multiple values are treated as OR.

**Example:**

```terraform
data "cachecloud_cache" "filtered" {
  filter {
    name   = "engine"
    values = ["redis"]
  }
  
  filter {
    name   = "status"
    values = ["available", "modifying"]
  }
}

Note: If multiple caches match the filters, the data source will fail. Use cachecloud_caches (plural) to return multiple results.

### Attributes (Outputs)

Document all available attributes:

```markdown
### Read-Only

All cache attributes are exported:

- `id` (String) The unique identifier of the cache.
- `arn` (String) The Amazon Resource Name (ARN) of the cache.
- `name` (String) The name of the cache.
- `engine` (String) The cache engine type (`redis` or `memcached`).
- `version` (String) The engine version.
- `node_type` (String) The instance type of the cache nodes.
- `num_nodes` (Number) Number of nodes in the cache cluster.
- `port` (Number) The port number for cache connections.
- `endpoint` (String) The primary endpoint for connecting to the cache.
- `reader_endpoint` (String) The reader endpoint for read replicas (Redis cluster mode only).
- `status` (String) Current operational status.
- `created_at` (String) Creation timestamp (RFC3339 format).
- `updated_at` (String) Last modification timestamp (RFC3339 format).

#### High Availability

- `multi_az_enabled` (Boolean) Whether multi-AZ is enabled.
- `automatic_failover_enabled` (Boolean) Whether automatic failover is enabled.

#### Backup Settings

- `backup_enabled` (Boolean) Whether automatic backups are enabled.
- `backup_retention_days` (Number) Number of days backups are retained.
- `backup_window` (String) Daily backup window (UTC).

#### Security

- `encryption_at_rest_enabled` (Boolean) Whether encryption at rest is enabled.
- `encryption_in_transit_enabled` (Boolean) Whether TLS is enabled.
- `vpc_id` (String) The ID of the VPC.
- `subnet_ids` (List of String) List of subnet IDs.
- `security_group_ids` (List of String) List of security group IDs.

#### Metadata

- `tags` (Map of String) Map of tags assigned to the cache.

Multiple Results

Using Plural Data Source

## Multiple Caches

To query multiple caches, use the `cachecloud_caches` (plural) data source:

```terraform
# List all Redis caches in production
data "cachecloud_caches" "redis_prod" {
  filter {
    name   = "engine"
    values = ["redis"]
  }
  
  tags = {
    Environment = "production"
  }
}

# Output all cache endpoints
output "cache_endpoints" {
  value = {
    for cache in data.cachecloud_caches.redis_prod.caches :
    cache.name => cache.endpoint
  }
}

Result Attributes

# Access individual cache attributes
locals {
  cache_ids = data.cachecloud_caches.redis_prod.caches[*].id
  
  cache_map = {
    for cache in data.cachecloud_caches.redis_prod.caches :
    cache.id => cache
  }
}

## Common Patterns

### Conditional Resources

```markdown
## Common Patterns

### Create Resource if Cache Exists

```terraform
data "cachecloud_cache" "existing" {
  count = var.use_existing_cache ? 1 : 0
  name  = var.cache_name
}

resource "cachecloud_cache" "new" {
  count     = var.use_existing_cache ? 0 : 1
  name      = var.cache_name
  engine    = "redis"
  node_type = "cache.t3.micro"
}

locals {
  cache_endpoint = var.use_existing_cache ? (
    data.cachecloud_cache.existing[0].endpoint
  ) : (
    cachecloud_cache.new[0].endpoint
  )
}

### Dynamic Configuration

```markdown
### Application Configuration from Cache

```terraform
data "cachecloud_cache" "app_cache" {
  name = var.cache_name
}

resource "aws_ssm_parameter" "config" {
  for_each = {
    endpoint = data.cachecloud_cache.app_cache.endpoint
    port     = data.cachecloud_cache.app_cache.port
    tls      = data.cachecloud_cache.app_cache.encryption_in_transit_enabled
  }
  
  name  = "/app/cache/${each.key}"
  type  = each.key == "tls" ? "String" : "SecureString"
  value = tostring(each.value)
}

### Validation

```markdown
### Validate Cache Configuration

```terraform
data "cachecloud_cache" "app_cache" {
  name = var.cache_name
}

# Ensure cache meets requirements
resource "null_resource" "validate_cache" {
  lifecycle {
    precondition {
      condition     = data.cachecloud_cache.app_cache.engine == "redis"
      error_message = "Cache must use Redis engine"
    }
    
    precondition {
      condition     = data.cachecloud_cache.app_cache.encryption_in_transit_enabled
      error_message = "Cache must have TLS enabled"
    }
    
    precondition {
      condition     = data.cachecloud_cache.app_cache.num_nodes >= 2
      error_message = "Cache must have at least 2 nodes for high availability"
    }
  }
}

## Error Handling

Document common errors and solutions:

```markdown
## Error Handling

### Multiple Matches

If multiple caches match the query:

Error: Multiple caches found matching criteria

Expected exactly one cache, but found 2:

cache-123456 (prod-api-cache)
cache-789012 (prod-web-cache)

Add more specific filters or use cachecloud_caches data source.

**Solution:** Add more specific filters or use the `cachecloud_caches` (plural) data source:

```terraform
# Use plural data source
data "cachecloud_caches" "prod" {
  tags = {
    Environment = "production"
  }
}

# Or add more specific filter
data "cachecloud_cache" "api" {
  tags = {
    Environment = "production"
    Application = "api"
  }
}

Cache Not Found

If no cache matches:

Error: Cache not found

No cache found matching: name = "my-cache"

Verify the cache exists and you have permission to access it.

Solution: Verify cache exists:

# Using CLI
cachecloud cache list --name my-cache

# Or use count for optional lookup
data "cachecloud_cache" "optional" {
  count = var.cache_exists ? 1 : 0
  name  = var.cache_name
}

## Best Practices

### 1. Specific Filters

```markdown
# ✅ Good: Specific query
data "cachecloud_cache" "specific" {
  name = "prod-api-cache"
}

# ❌ Bad: Broad query likely to match multiple
data "cachecloud_cache" "broad" {
  tags = {
    Environment = "production"
  }
}

2. Use Appropriate Data Source

# ✅ Good: Use singular for single cache
data "cachecloud_cache" "single" {
  id = var.cache_id
}

# ✅ Good: Use plural for multiple caches
data "cachecloud_caches" "multiple" {
  tags = {
    Environment = "production"
  }
}

# ❌ Bad: Using singular when multiple expected
data "cachecloud_cache" "wrong" {
  tags = {
    Environment = "production"
  }
}

3. Handle Optional Data Sources

# ✅ Good: Handle missing data source
data "cachecloud_cache" "optional" {
  count = var.use_existing ? 1 : 0
  name  = var.cache_name
}

locals {
  cache_id = var.use_existing ? (
    data.cachecloud_cache.optional[0].id
  ) : null
}

# ❌ Bad: Assume data source always exists
data "cachecloud_cache" "required" {
  name = var.cache_name # May not exist
}

resource "other_resource" "dependent" {
  cache_id = data.cachecloud_cache.required.id # Will fail if not found
}

Complete Documentation Example

---
page_title: "cachecloud_cache Data Source - CacheCloud"
subcategory: ""
description: |-
  Get information about a CacheCloud cache instance.
---

# cachecloud_cache (Data Source)

Use this data source to get information about an existing CacheCloud cache. The data source supports querying by name, ID, or tags.

~> **Note:** This data source returns a single cache. If multiple caches match the query, an error occurs. Use `cachecloud_caches` to query multiple caches.

## Example Usage

### Basic Query

```terraform
data "cachecloud_cache" "example" {
  name = "my-cache"
}

output "cache_endpoint" {
  value = data.cachecloud_cache.example.endpoint
}

Query with Tags

data "cachecloud_cache" "prod_api" {
  tags = {
    Environment = "production"
    Application = "api"
  }
}

Use in Application Configuration

data "cachecloud_cache" "session_cache" {
  name = "prod-session-cache"
}

resource "kubernetes_config_map" "app_config" {
  metadata {
    name = "app-config"
  }
  
  data = {
    CACHE_HOST = data.cachecloud_cache.session_cache.endpoint
    CACHE_PORT = tostring(data.cachecloud_cache.session_cache.port)
  }
}

Schema

Optional

id (String) The unique identifier of the cache. Conflicts with name.
name (String) The name of the cache. Conflicts with id.
tags (Map of String) Map of tags to filter caches.
filter (Block List) Custom filters. See Filter.

Read-Only

arn (String) The ARN of the cache.
engine (String) The cache engine (redis or memcached).
version (String) The engine version.
node_type (String) The instance type of cache nodes.
num_nodes (Number) Number of cache nodes.
port (Number) Connection port number.
endpoint (String) Primary connection endpoint.
reader_endpoint (String) Reader endpoint (Redis cluster only).
status (String) Current status.
vpc_id (String) VPC ID.
subnet_ids (List of String) Subnet IDs.
security_group_ids (List of String) Security group IDs.
encryption_at_rest_enabled (Boolean) Encryption at rest status.
encryption_in_transit_enabled (Boolean) TLS status.
backup_enabled (Boolean) Backup status.
created_at (String) Creation timestamp.
updated_at (String) Last update timestamp.

Filter

name (String) Field name to filter on.
values (List of String) Values to match. ```

Key Takeaways

✅ Explain what data can be queried
✅ Show multiple query methods (name, ID, tags)
✅ Document all filter options
✅ List all exported attributes
✅ Include common usage patterns
✅ Show integration with other resources
✅ Document error scenarios
✅ Distinguish singular vs plural data sources
✅ Handle optional data sources properly
✅ Provide complete, working examples

What’s Next?

Learn how to document provider configuration and authentication.

Next: Provider Configuration Docs →

Previous: ← Resource Documentation
Next: Provider Configuration Docs →

Last updated: June 30, 2026

Share on

Twitter Facebook LinkedIn

Data Source Documentation