Deploy and Operate OpenSearch
OpenSearch is a distributed search and analytics engine with OpenSearch Dashboards for visualization. Edka deploys it as a managed app in your Kubernetes cluster through the OpenSearch Kubernetes Operator, generates the cluster credentials and certificates, and optionally publishes Dashboards on a Gateway hostname.
Architecture
Section titled “Architecture”| Component | Purpose | How Edka connects it |
|---|---|---|
| OpenSearch Kubernetes Operator | Reconciles the node StatefulSet, certificates, and security configuration | Installed as a required add-on before the app, watching opensearch-system |
| cert-manager | Issues the operator’s admission webhook certificate | Installed as a required add-on |
| OpenSearch cluster | Search, indexing, and analytics | Declared as an OpenSearchCluster resource named opensearch in opensearch-system |
| OpenSearch Dashboards | Web interface for search, visualization, and administration | Deployed by the operator from the same OpenSearchCluster resource |
| Persistent volumes | Index data, one volume per node | A ReadWriteOnce PersistentVolumeClaim per node from the selected storage class |
| Envoy Gateway | Optional HTTPS access to Dashboards | Select a traffic class and hostname; Edka creates the HTTPRoute |
The operator generates the transport certificates per node and the HTTP layer
certificate, so in-cluster API clients connect over HTTPS and need to trust the
CA the operator generates. Edka also enables setVMMaxMapCount, so the
operator raises vm.max_map_count on the hosts that run OpenSearch pods.
Prerequisites
Section titled “Prerequisites”Before installing OpenSearch, prepare:
- an Edka cluster with capacity for the chosen node count at the selected memory and CPU limits; three nodes is the floor
- a storage class that provisions ReadWriteOnce volumes;
hcloud-volumesis the default - an Envoy Gateway traffic class and a DNS hostname resolving through it, if you want to publish Dashboards
Edka installs cert-manager and the OpenSearch Kubernetes Operator as required add-ons before the app when they are not already present. See Kubernetes Add-ons Management and Gateway API.
Install OpenSearch
Section titled “Install OpenSearch”- Open your cluster and select Apps.
- Find OpenSearch and select Install.
- In OpenSearch, set Version, Node Count, the per-node memory and CPU values, and Java Heap Size. Keep or replace the generated Admin Password.
- In Dashboards, keep Enable Dashboards on or turn it off, and review the Dashboards resource values.
- In Storage, set Storage Size per Node and Storage Class.
- In Access, optionally enable Expose Dashboards via Gateway, then select a Traffic Class and enter a Dashboards Hostname.
- Select Install App and follow the operation progress until the cluster is ready.
OpenSearch always installs into the opensearch-system namespace and is
limited to one instance per cluster. The operator watches only that namespace,
so neither the namespace nor the instance count is configurable.
Cluster Sizing and JVM Heap
Section titled “Cluster Sizing and JVM Heap”| Setting | Default | Range or note |
|---|---|---|
| Version | 3.7.0 | Set at install and locked afterwards |
| Node Count | 3 | 3, 5, 7, or 9 |
| Memory Limit per Node | 2Gi | 2Gi to 128Gi |
| Memory Request per Node | 1Gi | Free-form quantity |
| CPU Limit per Node | 1000m | 500m to 48000m |
| CPU Request per Node | 100m | Free-form quantity |
| Java Heap Size | 1g | Around 50% of the memory limit |
All nodes belong to a single pool and carry the cluster_manager, data, and
ingest roles. The operator requires at least three cluster-manager nodes,
which is why three is the minimum node count. The heap value is applied as
-Xms and -Xmx, so the remainder of the memory limit is available to the
filesystem cache.
Edka sets a topology spread constraint with maxSkew: 1 on
kubernetes.io/hostname and whenUnsatisfiable: DoNotSchedule, so node pods
spread across hosts rather than stacking on one.
Generated Secrets
Section titled “Generated Secrets”| Secret | Purpose | Handling |
|---|---|---|
| Admin Password | Password for the built-in admin user | Generated at install, 24 characters with a special character, minimum 8; stored in the opensearch-admin-credentials Secret |
| Dashboards Cookie Secret | Encrypts OpenSearch Dashboards browser sessions | Generated at install, 48 characters, minimum 32; stored in the opensearch-dashboards-cookie Secret and locked after install |
Both Secrets live in the opensearch-system namespace. The admin credentials
Secret carries the username admin and the generated password. Leaving either
field blank during a configuration update keeps the current value, which Edka
reads back from the Secret in the cluster.
Admin Password is retrievable from the app configuration. Revealing it follows your organization’s sensitive-action policy and requires passkey step-up when enforcement is enabled. Keep the Dashboards cookie secret stable for the lifetime of the instance; changing it invalidates existing browser sessions.
OpenSearch Dashboards
Section titled “OpenSearch Dashboards”Dashboards is enabled by default and runs as a single replica on port 5601,
at the same version as the cluster. Edka enables the data source, workspace,
and explore features in its configuration and sets a session cookie name
scoped to this app instance.
| Setting | Default | Options |
|---|---|---|
| Dashboards Memory Limit | 1Gi | 1Gi, 2Gi, 4Gi |
| Dashboards Memory Request | 512Mi | Free-form quantity |
| Dashboards CPU Limit | 1000m | 500m to 4000m |
| Dashboards CPU Request | 100m | Free-form quantity |
Turning Enable Dashboards off removes the Dashboards workload and hides the Dashboards resource and Gateway exposure fields.
Storage
Section titled “Storage”| Setting | Default | Note |
|---|---|---|
| Storage Size per Node | 50Gi | 10Gi to 1000Gi, one ReadWriteOnce volume per node |
| Storage Class | hcloud-volumes | Selected from the cluster storage classes, fixed at install |
Storage Size per Node stays editable after installation, so you can request larger volumes later. Storage Class is locked once the app is installed.
Publish Dashboards on a Gateway Hostname
Section titled “Publish Dashboards on a Gateway Hostname”Exposure is off by default, which leaves only the in-cluster API endpoint published. To publish Dashboards:
- Enable Expose Dashboards via Gateway.
- Select a Traffic Class. It must be an Envoy Gateway traffic class.
- Enter a Dashboards Hostname, for example
opensearch.example.com. - Enable Request Gateway TLS Certificate when no matching wildcard Gateway certificate is available, so Edka uses its Gateway HTTP-01 issuer.
Edka creates an HTTPRoute in opensearch-system that attaches the hostname to
the selected Gateway and forwards to the opensearch-dashboards Service on
port 5601, with a 120 second request and backend request timeout. The
hostname must not already be published by another app in the cluster.
See Domains and TLS for hostname and certificate setup.
Endpoints and Workloads
Section titled “Endpoints and Workloads”After installation, Edka shows:
- OpenSearch API:
https://opensearch.opensearch-system.svc.cluster.local:9200 - OpenSearch Dashboards: the public
https://URL, when Dashboards is enabled and exposed through a Gateway
The app view surfaces the operator-created workloads in opensearch-system:
opensearch-nodes, opensearch-bootstrap,
opensearch-securityconfig-update, and opensearch-dashboards, plus the
opensearch and opensearch-dashboards Services.
Updates
Section titled “Updates”OpenSearch does not offer chart auto-updates. Version is chosen at install and cannot be changed from the app configuration afterwards.
The editable settings, node count, per-node resources, JVM heap, storage size,
Dashboards options, and Gateway exposure, can be changed later from the app
configuration. Edka applies them to the OpenSearchCluster resource and the
operator rolls the change out.
cert-manager and the OpenSearch Kubernetes Operator are add-ons. Manage their versions from Clusters > Add-ons.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| OpenSearch Dashboards exposure requires a Gateway API traffic class | Select an Envoy Gateway traffic class in Traffic Class, or turn off Expose Dashboards via Gateway |
| App is already installed in this cluster | OpenSearch allows one instance per cluster; uninstall the existing instance before installing another one |
| Hostname is already used by another app | Choose a Dashboards Hostname that no other app in the cluster publishes |
| Admin password is rejected | Admin Password must contain at least 8 characters |
| Dashboards cookie secret is rejected | Dashboards Cookie Secret must contain at least 32 characters |
| Install stops while installing dependencies | cert-manager and the OpenSearch Kubernetes Operator must install successfully before the app |
| Node pods stay Pending | Confirm the storage class can bind one ReadWriteOnce volume per node and that enough hosts exist for the kubernetes.io/hostname spread constraint |
| Node pods restart under load | Keep Java Heap Size at roughly half of Memory Limit per Node |
| Dashboards stays unready | Confirm the OpenSearch nodes are ready, then review Logs for the opensearch-dashboards workload |
| Dashboards sign-in fails | Sign in as admin and reveal the stored Admin Password from the app configuration |