# splunk/splunk-operator architecture

> Architecture diagram of the GitHub repository splunk/splunk-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/splunk/splunk-operator
- Repository: https://github.com/splunk/splunk-operator

## Overview

##### Project type and purpose
- This is a Kubernetes Operator (the “Splunk Operator”) built with the Operator SDK in Go.
- Its purpose is to manage Splunk Enterprise deployments on Kubernetes by defining Custom Resource Definitions (CRDs) and reconciling desired state (Clusters, Standalones, LicenseManagers, etc.) via controller loops.
- It bundles OLM manifests, Helm charts, integration tests (kuttl), client libraries for Splunk REST API, and end-to-end tests.

a. Kubernetes Control Plane
- API Server (CRD and built-in resource registry)
- etcd (state store)
b. Splunk Operator Pod
- Manager (main.go)
- Controller-runtime machinery
- Reconcilers (one per CR type) in internal/controller/*
- Shared libraries: pkg/splunk/common, pkg/splunk/client, pkg/splunk/enterprise logic
c. Splunk Enterprise Workloads
- StatefulSets/Deployments/Pods for Splunk Clustermanager, IndexerCluster, SearchHeadCluster, MonitoringConsole, Standalone
- Services, ConfigMaps, Secrets (generated by controllers)
d. External Storage and Services
- AWS S3 / Azure Blob / GCP Buckets (via pkg/splunk/client/* clients)
- Optional sidecars for metrics, debug
e. Operator Installation Artifacts
- CRD YAMLs (config/crd/bases)
- RBAC manifests (config/rbac)
- OLM bundle (bundle/manifests)
- Helm charts (helm-chart/)
f. CI/CD & Testing
- GitHub workflows (.github/workflows)
- KUTTL integration tests (kuttl/, config/scorecard/)
- Unit tests (internal/controller/*_test.go, pkg/**/*.go tests)

##### Interactions and dataflow
- Operator watches CRDs & built-in resources (ServiceAccount, RoleBinding, etc.) via controller-runtime → events feed into reconciliation loops
- Reconcilers call into pkg/splunk/enterprise to compute desired Kubernetes objects → operator issues create/update to API Server
- Operator uses pkg/splunk/client to reach out to Splunk REST API endpoints on Pods for configuration, scaling, upgrades, smartstore actions
- Controllers reconcile loop until actual cluster state matches desired CR spec
- KUTTL and integration tests drive CR application and assert expected Kubernetes and Splunk side effects

##### Architectural patterns & principles
- Operator Pattern: controller/event-driven reconciliation loop
- CRD-First design: custom types under api/v* drive all behavior
- Shared library layering:
- api/v*/ types → internal/controller → pkg/splunk/common & client → pkg/splunk/enterprise business logic
- Separation of concerns: controller orchestration vs. Splunk REST logic vs. K8s resource templating
- Test coverage: unit tests for every package, integration via kuttl, smoke tests, CI pipelines

##### Technologies & frameworks
- Go modules, Operator SDK, controller-runtime
- Kubernetes API machinery (CRDs, RBAC, Namespaces)
- Helm for packaging operator & Splunk charts
- OLM bundle for marketplace integration
- KUTTL testing framework for end-to-end
- Storage clients: AWS S3 SDK, Azure Blob SDK, GCP Storage client

##### Essential architectural elements
- CRD Registration & API Server (config/crd, api/v*)
- Operator Manager & Controllers (main.go + internal/controller)
- Shared libraries & clients (pkg/splunk/common, pkg/splunk/client)
- Splunk Enterprise resource managers (pkg/splunk/enterprise)
- Generated Kubernetes resources (StatefulSets, Services, ConfigMaps)
- External storage integration
- Packaging artifacts (Helm, OLM bundle)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer/CI"]:::external

    subgraph "Kubernetes Control Plane"
        APIS["API Server"] 
        ETCD["etcd"] 
    end

    subgraph "CRD Registration"
        CRDDefinitions["CRD Definitions & Registration"] 
        APIV3["api/v3 & api/v4 Go Types"]  
    end

    subgraph "Operator Pod"
        Manager["Operator Manager (main.go)"] 
        CRuntime["Controller-runtime Setup"] 
        Reconcilers["Reconcilers (internal/controller/*_controller.go)"] 
        SLCommon["Common Utilities"] 
        SLTemplating["K8s Templating Lib"] 
        SLEnterprise["Splunk Enterprise Logic"] 
        SClient["Remote Storage Clients"] 
    end

    subgraph "Splunk Enterprise Workloads"
        SEPods["StatefulSets/Deployments/Pods"] 
        K8sResources["Services/ConfigMaps/Secrets"] 
    end

    subgraph "External Storage & Services"
        Storage["AWS S3 / Azure Blob / GCP Buckets"] 
    end

    subgraph "Operator Installation Artifacts"
        Helm["Helm Charts"] 
        OLM["OLM Bundle"] 
    end

    subgraph "CI/CD & Testing"
        GH["GitHub Workflows"] 
        KUTTL["KUTTL Integration Tests"] 
        UnitControllerTests["Controller Unit Tests"] 
        UnitPkgTests["Package Unit Tests"] 
        E2E["End-to-End & App Framework Tests"] 
    end

    Developer -->|"kubectl apply CRD / Helm/OLM install"| APIS
    APIS -->|"store state"| ETCD
    APIS -->|"events"| Reconcilers
    Reconcilers -->|"Reconcile loop"| SLEnterprise
    SLEnterprise -->|"generate resources"| APIS
    SLEnterprise -->|"REST API calls"| SEPods
    SEPods -->|"manage K8s resources"| K8sResources
    SEPods -->|"S3/Blob/GCS client calls"| Storage

    GH --> CRDDefinitions
    GH --> Manager
    KUTTL --> APIS
    KUTTL --> SEPods
    UnitControllerTests --> Reconcilers
    UnitPkgTests --> SLCommon
    E2E --> SEPods

    click CRDDefinitions "https://github.com/splunk/splunk-operator/tree/main/config/crd/bases"
    click APIV3 "https://github.com/splunk/splunk-operator/tree/main/api/v3"
    click APIV3 "https://github.com/splunk/splunk-operator/tree/main/api/v4"
    click Manager "https://github.com/splunk/splunk-operator/blob/main/cmd/main.go"
    click CRuntime "https://github.com/splunk/splunk-operator/blob/main/config/manager/manager.yaml"
    click CRuntime "https://github.com/splunk/splunk-operator/blob/main/config/manager/controller_manager_config.yaml"
    click Reconcilers "https://github.com/splunk/splunk-operator/blob/main/internal/controller/clustermanager_controller.go"
    click Reconcilers "https://github.com/splunk/splunk-operator/blob/main/internal/controller/indexercluster_controller.go"
    click UnitControllerTests "https://github.com/splunk/splunk-operator/blob/main/internal/controller/clustermanager_controller_test.go"
    click UnitControllerTests "https://github.com/splunk/splunk-operator/blob/main/internal/controller/indexercluster_controller_test.go"
    click SLCommon "https://github.com/splunk/splunk-operator/tree/main/pkg/splunk/common"
    click SLTemplating "https://github.com/splunk/splunk-operator/tree/main/pkg/splunk/splkcontroller"
    click SLEnterprise "https://github.com/splunk/splunk-operator/tree/main/pkg/splunk/enterprise"
    click SClient "https://github.com/splunk/splunk-operator/blob/main/pkg/splunk/client/awss3client.go"
    click SClient "https://github.com/splunk/splunk-operator/blob/main/pkg/splunk/client/azureblobclient.go"
    click SClient "https://github.com/splunk/splunk-operator/blob/main/pkg/splunk/client/gcpbucketclient.go"
    click SClient "https://github.com/splunk/splunk-operator/blob/main/pkg/splunk/client/minioclient.go"
    click Helm "https://github.com/splunk/splunk-operator/tree/main/helm-chart/splunk-operator"
    click Helm "https://github.com/splunk/splunk-operator/tree/main/helm-chart/splunk-enterprise"
    click OLM "https://github.com/splunk/splunk-operator/tree/main/bundle/manifests"
    click OLM "https://github.com/splunk/splunk-operator/tree/main/bundle/metadata"
    click GH "https://github.com/splunk/splunk-operator/tree/main/.github/workflows/"
    click KUTTL "https://github.com/splunk/splunk-operator/tree/main/bundle/tests/scorecard/kuttl"
    click KUTTL "https://github.com/splunk/splunk-operator/tree/main/kuttl/"
    click UnitPkgTests "https://github.com/splunk/splunk-operator/blob/main/pkg/splunk/common/util_test.go"
    click E2E "https://github.com/splunk/splunk-operator/tree/main/test/custom_resource_crud"
    click E2E "https://github.com/splunk/splunk-operator/tree/main/test/delete_cr"

    classDef controlplane fill:#CCDDFF,stroke:#000
    classDef operator fill:#CCFFCC,stroke:#000
    classDef workloads fill:#FFE0B2,stroke:#000
    classDef external fill:#E0E0E0,stroke:#000
    classDef pack fill:#E1BEE7,stroke:#000
    classDef testing fill:#FFCDD2,stroke:#000

    class APIS,ETCD controlplane
    class CRDDefinitions,APIV3 operator
    class Manager,CRuntime,Reconcilers,SLCommon,SLTemplating,SLEnterprise,SClient operator
    class SEPods,K8sResources workloads
    class Storage external
    class Helm,OLM pack
    class GH,KUTTL,UnitControllerTests,UnitPkgTests,E2E testing
```
