# opensearch-project/opensearch-k8s-operator architecture

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

- Interactive diagram: https://gitdiagram.com/opensearch-project/opensearch-k8s-operator
- Repository: https://github.com/opensearch-project/opensearch-k8s-operator

## Overview

The OpenSearch Kubernetes Operator turns Kubernetes custom resources into managed OpenSearch clusters, Dashboards, and in-cluster configuration. Users submit resources; admission validation and controllers reconcile them into Kubernetes workloads and OpenSearch API changes. The README documents scaling, upgrades, TLS, plugins, and multi-namespace management; the tree identifies corresponding runtime modules. Source excerpts establish key controller, builder, Kubernetes-client, migration, and gateway relationships, but many feature reconcilers were not sampled, so their internal call paths are not asserted.

Main entry points: [`opensearch-operator/controllers/opensearchController.go`](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/controllers/opensearchController.go) (Cluster Controller), [`opensearch-operator/opensearch-gateway/services/os_client.go`](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/opensearch-gateway/services/os_client.go) (OpenSearch Client), [`opensearch-operator/api/opensearch.org/v1/opensearchism_types.go`](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/api/opensearch.org/v1/opensearchism_types.go) (Config Resources), [`opensearch-operator/api/opensearch.org/v1/opensearch_types.go`](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/api/opensearch.org/v1/opensearch_types.go) (OpenSearch Resources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Custom Resource API"]
  node_custom_resources["OpenSearch Resources"]
  node_config_resources["Config Resources"]
end

subgraph group_control["Operator Control Plane"]
  node_admission["Admission Validation"]
  node_runtime["Manager Runtime<br/>[main.go]"]
  node_cluster_controller["Cluster Controller"]
  node_migration["API Migration"]
  node_resource_engine["Resource Reconciler<br/>[resource.go]"]
  node_k8s_client["Kubernetes Client<br/>[client.go]"]
end

subgraph group_cluster["Cluster Lifecycle"]
  node_cluster_builder["Cluster Builder<br/>[cluster.go]"]
  node_dashboards_builder["Dashboards Builder<br/>[dashboards.go]"]
  node_cluster_features["Scaling and Upgrades"]
  node_tls["Certificate Management<br/>[pki.go]"]
end

subgraph group_config["OpenSearch Configuration"]
  node_security["Security Resources<br/>[securityconfig.go]"]
  node_templates["Template Resources"]
  node_ism["ISM Policies<br/>[ismpolicy.go]"]
  node_snapshot_policy["Snapshot Policies<br/>[snapshotpolicy.go]"]
  node_snapshot_repository["Snapshot Repositories"]
  node_gateway_data["Cluster API Services<br/>[os_data_service.go]"]
  node_gateway_security["Security API Services"]
  node_gateway_client["OpenSearch Client<br/>[os_client.go]"]
end

node_operator_user(("Cluster Operator"))
node_kubernetes[("Kubernetes API")]
node_opensearch[("OpenSearch Cluster")]
node_dashboards["OpenSearch Dashboards"]

node_operator_user -->|"submits resources"| node_custom_resources
node_custom_resources -->|"validates"| node_admission
node_runtime -->|"registers"| node_cluster_controller
node_runtime -->|"registers"| node_admission
node_runtime -->|"registers"| node_migration
node_cluster_controller -->|"builds workloads"| node_cluster_builder
node_cluster_controller -->|"reconciles resources"| node_k8s_client
node_cluster_controller -.->|"manages lifecycle"| node_cluster_features
node_cluster_controller -.->|"provisions dashboards"| node_dashboards_builder
node_cluster_controller -.->|"manages certificates"| node_tls
node_cluster_builder -->|"reads specification"| node_custom_resources
node_k8s_client -->|"delegates reconciliation"| node_resource_engine
node_resource_engine -.->|"applies workloads"| node_kubernetes
node_cluster_builder -.->|"defines workloads"| node_kubernetes
node_migration -->|"converts API resources"| node_custom_resources
node_config_resources -.->|"configures security"| node_security
node_config_resources -.->|"configures templates"| node_templates
node_config_resources -.->|"configures policies"| node_ism
node_config_resources -.->|"configures snapshots"| node_snapshot_policy
node_snapshot_repository -->|"creates client"| node_gateway_client
node_snapshot_repository -->|"manages repositories"| node_gateway_data
node_security -.->|"manages security APIs"| node_gateway_security
node_templates -.->|"manages templates"| node_gateway_data
node_ism -.->|"uses cluster API"| node_gateway_client
node_snapshot_policy -.->|"uses cluster API"| node_gateway_client
node_gateway_data -->|"uses client"| node_gateway_client
node_gateway_security -->|"uses client"| node_gateway_client
node_gateway_client -.->|"sends API requests"| node_opensearch
node_dashboards_builder -.->|"deploys"| node_dashboards
node_cluster_features -.->|"scales and upgrades"| node_kubernetes
node_tls -.->|"manages certificates"| node_kubernetes

click node_custom_resources "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/api/opensearch.org/v1/opensearch_types.go"
click node_config_resources "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/api/opensearch.org/v1/opensearchism_types.go"
click node_admission "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/webhook/opensearch_cluster_webhook.go"
click node_runtime "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/main.go"
click node_cluster_controller "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/controllers/opensearchController.go"
click node_migration "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/controllers/migration_controller.go"
click node_resource_engine "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconciler/resource.go"
click node_k8s_client "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/k8s/client.go"
click node_cluster_builder "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/builders/cluster.go"
click node_dashboards_builder "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/builders/dashboards.go"
click node_cluster_features "https://github.com/opensearch-project/opensearch-k8s-operator/tree/main/opensearch-operator/pkg/reconcilers"
click node_tls "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/tls/pki.go"
click node_security "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/securityconfig.go"
click node_templates "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/componenttemplate.go"
click node_ism "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/ismpolicy.go"
click node_snapshot_policy "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/snapshotpolicy.go"
click node_snapshot_repository "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/snapshotrepository.go"
click node_gateway_data "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/opensearch-gateway/services/os_data_service.go"
click node_gateway_security "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/opensearch-gateway/services/os_security_service.go"
click node_gateway_client "https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/opensearch-gateway/services/os_client.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_custom_resources,node_config_resources toneBlue
class node_admission,node_runtime,node_cluster_controller,node_migration,node_resource_engine,node_k8s_client,node_kubernetes,node_opensearch toneAmber
class node_cluster_builder,node_dashboards_builder,node_cluster_features,node_tls toneMint
class node_security,node_templates,node_ism,node_snapshot_policy,node_snapshot_repository,node_gateway_data,node_gateway_security,node_gateway_client toneRose
class node_operator_user,node_dashboards toneIndigo
```

## Components

### Custom Resource API

- [OpenSearch Resources](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/api/opensearch.org/v1/opensearch_types.go): `opensearch-operator/api/opensearch.org/v1/opensearch_types.go`
- [Config Resources](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/api/opensearch.org/v1/opensearchism_types.go): `opensearch-operator/api/opensearch.org/v1/opensearchism_types.go`

### Operator Control Plane

- [Admission Validation](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/webhook/opensearch_cluster_webhook.go): `opensearch-operator/webhook/opensearch_cluster_webhook.go`
- [Manager Runtime](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/main.go): `opensearch-operator/main.go`
- [Cluster Controller](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/controllers/opensearchController.go): `opensearch-operator/controllers/opensearchController.go`
- [API Migration](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/controllers/migration_controller.go): `opensearch-operator/controllers/migration_controller.go`
- [Resource Reconciler](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconciler/resource.go): `opensearch-operator/pkg/reconciler/resource.go`
- [Kubernetes Client](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/k8s/client.go): `opensearch-operator/pkg/reconcilers/k8s/client.go`

### Cluster Lifecycle

- [Cluster Builder](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/builders/cluster.go): `opensearch-operator/pkg/builders/cluster.go`
- [Dashboards Builder](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/builders/dashboards.go): `opensearch-operator/pkg/builders/dashboards.go`
- [Scaling and Upgrades](https://github.com/opensearch-project/opensearch-k8s-operator/tree/main/opensearch-operator/pkg/reconcilers): `opensearch-operator/pkg/reconcilers`
- [Certificate Management](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/tls/pki.go): `opensearch-operator/pkg/tls/pki.go`

### OpenSearch Configuration

- [Security Resources](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/securityconfig.go): `opensearch-operator/pkg/reconcilers/securityconfig.go`
- [Template Resources](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/componenttemplate.go): `opensearch-operator/pkg/reconcilers/componenttemplate.go`
- [ISM Policies](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/ismpolicy.go): `opensearch-operator/pkg/reconcilers/ismpolicy.go`
- [Snapshot Policies](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/snapshotpolicy.go): `opensearch-operator/pkg/reconcilers/snapshotpolicy.go`
- [Snapshot Repositories](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/pkg/reconcilers/snapshotrepository.go): `opensearch-operator/pkg/reconcilers/snapshotrepository.go`
- [Cluster API Services](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/opensearch-gateway/services/os_data_service.go): `opensearch-operator/opensearch-gateway/services/os_data_service.go`
- [Security API Services](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/opensearch-gateway/services/os_security_service.go): `opensearch-operator/opensearch-gateway/services/os_security_service.go`
- [OpenSearch Client](https://github.com/opensearch-project/opensearch-k8s-operator/blob/main/opensearch-operator/opensearch-gateway/services/os_client.go): `opensearch-operator/opensearch-gateway/services/os_client.go`

### Other components

- **Cluster Operator**
- **Kubernetes API**
- **OpenSearch Cluster**
- **OpenSearch Dashboards**

## Connections

- Cluster Operator → OpenSearch Resources: submits resources (evidence: `README.md`)
- OpenSearch Resources → Admission Validation: validates (evidence: `opensearch-operator/webhook/opensearch_cluster_webhook.go`)
- Manager Runtime → Cluster Controller: registers (evidence: `opensearch-operator/main.go`)
- Manager Runtime → Admission Validation: registers (evidence: `opensearch-operator/main.go`)
- Manager Runtime → API Migration: registers (evidence: `opensearch-operator/main.go`)
- Cluster Controller → Cluster Builder: builds workloads (evidence: `opensearch-operator/controllers/opensearchController.go`)
- Cluster Controller → Kubernetes Client: reconciles resources (evidence: `opensearch-operator/controllers/opensearchController.go`)
- Cluster Controller → Scaling and Upgrades: manages lifecycle (evidence: `README.md`)
- Cluster Controller → Dashboards Builder: provisions dashboards (evidence: `README.md`)
- Cluster Controller → Certificate Management: manages certificates (evidence: `README.md`)
- Cluster Builder → OpenSearch Resources: reads specification (evidence: `opensearch-operator/pkg/builders/cluster.go`)
- Kubernetes Client → Resource Reconciler: delegates reconciliation (evidence: `opensearch-operator/pkg/reconcilers/k8s/client.go`)
- Resource Reconciler → Kubernetes API: applies workloads
- Cluster Builder → Kubernetes API: defines workloads (evidence: `README.md`)
- API Migration → OpenSearch Resources: converts API resources (evidence: `opensearch-operator/controllers/migration_controller.go`)
- Config Resources → Security Resources: configures security
- Config Resources → Template Resources: configures templates
- Config Resources → ISM Policies: configures policies
- Config Resources → Snapshot Policies: configures snapshots
- Snapshot Repositories → OpenSearch Client: creates client (evidence: `opensearch-operator/pkg/reconcilers/snapshotrepository.go`)
- Snapshot Repositories → Cluster API Services: manages repositories (evidence: `opensearch-operator/pkg/reconcilers/snapshotrepository.go`)
- Security Resources → Security API Services: manages security APIs
- Template Resources → Cluster API Services: manages templates
- ISM Policies → OpenSearch Client: uses cluster API
- Snapshot Policies → OpenSearch Client: uses cluster API
- Cluster API Services → OpenSearch Client: uses client (evidence: `opensearch-operator/opensearch-gateway/services/os_data_service.go`)
- Security API Services → OpenSearch Client: uses client (evidence: `opensearch-operator/opensearch-gateway/services/os_security_service.go`)
- OpenSearch Client → OpenSearch Cluster: sends API requests
- Dashboards Builder → OpenSearch Dashboards: deploys (evidence: `README.md`)
- Scaling and Upgrades → Kubernetes API: scales and upgrades (evidence: `README.md`)
- Certificate Management → Kubernetes API: manages certificates (evidence: `README.md`)
