# aerospike/aerospike-kubernetes-operator architecture

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

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

## Overview

##### Project type and purpose
- This is a Kubernetes Operator (written in Go) for managing Aerospike Enterprise clusters.
- It extends the Kubernetes API via CRDs (aerospikeclusters, aerospikebackups, aerospikebackupservices, aerospikerestores), and implements a controller-reconciler loop plus webhooks to automate lifecycle tasks: deploy, scale, upgrade, backup/restore, monitoring, security, rack/zonal placement.

##### File structure
- Top-level code:
- cmd/main.go – entry point for the operator (controller-manager).
- api/v1 & api/v1beta1 – Go types defining CRD schemas.
- internal/controller – reconcilers for cluster, backup, restore, backup-service.
- internal/webhook – mutating & validating webhooks for CR validation and defaulting.
- config/… – kustomize manifests: CRDs, RBAC, cluster-service-version, sample CRs, webhook, cert-manager, monitoring, network policies.
- helm-charts/… – Helm charts for operator and CRs.
- test/… – end-to-end and unit tests, test scripts.
- Dockerfile, Jenkinsfile, GitHub workflows – CI/CD pipelines for build, lint, security scans, release.

##### README for additional insights
- Operator deploys as a Kubernetes StatefulSet (headless service) to maintain stable network identities.
- Layered orchestration: Operator manages Kubernetes primitives (StatefulSets, Services, ConfigMaps, PVCs, PodDisruptionBudgets) to drive Aerospike pods.
- Integrates with cert-manager for webhook certificates, OLM for installation, Prometheus/Grafana/Alertmanager for monitoring, and Helm for packaging.

##### Main components and their interactions
a. Kubernetes Cluster
- API Server + etcd – stores CRDs and CR instances.
- cert-manager – issues TLS certs for webhooks.
- Monitoring stack – Prometheus scrapes metrics, Grafana dashboards, Alertmanager.
b. Operator (Controller Manager)
- StatefulSet headless service exposing metrics endpoint & webhook server.
- Controllers (Reconciliation loops)
– Cluster controller: manages aerospikecluster CRs → creates/updates StatefulSets, Services, ConfigMaps, PVCs, PodDisruptionBudgets, Secrets.
– Backup/Restore controllers: manage backup and restore CRs → trigger jobs, manage storage, coordinate with Aerospike.
– Backup-Service controller: manages backup-service CR for on-demand backups via HTTP API.
- Webhooks
– Mutating webhook: defaults missing fields, injects sidecars or annotations.
– Validating webhook: enforces schema, cross-field validation, rack/zone placement rules.
- CRDs – definitions under config/crd/bases; installed by Kustomize or Helm.
c. Aerospike Cluster (Pods)
- StatefulSet of N pods running Aerospike server.
- Mounted PVCs for persistent storage (SSD, PMEM, file).
- Optionally sidecar containers for backup or metrics.
d. Helm and OLM
- Helm charts for operator and CRs.
- OLM bundle for catalog and subscription management.
e. CI/CD & Testing
- Docker image build, multi-arch builds via buildx.
- GitHub Actions + Jenkins pipelines for linting, security (Snyk, CodeQL), release.
- Automated tests that spin up test clusters, deploy operator and sample CRs.

##### Architectural patterns and design principles
- Controller pattern / reconciliation loop – desired vs. actual state.
- Kubernetes operator best practices – CustomResourceDefinitions, RBAC, leader election, metrics.
- Layered orchestration: separate concerns for cluster management vs. backup vs. restore.
- Webhook-driven validation/defaulting.
- Declarative config via Kustomize and Helm.
- Extensibility via Go interfaces, pkg/utils, pkg/merge, pkg/validation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% DevOps Layer
    subgraph "DevOps & CI/CD"
        direction TB
        CICD["CI/CD Pipelines"]:::devops
        Docker["Dockerfile & Makefile"]:::devops
        Jenkins["Jenkinsfile"]:::devops
        Test["Tests & Scripts"]:::devops
    end

    %% Installation Layer
    subgraph "Installation"
        direction TB
        Helm["Helm Charts & OLM"]:::install
    end

    %% Kubernetes Core
    subgraph "Kubernetes Cluster"
        direction TB
        APIServer["API Server"]:::core
        Etcd(("etcd")):::storage
        CertManager(["cert-manager"]):::external
        CRDs["CRD Definitions"]:::crd
    end

    %% Operator Layer
    subgraph "Aerospike Operator"
        direction TB
        OperatorSS["Operator StatefulSet"]:::operator
        subgraph Controllers
            direction TB
            ClusterCtrl["Cluster Controller"]:::controller
            BackupCtrl["Backup Controller"]:::controller
            RestoreCtrl["Restore Controller"]:::controller
            BackupSvcCtrl["Backup-Service Controller"]:::controller
        end
        subgraph Webhooks
            direction TB
            Mutating["Mutating Webhook"]:::webhook
            Validating["Validating Webhook"]:::webhook
        end
        Metrics["Metrics Endpoint & Leader Election"]:::operator
    end

    %% Data Layer
    subgraph "Aerospike Cluster"
        direction TB
        AStateful["Aerospike StatefulSet"]:::app
        PVC(("Persistent Volumes (PVC)")):::storage
    end

    %% Monitoring Layer
    subgraph "Monitoring & Observability"
        direction TB
        Prometheus["Prometheus"]:::monitor
        Grafana["Grafana"]:::monitor
        Alertmgr["Alertmanager"]:::monitor
    end

    %% Connections
    CICD -->|build/deploy| Helm
    Helm -->|install CRDs| CRDs
    CRDs --> APIServer
    APIServer -->|watch CRs| OperatorSS
    Etcd --> APIServer
    CertManager -->|provide certs| Webhooks
    OperatorSS -->|runs| Controllers
    OperatorSS -->|runs| Webhooks
    Controllers -->|reconcile| APIServer
    Controllers -->|manage| AStateful
    Controllers -->|create| PVC
    AStateful -->|expose metrics| Prometheus
    Prometheus -->|visualize| Grafana
    Prometheus -->|alert rules| Alertmgr

    %% Click Events
    click CICD "https://github.com/aerospike/aerospike-kubernetes-operator/tree/master/.github/workflows"
    click Docker "https://github.com/aerospike/aerospike-kubernetes-operator/tree/master/Dockerfile"
    click Jenkins "https://github.com/aerospike/aerospike-kubernetes-operator/tree/master/Jenkinsfile"
    click Test "https://github.com/aerospike/aerospike-kubernetes-operator/tree/master/test"
    click Helm "https://github.com/aerospike/aerospike-kubernetes-operator/tree/master/helm-charts"
    click CRDs "https://github.com/aerospike/aerospike-kubernetes-operator/tree/master/config"
    click ClusterCtrl "https://github.com/aerospike/aerospike-kubernetes-operator/tree/master/internal/controller/cluster"
    click BackupCtrl "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/internal/controller/backup/reconciler.go"
    click RestoreCtrl "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/internal/controller/restore/reconciler.go"
    click BackupSvcCtrl "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/internal/controller/backup-service/reconciler.go"
    click Mutating "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/internal/webhook/v1/aerospikecluster_mutating_webhook.go"
    click Validating "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/internal/webhook/v1/aerospikecluster_validating_webhook.go"
    click ClusterCtrl "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/internal/controller/cluster/reconciler.go"
    click APIServer "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/cmd/main.go"
    click CRDs "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/api/v1/aerospikecluster_types.go"
    click CRDs "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/api/v1/access_control_validate.go"
    click CRDs "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/api/v1/aerospikeconfig.go"
    click CRDs "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/api/v1beta1/aerospikebackup_types.go"
    click CRDs "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/api/v1beta1/aerospikebackupservice_types.go"
    click CRDs "https://github.com/aerospike/aerospike-kubernetes-operator/blob/master/api/v1beta1/aerospikerestore_types.go"

    %% Styles
    classDef core fill:#DDEEFF,stroke:#0088CC,stroke-width:2px
    classDef storage fill:#EEFFDD,stroke:#33AA00,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:2px,stroke-dasharray: 5 5
    classDef crd fill:#FFF8DC,stroke:#DAA520,stroke-width:2px
    classDef operator fill:#FFE4E1,stroke:#FF69B4,stroke-width:2px
    classDef controller fill:#FFB6C1,stroke:#DB7093,stroke-width:2px
    classDef webhook fill:#FFF0F5,stroke:#C71585,stroke-width:2px
    classDef app fill:#E6E6FA,stroke:#9370DB,stroke-width:2px
    classDef monitor fill:#E0FFFF,stroke:#20B2AA,stroke-width:2px
    classDef install fill:#FAFAD2,stroke:#DAA520,stroke-width:2px
    classDef devops fill:#F5F5F5,stroke:#A9A9A9,stroke-width:2px
```
