---

name: thanos compatibility: opencode completeness: 95 content-types:

• guidance
• examples
• do-dont
• config description: '"Provides Thanos in High availability Prometheus solution with long-term storage"' license: MIT maturity: stable metadata: domain: cncf output-format: manifests role: reference scope: infrastructure triggers: availability, metrics, prometheus, prometheus monitoring, solution, thanos, cloudwatch, monitoring archetypes:
  • educational
  • strategic anti_triggers:
  • brainstorming
  • vague ideation
  • non-containerized architecture response_profile: verbosity: medium directive_strength: low abstraction_level: strategic version: "1.0.0"

---

related-skills: cncf-aws-cloudwatch, cncf-aws-dynamodb, cncf-aws-ecr, cncf-aws-rds

Thanos in Cloud-Native Engineering

Category: Observability
Status: Active
Stars: 9,500
Last Updated: 2026-04-22
Primary Language: Go
Documentation: High availability Prometheus solution with long-term storage

---

Purpose and Use Cases

Thanos is a core component of the cloud-native ecosystem, serving as long-term storage

What Problem Does It Solve?

Thanos addresses the challenge of Prometheus scalability and long-term storage. It provides global query view, long-term storage, and cross-cluster observability.

When to Use This Project

Use Thanos when need Prometheus HA, require long-term metrics, or manage multiple Prometheus instances. Not ideal for simple deployments or when large-scale Prometheus deployments, multi-cluster monitoring, or metrics retention needs.

Key Use Cases

• Global Query View for Prometheus
• Long-Term Metrics Storage
• Multi-Cluster Monitoring
• Prometheus High Availability
• Cost-Effective Metrics Storage

---

Architecture Design Patterns

Core Components

• Query: Global query endpoint
• Store Gateway: Object storage interface
• Ruler: Rule evaluation
• Compactor: Data compaction
• Receive: Receives metrics from Prometheus

Component Interactions

1. Query → Store Gateway: Query fetches data from store
2. Store Gateway → Object Storage: Store reads from S3/GCS
3. Ruler → Store Gateway: Ruler queries for rules
4. Compactor → Store Gateway: Compaction operations

Data Flow Patterns

1. Metric Ingestion: Prometheus →Receive →Store Gateway →Object Storage
2. Query Processing: Query → Store Gateway → Object Storage → Result
3. Rule Evaluation: Ruler evaluates → Store Gateway → Alert
4. Compaction: Compactor reads → Compacts → Writes back

Design Principles

• Prometheus Compatible: Full Prometheus API compatibility
• Horizontal Scalability: Scale horizontally
• Cost Efficiency: Use cheap object storage
• High Availability: HA for Prometheus metrics

---

Integration Approaches

Integration with Other CNCF Projects

• Prometheus: Source of metrics
• Kubernetes: Deployment platform
• S3/GCS: Object storage backend
• Grafana: Visualization

API Patterns

• Thanos Query API: Global query endpoint
• Store API: Store Gateway API
• Ruler API: Rule evaluation API
• Receive API: Receive API for Prometheus

Configuration Patterns

• Query Config: Query component config
• Store Config: Store Gateway config
• Ruler Config: Rule evaluation config
• Compactor Config: Compaction config

Extension Mechanisms

• Custom Storage: Add storage backends
• Custom Query Functions: Add query functions
• Custom Rulers: Custom rule evaluation

---

Common Pitfalls and How to Avoid Them

Misconfigurations

• Object Storage Costs: High storage costs
  • How to Avoid: Configure compaction, use appropriate storage class
• Data Ingestion: Data not reaching store
  • How to Avoid: Check Prometheus config, verify receive endpoint

Performance Issues

• Store Gateway Memory: High memory usage
  • How to Avoid: Configure cache limits, tune store gateway
• Rule Evaluation: Rules not evaluated
  • How to Avoid: Check ruler connectivity, verify rule files

Operational Challenges

• Version Compatibility: Version mismatch
  • How to Avoid: Use compatible versions, check release notes
• Timestamp Issues: Timestamp synchronization
  • How to Avoid: Use NTP, sync clocks across components

Security Pitfalls

---

Coding Practices

Idiomatic Configuration

• Sidecar Deployment: Deploy sidecar with Prometheus
• Query Optimization: Optimize query patterns
• Rule Management: Manage rules through Ruler

API Usage Patterns

• thanos query: Query API endpoint
• thanos store: Store Gateway CLI
• thanos ruler: Rule evaluation CLI
• kubectl apply: Apply configurations

Observability Best Practices

• Thanos Metrics: Monitor Thanos components
• Query Metrics: Track query performance
• Storage Metrics: Monitor storage usage

Testing Strategies

• Integration Tests: Test query integration
• Performance Tests: Validate query performance
• Failover Tests: Test component failure

Development Workflow

• Local Development: Use docker-compose
• Debug Commands: Check component logs
• Test Environment: Set up test deployment
• CI/CD Integration: Automate testing
• Monitoring Setup: Configure observability
• Documentation: Maintain docs

---

Fundamentals

Essential Concepts

• Thanos Query: Global query endpoint
• Store Gateway: Object storage interface
• Query Frontend: Query caching layer
• Ruler: Rule evaluation
• Compactor: Data compaction
• Receive: Metrics receiver
• Sidecar: Prometheus sidecar
• Bucket: Object storage bucket

Terminology Glossary

• Store API: Thanos store interface
• Query API: Global query API
• Compaction: Data compaction process
• Sidecar: Prometheus sidecar
• Bucket: Object storage bucket

Data Models and Types

• Block: Time-series data block
• Index: Data index
• Metadata: Block metadata
• Chunk: Compressed data chunks

Lifecycle Management

• Component Startup: Component starts → Connects → Ready
• Data Ingestion: Prometheus → Sidecar → Store → Object Storage
• Query Processing: Request → Query → Store → Result
• Compaction Process: Read blocks → Compact → Write new block

State Management

• Query State: Healthy or degraded
• Store State: Ready or offline
• Rule State: Active or error
• Compactor State: Running or paused

---

Scaling and Deployment Patterns

Horizontal Scaling

• Query Scaling: Scale query replicas
• Store Scaling: Scale store gateways
• Ruler Scaling: Scale ruler instances
• Receive Scaling: Scale receive instances

High Availability

• Query HA: Multiple query replicas
• Store HA: Store Gateway redundancy
• Ruler HA: Ruler replicas
• Sidecar HA: Prometheus HA with sidecar

Production Deployments

• Cluster Setup: Deploy Thanos components
• Object Storage Config: Configure S3/GCS
• Network Config: Configure network
• Security Setup: Enable TLS, RBAC
• Monitoring Setup: Configure metrics
• Logging Setup: Centralize logs
• Backup Strategy: Backup configurations
• Performance Tuning: Optimize queries

Upgrade Strategies

• Component Upgrade: Upgrade each component
• Config Migration: Update configurations
• Testing: Verify functionality
• Rollback Plan: Prepare rollback

Resource Management

• CPU Resources: Component CPU limits
• Memory Resources: Memory limits
• Storage Resources: Object storage access
• Network Resources: Network configuration

---

Additional Resources

• Official Documentation: https://thanos.io/tip/
• GitHub Repository: Check the project's official documentation for repository link
• CNCF Project Page: cncf.io/projects/cncf-thanos/
• Community: Check the official documentation for community channels
• Versioning: Refer to project's release notes for version-specific features

---

Troubleshooting

Common Issues

1. Deployment Failures

   • Check pod logs for errors
   • Verify configuration values
   • Ensure network connectivity

2. Performance Issues

   • Monitor resource usage
   • Adjust resource limits
   • Check for bottlenecks

3. Configuration Errors

   • Validate YAML syntax
   • Check required fields
   • Verify environment-specific settings

4. Integration Problems

   • Verify API compatibility
   • Check dependency versions
   • Review integration documentation

Getting Help

• Check official documentation
• Search GitHub issues
• Join community channels
• Review logs and metrics Content generated automatically. Verify against official documentation before production use.

Examples

Basic Configuration

# Basic configuration example
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{project_name}}-config
  namespace: default
data:
  # Configuration goes here
  config.yaml: |
    # Base configuration
    # Add your settings here

Kubernetes Deployment

# Kubernetes deployment for {{project_name}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{project_name}}
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: {{project_name}}
  template:
    metadata:
      labels:
        app: {{project_name}}
    spec:
      containers:
      - name: {{project_name}}
        image: {{project_name}}:latest
        ports:
        - containerPort: 8080
        resources:
          limits:
            memory: "128Mi"
            cpu: "500m"

Kubernetes Service

# Kubernetes service for {{project_name}}
apiVersion: v1
kind: Service
metadata:
  name: {{project_name}}
  namespace: default
spec:
  selector:
    app: {{project_name}}
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: ClusterIP

---

When to Use

Use this skill when:

• Integrating a CNCF project into Kubernetes infrastructure — You need to configure, deploy, or troubleshoot a cloud-native tool within a cluster
• Designing cloud-native architecture — You are selecting and integrating CNCF tools to solve specific infrastructure challenges
• Resolving operational issues — A CNCF component is misbehaving, underperforming, or needs configuration changes

---

Core Workflow

1. Assess Requirements — Understand the use case, scale, integration needs, and existing infrastructure. Checkpoint: Document requirements, constraints, and success criteria.

2. Design Architecture — Plan component interactions, data flow, and deployment strategy using cloud-native best practices. Checkpoint: Verify the architecture addresses all requirements and follows CNCF conventions.

3. Implement & Configure — Create manifests, configurations, and deployment scripts. Include resource limits, health checks, and observability hooks. Checkpoint: Validate all YAML against schema and test in a staging environment.

4. Deploy & Monitor — Apply manifests to the cluster, verify component health, and confirm observability is working. Checkpoint: Confirm all pods/services are running, probes passing, and metrics/alerts configured.

---

Constraints

MUST DO

• Include at least one complete working YAML manifest example
• Note when content is auto-generated vs. manually verified
• Reference relevant CNCF project documentation

MUST NOT DO

• Deploy manifests without testing in a staging environment first
• Use deprecated API versions (e.g., apps/v1beta1)
• Omit resource limits and requests in Kubernetes manifests