Search and analytics engine for full text search, hybrid retrieval and logs. Single node or cluster with dedicated cluster manager and data nodes.
Generated from catalog/services/opensearch.yaml: do not edit by hand.
Summary
| |
|---|
| Version | 2.19.2 |
| Use | install and configure, configure and connect |
| Layer | functional (AI catalog) |
| Category | Data platforms |
| Installation methods | binary, podman |
| External connection | opensearch |
| Sandbox only | no |
Licence
| |
|---|
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | opensearch |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64 (architecture of the artifacts of the descriptor) |
podman | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- at least 4096 MB of memory (blocking,
memory).
- kernel parameter
vm.max_map_count at least 262144 (warning, max_map_count).
Programs the commands and checks of the service start on the host, outside the managed roots: add them to allowed_commands of the agent (see Security of the Navin agent), else the agent refuses them with command_not_allowed: /usr/bin/curl.
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|
manager | http | 9200/tcp | yes |
manager | transport | 9300/tcp | yes |
node | http | 9200/tcp | yes |
node | transport | 9300/tcp | yes |
Kernel parameters
| Parameter | Value |
|---|
vm.max_map_count | 262144 |
vm.swappiness | 1 |
Process limits: memlock | unlimited |
Process limits: nofile | 65536 |
Process limits: nproc | 4096 |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
podman | - | the container images of the descriptor, run by Podman under systemd |
Components
| Component | Kind | Installation methods | Ports |
|---|
Cluster manager (manager) | master | binary, podman | 9200/tcp, 9300/tcp |
Data node (node) | worker | binary, podman | 9200/tcp, 9300/tcp |
Single node (single-node) (default)
One node holding every role.
What the mode deploys:
| Component | Placement |
|---|
manager | not used |
node | min 1, max 1 |
Cluster (cluster)
An odd number (3 or more) of cluster manager eligible nodes and data nodes.
What the mode deploys:
| Component | Placement |
|---|
manager | min 3, odd number, recommended 3 |
node | min 2, recommended 3 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select OpenSearch. The card shows the licence Apache-2.0. Pick the Method among binary, podman (default binary). To register an existing opensearch service of your organisation instead, turn on Use an existing external service.
-
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: single-node (default), cluster. Each mode deploys the components listed in Installation methods and modes. With several components, place each one on its hosts in Component placement (Suggest placement proposes a placement that respects the cardinalities).
-
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
Connect an existing service
| |
|---|
| Schemes | https |
| Default port | 9200 |
| Authentication | required |
| Health check | /_cluster/health |
| Authentication method | Fields | Description |
|---|
basic | username, password | User of the security plugin (internal users or LDAP); Jaeger, OpenSearch Dashboards and the collector connect with it. |
Official documentation: https://docs.opensearch.org/latest/security/
| Field | Type | Default | Description | Notes |
|---|
Security Analytics index prefix (security_analytics_index) | string | navin-siem | Security Analytics index prefix used by the platform. | - |
High availability
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|
single-node | standalone (standalone) | single (single) | - | 1 | One node holding every role. |
cluster | cluster (cluster) | active-active (active-active) | manager | 3 | An odd number of cluster manager eligible nodes and data nodes holding primary and replica shards. |
Notes
- The election of the cluster manager uses a voting configuration (majority of the eligible nodes), listed here as raft; an index survives a node loss only with at least one replica shard.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
HTTP port (http_port) | port | 9200 | - | no | no | no | Port of the REST API. |
Transport port (transport_port) | port | 9300 | - | no | no | no | Port of the traffic between nodes. |
Cluster name (cluster_name) | string | navin-search | ^[a-z][a-z0-9-]{1,40}$ | no | no | no | Name shared by the nodes of the cluster. |
Memory
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
JVM heap (heap_mb) | int | 2048 | min 512, max 31744, MB | no | no | yes | Heap of the JVM: half of the host memory, at most 31 GB (compressed pointers). (recommended clamp(round(host.memory_mb * 0.5), 512, 31744)) |
Security
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Security and TLS (tls_enabled) | bool | true | - | no | no | no | TLS on HTTP and transport with certificates of the manager CA. The security plugin is never disabled (P5C-006): it needs the transport certificates, so turning this off is refused when the configuration is rendered. |
Administrator password (admin_password) | password | generated | - | no | yes | no | Initial password of the admin user, hashed into internal_users.yml at the first start (the security index keeps it afterwards). |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|
http | http | node | 9200 (http_port) | - | tls_enabled | username, tls | password | - |
Commands
| Command | Component | Target | Description |
|---|
Cluster health (cluster_health) | node | first host | Reads _cluster/health (status, nodes, unassigned shards). |
List nodes (cat_nodes) | node | first host | Reads _cat/nodes (roles, heap, load, elected manager). |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|
manager | TCP {{ host.ip or '127.0.0.1' }}:{{ config.http_port }} | 90 retries; interval 2 s |
node | TCP {{ host.ip or '127.0.0.1' }}:{{ config.http_port }} | 90 retries; interval 2 s |
Readiness (service check)
| Check | Details |
|---|
TCP {{ host.ip or '127.0.0.1' }}:{{ config.http_port }} | - |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|
memory | memory_mb {"min": 4096} | at least 4096 MB of memory | blocking | every component |
max_map_count | sysctl_min {"key": "vm.max_map_count", "min": 262144} | kernel parameter vm.max_map_count at least 262144 | warning | every component |
http_port_free | port_free {"param": "http_port"} | port 9200 free on the host | blocking | every component |
Backup and restore
Snapshot of every index (security index excepted) into a filesystem repository of path.repo, archived (P5C-008, engine opensearch_snapshot). Mode single-node only: a cluster needs a repository shared by every node and is refused by the script with an explicit message.
| |
|---|
| Format | opensearch-snapshot |
| Component | node |
| Files | {{ backup.dir }}/snapshot.tar.gz |
| Restore test | no |
| Instances stopped for the restore | no |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Upstream documentation