​

CLAUDE.md - StreamNative Tools Documentation

​

Purpose

​

Directory Structure

• cli/: Command-line interface documentation
  • snctl - StreamNative CLI for cloud management
  • pulsarctl - Pulsar administration CLI
• operator/: Kubernetes operator documentation
• terraform/: Terraform provider documentation

​

Source Code Repository Mappings

​

CLI Tools

• cloud-cli (source_code_refs/cloud-cli/): snctl - StreamNative CLI
  • Go-based CLI for StreamNative Cloud management
  • Key directories:
    • cmd/: Command implementations
    • pkg/: Core functionality and API clients
    • docs/: Auto-generated command documentation
  • Installation script: install.sh
  • Note: Reference docs synced from sn-doc-references repo

​

Kubernetes Operators

• sn-operator (source_code_refs/sn-operator/): StreamNative Operator
  • Main operator for StreamNative platform on Kubernetes
  • Controllers for various components:
    • PulsarCoordinator: Orchestrates Pulsar clusters
    • KafkaConnect: Manages Kafka Connect clusters
    • OxiaCluster: Manages Oxia metadata stores
    • PfSQLCluster: Manages PfSQL compute clusters
  • CRD definitions in config/crd/
• pulsar-resources-operator (source_code_refs/pulsar-resources-operator/): Resource management
  • Manages Pulsar resources declaratively
  • Resources: tenants, namespaces, topics, permissions
  • Service accounts and bindings
  • Connection management

​

Infrastructure as Code

• terraform-provider-pulsar (source_code_refs/terraform-provider-pulsar/): Pulsar provider
  • Manages Pulsar resources via Terraform
  • Resources: clusters, tenants, namespaces, topics, functions
  • Works with both cloud and self-hosted Pulsar
  • Examples in examples/ directory
• terraform-provider-streamnative (source_code_refs/terraform-provider-streamnative/): StreamNative provider
  • Manages StreamNative Cloud resources
  • Resources: instances, clusters, service accounts, API keys
  • Cloud-specific features: cloud connections, environments
  • Data sources for querying existing resources
• terraform-managed-cloud (source_code_refs/terraform-managed-cloud/): Terraform modules
  • Pre-built modules for common scenarios
  • Vendor access configurations
  • Best practice examples

​

Documentation Patterns

​

CLI Documentation

1. Overview: Purpose and capabilities
2. Installation: Multiple installation methods
3. Authentication: Login and credential management
4. Command Reference: Auto-generated from source
5. Examples: Common workflows and use cases
6. Configuration: Config file and environment variables

​

Operator Documentation

1. Architecture: How operators work
2. Installation: Helm charts, manifests, OLM
3. CRD Reference: Resource specifications
4. Configuration: Operator and resource configuration
5. Operations: Upgrades, monitoring, troubleshooting
6. Examples: Sample deployments

​

Terraform Documentation

1. Provider Setup: Authentication and configuration
2. Resource Reference: All managed resources
3. Data Sources: Querying existing resources
4. Examples: Complete configurations
5. Migration: From manual to IaC
6. Best Practices: State management, modules

​

SNIP References

• Operator improvements (SNIP-104, SNIP-118, SNIP-125)
• CLI enhancements (related to cloud features)
• Resource management (SNIP-108 for RBAC)
• Private cloud tooling (SNIP-124)

​

Common Tasks

​

Adding CLI Commands

1. Check cloud-cli/cmd/ for command structure
2. Document command syntax and flags
3. Include practical examples
4. Show output formats (JSON, table, etc.)
5. Cover error cases and troubleshooting

​

Documenting Operators

1. CRD Documentation:
   • Extract schema from operator source
   • Document each field with examples
   • Show field relationships and dependencies
   • Include validation rules
2. Operational Guides:
   • Installation procedures
   • Upgrade strategies
   • Backup and recovery
   • Performance tuning
   • Multi-cluster scenarios

​

Terraform Provider Updates

1. Document new resources or data sources
2. Show complete configuration examples
3. Explain state management implications
4. Include import procedures for existing resources
5. Document breaking changes and migrations

​

Important Workflows

​

Cloud Management (snctl)

• Organization and user management
• Instance and cluster lifecycle
• Service account and API key management
• Monitoring and troubleshooting
• Cost management and billing

​

Pulsar Administration (pulsarctl)

• Cluster health checks
• Topic and namespace management
• Security configuration
• Performance tuning
• Data migration

​

GitOps with Operators

• Declarative resource management
• CI/CD integration
• Multi-environment deployments
• Configuration drift detection
• Disaster recovery

​

Infrastructure as Code

• Environment provisioning
• Configuration management
• Compliance and governance
• Cost optimization
• Multi-cloud deployments

​

Cross-References

• Cloud docs for snctl cloud features
• Private Cloud docs for operator deployment
• Connect docs for connector management via CLI
• API docs for understanding CLI operations

​

Tool Integration Points

• snctl + Terraform: Provisioning and configuration
• Operators + GitOps: Declarative deployments
• pulsarctl + Monitoring: Operational visibility
• All tools + CI/CD: Automation workflows

​

Best Practices Documentation

1. Security: Credential management, RBAC, secrets
2. Automation: Scripts, pipelines, GitOps
3. Monitoring: Metrics, logs, alerts
4. Disaster Recovery: Backups, failover, restoration
5. Performance: Optimization, scaling, tuning