telemetryflow/telemetryflow-operator repository overview

graph TB
    CR["TelemetryFlow CR<br/>(telemetryflow.id/v1alpha1)"]

    subgraph Controller["TelemetryFlow Operator"]
        REC["Reconciler<br/>(15 reconciliation steps)"]
    end

    subgraph Infra["Infrastructure"]
        PG["PostgreSQL<br/>StatefulSet"]
        CH["ClickHouse<br/>StatefulSet"]
        RD["Redis<br/>StatefulSet"]
        BRD["BullMQ Redis<br/>StatefulSet"]
        NT["NATS<br/>StatefulSet"]
    end

    subgraph Observability["Telemetry Pipeline"]
        COL["Collector<br/>Deployment + RBAC"]
        AGN["Agent Node<br/>DaemonSet"]
        AGK["Agent K8s<br/>Deployment"]
    end

    subgraph App["Application"]
        BE["Backend<br/>Deployment + HPA + Ingress"]
        VIZ["Frontend<br/>Deployment + Ingress"]
    end

    CR --> REC
    REC --> Infra
    REC --> Observability
    REC --> App

    AGN -.->|"OTLP"| COL
    AGK -.->|"OTLP"| COL
    COL -.->|"processed"| BE
    VIZ -.->|"API"| BE
    BE -.-> PG
    BE -.-> CH
    BE -.-> RD
    BE -.-> NT

    style CR fill:#fef3c7
    style Controller fill:#e0f2fe
    style Infra fill:#f3f4f6
    style Observability fill:#fff7ed
    style App fill:#d1fae5

graph LR
    S1["postgresql"] --> S2["clickhouse"]
    S2 --> S3["redis"]
    S3 --> S4["bullmq-redis"]
    S4 --> S5["nats"]
    S5 --> S6["collector-rbac"]
    S6 --> S7["collector"]
    S7 --> S8["agent-rbac"]
    S8 --> S9["agent-daemonset"]
    S9 --> S10["agent-k8s"]
    S10 --> S11["backend"]
    S11 --> S12["frontend"]
    S12 --> S13["backend-ingress"]
    S13 --> S14["frontend-ingress"]
    S14 --> S15["backend-hpa"]
    S15 --> SEC["secrets<br/>(optional)"]
    SEC --> READY["phase: Ready"]

    style READY fill:#d1fae5

# Install CRDs into your cluster (uses current kubeconfig)
make install

# Run the operator against the cluster
make run

# Build the image
make docker-build IMG=telemetryflow/telemetryflow-operator:1.5.0

# (Push to your registry if remote)
make docker-push IMG=telemetryflow/telemetryflow-operator:1.5.0

# Deploy the controller manager
make deploy IMG=telemetryflow/telemetryflow-operator:1.5.0

kubectl apply -f config/samples/telemetryflow_v1alpha1_telemetryflow.yaml

kubectl get telemetryflow -n telemetryflow -w
# NAME                    PHASE    READY   VERSION   AGE
# telemetryflow-sample    Ready    true    1.4.2     2m

kubectl describe telemetryflow telemetryflow-sample -n telemetryflow

# Delete the CR (triggers finalizer cleanup)
kubectl delete telemetryflow telemetryflow-sample -n telemetryflow

# Undeploy the operator
make undeploy

# Remove CRDs
make uninstall

apiVersion: telemetryflow.id/v1alpha1
kind: TelemetryFlow
metadata:
  name: telemetryflow-prod
  namespace: telemetryflow
spec:
  version: "1.5.0"

  backend:
    image: telemetryflow/tfo-backend:1.4.2
    replicas: 3
    resources:
      requests: { cpu: "1", memory: 1Gi }
      limits:   { cpu: "2", memory: 2Gi }
    autoscaling:
      enabled: true
      minReplicas: 3
      maxReplicas: 15
      targetCPUUtilizationPercentage: 65
    ingress:
      enabled: true
      className: nginx
      host: api.telemetryflow.id
      tls: true
      tlsSecretName: telemetryflow-api-tls
    scheduling:
      nodeSelector:
        eks.amazonaws.com/nodegroup: telemetryflow-production
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: DoNotSchedule

  agent:
    enabled: true
    image: telemetryflow/telemetryflow-agent:1.2.0
    node:
      enabled: true        # DaemonSet (per-node OS metrics)
    kubernetes:
      enabled: true        # Deployment (cluster-wide K8s state)

  postgresql:
    image: postgres:16-alpine
    persistence:
      enabled: true
      size: "50Gi"

  secrets:
    create: false          # use pre-provisioned secrets

operator/
├── main.go                              # Entrypoint (manager setup, flags, probes)
├── go.mod                               # Module: github.com/telemetryflow/telemetryflow-operator
├── Makefile                             # Build, test, lint, deploy, docker targets
├── Dockerfile                           # Multi-stage (golang:1.26-alpine → alpine:3.21)
├── PROJECT                              # Kubebuilder project metadata (v4 layout)
├── run-container.sh                     # Docker build/tag/push helper
│
├── api/v1alpha1/                        # CRD type definitions
│   ├── groupversion_info.go             # Group: telemetryflow.id, Version: v1alpha1
│   ├── telemetryflow_types.go           # TelemetryFlow spec/status types
│   └── zz_generated.deepcopy.go         # Generated DeepCopy methods
│
├── internal/controller/
│   └── telemetryflow_controller.go      # Reconciler (1470 lines, 15 steps + finalizer)
│
├── config/                              # Kustomize manifests
│   ├── crd/
│   │   ├── bases/                       # Generated CRD YAML
│   │   └── kustomization.yaml
│   ├── manager/
│   │   ├── manager.yaml                 # Controller Deployment (health probes, resources)
│   │   └── kustomization.yaml
│   ├── rbac/
│   │   ├── role.yaml                    # ClusterRole (scoped permissions)
│   │   ├── role_binding.yaml
│   │   └── service_account.yaml
│   └── samples/
│       └── telemetryflow_v1alpha1_telemetryflow.yaml  # Full example CR
│
└── tests/
    ├── unit/
    │   └── controller_test.go           # envtest unit tests (no real cluster)
    ├── e2e/
    │   ├── e2e_suite_test.go            # Suite setup (namespace, kubeconfig)
    │   ├── e2e_test.go                  # Full, minimal, delete, update scenarios
    │   ├── startup_test.go              # Startup verification
    │   ├── collection_test.go           # Telemetry collection tests
    │   ├── pipeline_test.go             # Pipeline verification
    │   ├── shutdown_test.go             # Shutdown verification
    │   ├── testdata/                    # Test fixtures
    │   └── README.md                    # E2E testing guide
    └── integration/                     # Integration tests (placeholder)

make help                # Show all available commands

# Build
make build               # Build operator binary (fmt + vet + manifests + generate)
make run                 # Build and run operator locally
make version             # Show version info
make info                # Show build configuration

# Code Generation
make manifests           # Generate CRD, RBAC manifests (controller-gen)
make generate            # Generate DeepCopy methods
make generate-manifests  # Generate all manifests and code

# Testing
make test                # Unit tests via envtest (K8s 1.31, no cluster needed)
make test-e2e            # E2E tests against a real cluster
make test-coverage       # Generate HTML coverage report

# Code Quality
make fmt                 # Format code (go fmt)
make fmt-check           # Check formatting (CI gate)
make vet                 # Run go vet
make staticcheck         # Run staticcheck v0.7.0
make lint                # Run golangci-lint v1.59.0
make lint-fix            # Run golangci-lint with auto-fix
make check               # fmt + vet + lint + test

# Dependencies
make deps                # Download and tidy modules
make tidy                # Tidy go modules
make verify              # Verify dependencies

# Deployment
make install             # Install CRDs into cluster
make uninstall           # Remove CRDs from cluster
make deploy              # Deploy controller manager (set IMG)
make undeploy            # Remove controller manager

# Docker
make docker-build        # Build image (set IMG)
make docker-push         # Push image (set IMG)
make docker-buildx       # Multi-platform build (arm64, amd64, s390x, ppc64le)
make docker-run          # Run the image interactively

# Misc
make clean               # Clean build artifacts and coverage files

make test                # Runs ./tests/unit/... with envtest (K8s 1.31)
make test-coverage       # Generates coverage.html and coverage-summary.txt

# Using kind
kind create cluster --name tfo-e2e
make install
make deploy IMG=telemetryflow/telemetryflow-operator:1.5.0
make test-e2e
kind delete cluster --name tfo-e2e

# Build
docker build -t telemetryflow/telemetryflow-operator:1.5.0 .

# Or use the helper script
./run-container.sh -b -t 1.5.0
./run-container.sh -c          # build, tag, and push

make check    # fmt + vet + lint + test