Skip to main content

​
CLAUDE.md - StreamNative Private Cloud Documentation

This file provides guidance to Claude Code (claude.ai/code) when working with StreamNative Private Cloud documentation.

​
Purpose

The private-cloud/ directory contains documentation for StreamNative Private Cloud - self-managed Kubernetes deployments of StreamNative platform that customers run in their own infrastructure.

​
Directory Structure

  • v1/: Documentation for Private Cloud version 1.x
  • v2/: Documentation for Private Cloud version 2.x

​
Source Code Repository Mappings

​
Version-Specific Deployments

​
Private Cloud v1 (Helm-based)

  • charts (source_code_refs/charts/): Helm charts for v1 deployments
    • Contains traditional Helm charts for Pulsar deployment
    • Key charts:
      • sn-platform/: Full-featured platform with all components
      • sn-platform-slim/: Lightweight platform without Vault
      • sn-console/: StreamNative Console UI
    • Includes configuration examples in examples/
    • Scripts for cluster management in scripts/

​
Private Cloud v2 (Operator-based)

  • private-cloud (source_code_refs/private-cloud/): v2 deployment resources
    • Operator-based deployment model
    • Key components:
      • charts/sn-operator/: StreamNative Operator Helm chart
      • crds/: All CRD definitions for v2 resources
      • quick-start/: Example configurations and deployments
      • security/: Authentication and authorization examples
      • protocols/: KSN, MoP, and REST proxy configurations
    • Includes Oxia metadata store examples in oxia/

​
Kubernetes Operators

  • sn-operator (source_code_refs/sn-operator/): StreamNative Operator source
    • Main operator for managing StreamNative platform on Kubernetes
    • Handles deployment of Pulsar clusters, Kafka Connect, PfSQL, Oxia, and more
    • Controllers in controllers/ directory
    • CRD definitions in config/crd/
    • Key controllers: pulsarcoordinator_controller.go, kafkaconnect_controller.go, oxiacluster_controller.go
  • pulsar-resources-operator (source_code_refs/pulsar-resources-operator/): Pulsar Resources Operator
    • Manages Pulsar resources (tenants, namespaces, topics, permissions)
    • Works alongside sn-operator for resource management
    • Documentation in docs/ directory covers each resource type
    • Controllers handle connections, service accounts, and Pulsar resources

​
Infrastructure as Code

  • terraform-provider-streamnative (source_code_refs/terraform-provider-streamnative/): Terraform Provider
    • Manages StreamNative Cloud resources via Terraform
    • Also used for Private Cloud service account and RBAC configuration
    • Resources in cloud/ directory
    • Examples in examples/ directory
  • terraform-managed-cloud (source_code_refs/terraform-managed-cloud/): Terraform Modules
    • Pre-built Terraform modules for common configurations
    • Examples for various cloud providers
    • Vendor access modules for support

​
Documentation Patterns

​
Version-Specific Documentation

Each version (v1, v2) typically includes:
  1. Overview: Architecture and concepts
  2. Installation: Deployment guides for different environments
  3. Configuration: Cluster and component configuration
  4. Operations: Day-2 operations, upgrades, monitoring
  5. Security: Authentication, authorization, encryption
  6. Troubleshooting: Common issues and solutions

​
Key Components to Document

  • StreamNative Operator: Core platform operator
  • Pulsar Resources Operator: Resource management
  • Pulsar Clusters: Broker, BookKeeper, ZooKeeper configuration
  • Kafka Connect: Managed Kafka Connect clusters
  • PfSQL: Pulsar Functions SQL runtime
  • Oxia: Metadata storage (replacing ZooKeeper)
  • Console: Management UI deployment
  • Monitoring: Prometheus, Grafana integration

​
SNIP References

Check source_code_refs/snip/proposals/ for design documents related to:
  • Operator features (SNIP-104, SNIP-118, SNIP-125)
  • Private Cloud architecture (SNIP-124)
  • Oxia deployment (SNIP-130)
  • Kafka Connect support (SNIP-130)

​
Common Tasks

​
Adding Operator Features

  1. Check sn-operator or pulsar-resources-operator for implementation
  2. Review controller logic and CRD definitions
  3. Document both CRD configuration and operational aspects
  4. Include examples from tests/ directories
  5. Reference design decisions from SNIP proposals

​
Documenting CRDs

  1. Extract CRD schema from operator source
  2. Document each field with descriptions and examples
  3. Show relationships between CRDs (e.g., PulsarCoordinator -> PulsarBroker)
  4. Include kubectl examples for common operations

​
Version Migration

  1. Document breaking changes between v1 and v2
  2. Provide migration guides and tools
  3. Highlight deprecated features
  4. Show compatibility matrices

​
Terraform Documentation

  1. Reference terraform provider documentation
  2. Include example configurations
  3. Document required permissions
  4. Show integration with cloud providers

​
Cross-References

  • Cloud docs for comparison with managed service
  • Tools docs for operator and CLI usage
  • Connect docs for connector deployment on Private Cloud
  • Release notes for version-specific changes

​
Important Considerations

  • Private Cloud requires deep Kubernetes knowledge
  • Security configuration is customer’s responsibility
  • Performance tuning depends on infrastructure
  • Multi-cluster and federation scenarios
  • Air-gapped installation requirements