# opensearch-project/helm-charts architecture

> Architecture diagram of the GitHub repository opensearch-project/helm-charts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opensearch-project/helm-charts
- Repository: https://github.com/opensearch-project/helm-charts

## Overview

##### Project Type and Purpose
- This is an open-source repository of Helm charts for deploying the OpenSearch stack (OpenSearch core, OpenSearch Dashboards, Data Prepper) on Kubernetes.
- It’s not an application per se but a packaging/templating layer (Helm) that codifies Kubernetes manifests and CI/CD pipelines for chart linting, testing, and release.

##### Main Components
A. Source & CI/CD
- GitHub Repository (helm-charts)
- Developer (pushes commits/PRs)
- GitHub Actions workflows:
- lint-test.yaml (chart linting & basic validation)
- release.yaml (package and publish charts)
- chart-releaser (publishes to gh-pages)
B. Chart Artifacts & Registry
- GitHub Pages branch (gh-pages) hosting `index.yaml` and chart tarballs
- Helm repository endpoint: https://opensearch-project.github.io/helm-charts/
C. Consumers
- End users or automation pipelines running `helm repo add` & `helm install`
D. Kubernetes Cluster
- Kubernetes API Server
- Worker nodes running pods for:
- OpenSearch (StatefulSet, Services, ConfigMaps, PVCs)
- OpenSearch Dashboards (Deployment, Service, Ingress)
- Data Prepper (Deployment, ConfigMap, Service)
- Supporting Kubernetes primitives: Secrets, Ingress, HPA, PodDisruptionBudget, NetworkPolicy, ServiceAccount, RBAC

##### Relationships & Data/Control Flows
- Developer → push code → GitHub repo
- GitHub Actions (on push/PR) executes lint/test → upon tag or release event runs packaging
- Chart-Releaser uploads packaged `.tgz` + updates `index.yaml` in gh-pages branch
- End user `helm repo update` pulls index from gh-pages
- `helm install` fetches chart → renders templates → sends Kubernetes manifests to API server
- API server schedules pods on worker nodes → pods pull Docker images (OpenSearch, Dashboards, Data Prepper) from container registry

##### Architectural Patterns & Design Principles
- GitOps-style chart management: declarative manifests stored in Git and published via CI to a versioned Helm repo
- Chart templating: reusable parameterized YAML templates under `charts/<chart>/templates`
- Separation of concerns: three distinct charts targeting different layers of the search pipeline
- Kubernetes best practices: use of StatefulSet for OpenSearch, Deployments for stateless components, RBAC, network policies, health checks

##### Key Technologies & Frameworks
- Helm (Chart.yaml, values.yaml, templates)
- Kubernetes primitives (StatefulSet, Deployment, Service, Ingress, ConfigMap, Secret, PVC, ServiceAccount, RBAC)
- GitHub Actions for CI/CD
- Chart-Releaser (automates publishing to GitHub Pages)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Git Source & CI/CD
    subgraph "GitHub Repository" 
        direction TB
        Repo["helm-charts"]:::github
        GitFolder[".github/"]:::github
        Repo --> GitFolder
        LintTest["lint-test.yaml"]:::cicd
        Release["release.yaml"]:::cicd
        GitFolder --> LintTest
        GitFolder --> Release
    end

    Developer["Developer"]:::actor
    Developer -->|"push commits/PRs"| Repo

    subgraph "CI/CD Worker (GitHub Actions)"
        direction TB
        LintTest
        Release
        ChartReleaser["chart-releaser step"]:::cicd
        Release -->|"on release/tag"| ChartReleaser
    end

    Repo -->|"Workflow triggers"| LintTest
    Repo -->|"Workflow triggers"| Release

    %% Chart Artifacts & Registry
    subgraph "Helm Chart Registry (gh-pages)"
        direction TB
        Index["index.yaml"]:::helm
        Tarballs[".tgz packages"]:::helm
    end

    ChartReleaser -->|"push charts & update index"| Index
    ChartReleaser --> Tarballs

    %% Consumers
    EndUser["End User (Helm CLI)"]:::actor
    EndUser -->|"helm repo add && helm repo update"| Index
    EndUser -->|"helm install"| ChartsFetch

    ChartsFetch["Fetch charts from registry"]:::helm
    ChartsFetch -->|"renders templates"| KubernetesAPI

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster" 
        direction TB
        KubernetesAPI["API Server"]:::k8s
        subgraph "Worker Nodes"
            direction TB
            subgraph "OpenSearch Pod" 
                OSStateful["StatefulSet"]:::pods
                OSService["Service"]:::pods
                OSConfig["ConfigMap"]:::pods
                OSPVC["PVC"]:::pods
                OSNetwork["NetworkPolicy"]:::pods
                OSRole["RBAC (Role & Binding)"]:::pods
                OSStateful --> OSService
                OSStateful --> OSConfig
                OSStateful --> OSPVC
                OSStateful --> OSNetwork
                OSStateful --> OSRole
            end
            subgraph "Dashboards Pod" 
                DashDeployment["Deployment"]:::pods
                DashService["Service"]:::pods
                DashIngress["Ingress"]:::pods
                DashHPA["HPA"]:::pods
                DashMonitor["ServiceMonitor"]:::pods
                DashRBAC["RBAC"]:::pods
                DashDeployment --> DashService
                DashDeployment --> DashIngress
                DashDeployment --> DashHPA
                DashDeployment --> DashMonitor
                DashDeployment --> DashRBAC
            end
            subgraph "Data Prepper Pod" 
                DPDeployment["Deployment"]:::pods
                DPService["Service"]:::pods
                DPConfig["ConfigMap"]:::pods
                DPSecret["Secret"]:::pods
                DPIngress["Ingress"]:::pods
                DPHPA["HPA"]:::pods
                DPServiceAcc["ServiceAccount"]:::pods
                DPDeployment --> DPService
                DPDeployment --> DPConfig
                DPDeployment --> DPSecret
                DPDeployment --> DPIngress
                DPDeployment --> DPHPA
                DPDeployment --> DPServiceAcc
            end
        end
        ChartsFetch --> KubernetesAPI
        KubernetesAPI -->|"schedules pods"| OSStateful
        KubernetesAPI --> DashDeployment
        KubernetesAPI --> DPDeployment
        OSStateful -->|"pull images"| ContainerRegistry
        DashDeployment -->|"pull images"| ContainerRegistry
        DPDeployment -->|"pull images"| ContainerRegistry
    end

    ContainerRegistry["Container Registry"]:::external

    %% Click Events for component mapping
    click GitFolder "https://github.com/opensearch-project/helm-charts/tree/main/.github/"
    click LintTest "https://github.com/opensearch-project/helm-charts/blob/main/.github/workflows/lint-test.yaml"
    click Release "https://github.com/opensearch-project/helm-charts/blob/main/.github/workflows/release.yaml"
    click ChartsFetch "https://github.com/opensearch-project/helm-charts/tree/main/charts/"
    click OSStateful "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/statefulset.yaml"
    click OSService "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/service.yaml"
    click OSConfig "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/configmap.yaml"
    click OSNetwork "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/networkpolicy.yaml"
    click OSRole "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/role.yaml"
    click OSRole "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/rolebinding.yaml"
    click OSStateful "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/Chart.yaml"
    click OSStateful "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/values.yaml"
    click OSStateful "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/poddisruptionbudget.yaml"
    click OSStateful "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/serviceaccount.yaml"
    click OSStateful "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch/templates/podsecuritypolicy.yaml"
    click DashDeployment "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch-dashboards/templates/deployment.yaml"
    click DashService "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch-dashboards/templates/service.yaml"
    click DashIngress "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch-dashboards/templates/ingress.yaml"
    click DashHPA "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch-dashboards/templates/autoscaler.yaml"
    click DashMonitor "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch-dashboards/templates/serviceMonitor.yaml"
    click DashRBAC "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch-dashboards/templates/rolebinding.yaml"
    click DashServiceAcc "https://github.com/opensearch-project/helm-charts/blob/main/charts/opensearch-dashboards/templates/serviceaccount.yaml"
    click DPDeployment "https://github.com/opensearch-project/helm-charts/blob/main/charts/data-prepper/templates/deployment.yaml"
    click DPService "https://github.com/opensearch-project/helm-charts/blob/main/charts/data-prepper/templates/service.yaml"
    click DPConfig "https://github.com/opensearch-project/helm-charts/blob/main/charts/data-prepper/templates/configmap.yaml"
    click DPSecret "https://github.com/opensearch-project/helm-charts/blob/main/charts/data-prepper/templates/secret.yaml"
    click DPIngress "https://github.com/opensearch-project/helm-charts/blob/main/charts/data-prepper/templates/ingress.yaml"
    click DPHPA "https://github.com/opensearch-project/helm-charts/blob/main/charts/data-prepper/templates/hpa.yaml"
    click DPServiceAcc "https://github.com/opensearch-project/helm-charts/blob/main/charts/data-prepper/templates/serviceaccount.yaml"

    %% Styles
    classDef github fill:#cce5ff,stroke:#004085
    classDef cicd fill:#ffe5b4,stroke:#b35405
    classDef helm fill:#e5ccff,stroke:#660099
    classDef k8s fill:#d4edda,stroke:#155724
    classDef pods fill:#fff3cd,stroke:#856404
    classDef external fill:#f8f9fa,stroke:#6c757d
    classDef actor fill:#ffffff,stroke:#000000,stroke-dasharray: 2 2
```
