Cómo instalar OpenSearch 3 en Ubuntu 24.04

OpenSearch es un motor de búsqueda y análisis distribuido de código abierto, nacido como bifurcación de Elasticsearch 7.10 y gobernado hoy por la OpenSearch Software Foundation. Incluye de serie un plugin de seguridad con TLS y usuarios, OpenSearch Dashboards para visualizar datos y la gestión del ciclo de vida de índices. En este tutorial instalarás OpenSearch 3 en un nodo único de Ubuntu 24.04 desde el repositorio APT oficial, crearás un índice con análisis en español, instalarás Dashboards y definirás una política que borra los índices antiguos automáticamente.

Requisitos previos

Para seguir esta guía necesitas:

• Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath.
• Un usuario no root con privilegios sudo.
• Al menos 4 GB de RAM (8 GB recomendados) y 2 vCPU. OpenSearch reserva la mitad de la memoria para la JVM y usa el resto como caché del sistema de ficheros.
• Unos 20 GB libres en disco.
• Acceso SSH desde tu equipo para abrir un túnel hasta Dashboards.

Paso 1: Preparar el sistema

OpenSearch usa muchas áreas de memoria mapeada para sus índices y no arranca si el límite del kernel es bajo. Fija vm.max_map_count en 262144 de forma persistente:

echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-opensearch.conf
sudo sysctl --system

Comprueba el valor activo:

sysctl vm.max_map_count

vm.max_map_count = 262144

Paso 2: Instalar OpenSearch desde el repositorio oficial

Instala las herramientas necesarias e importa la clave con la que se firma el repositorio:

sudo apt update
sudo apt install -y curl gnupg ca-certificates
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://artifacts.opensearch.org/publickeys/opensearch-release.pgp | sudo gpg --dearmor -o /etc/apt/keyrings/opensearch.gpg

Añade el repositorio de la rama 3.x:

echo "deb [signed-by=/etc/apt/keyrings/opensearch.gpg] https://artifacts.opensearch.org/releases/bundle/opensearch/3.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-3.x.list
sudo apt update

Desde la versión 2.12, la instalación exige definir la contraseña inicial del usuario admin, que el instalador usa para aplicar una configuración de seguridad de demostración. La contraseña debe tener al menos 8 caracteres con mayúsculas, minúsculas, números y símbolos, y el instalador rechaza las que considera débiles. Sustituye your_strong_password por la tuya:

sudo env OPENSEARCH_INITIAL_ADMIN_PASSWORD='your_strong_password' apt install -y opensearch

El paquete incluye su propio JDK, así que no necesitas instalar Java aparte.

Paso 3: Configurar el nodo

Revisa qué ajustes están ya presentes en el fichero de configuración principal, porque el instalador añade al final un bloque de seguridad y no conviene duplicar claves:

sudo grep -nE '^(cluster.name|node.name|network.host|discovery.type)' /etc/opensearch/opensearch.yml

Abre el fichero:

sudo nano /etc/opensearch/opensearch.yml

Asegúrate de que estas cuatro claves tienen los valores siguientes. Si alguna línea ya existe, cambia su valor; si está comentada o no existe, añádela al principio del fichero. No toques el bloque plugins.security que añadió el instalador:

cluster.name: cubepath-search
node.name: nodo-1
network.host: 127.0.0.1
discovery.type: single-node

discovery.type: single-node evita que el nodo busque otros miembros del clúster, y network.host: 127.0.0.1 limita el acceso a la propia máquina. Si tus aplicaciones están en otros servidores, usa aquí la IP privada del servidor y permite el puerto 9200 solo desde esas IP.

Fija el tamaño del heap de la JVM en un fichero propio dentro de jvm.options.d, que se conserva en las actualizaciones. En un servidor de 4 GB, usa 2 GB:

sudo nano /etc/opensearch/jvm.options.d/heap.options

-Xms2g
-Xmx2g

Usa siempre el mismo valor en -Xms y -Xmx, como máximo la mitad de la RAM y nunca más de 31 GB.

Habilita y arranca el servicio:

sudo systemctl daemon-reload
sudo systemctl enable --now opensearch

El arranque tarda unos segundos. Guarda la contraseña en una variable de la sesión para no repetirla en cada comando y comprueba que el nodo responde. La opción --insecure es necesaria porque la configuración de demostración usa certificados autofirmados:

OS_PASS='your_strong_password'
curl -s --insecure -u "admin:${OS_PASS}" https://localhost:9200

{
  "name" : "nodo-1",
  "cluster_name" : "cubepath-search",
  "cluster_uuid" : "k3Yb1lQzS8uV0cX6n2aHdg",
  "version" : {
    "distribution" : "opensearch",
    "number" : "3.8.0",
    ...
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

Comprueba también el estado del clúster:

curl -s --insecure -u "admin:${OS_PASS}" "https://localhost:9200/_cluster/health?pretty" | grep status

  "status" : "green",

Un nodo único sano muestra green. Si ves yellow, consulta la sección de solución de problemas.

Importante

los certificados de demostración son públicos y los mismos en todas las instalaciones. Sirven para un nodo que solo escucha en 127.0.0.1 o en una red privada, pero antes de exponer OpenSearch fuera de esa red debes sustituirlos por certificados propios siguiendo la documentación de seguridad de OpenSearch.

Paso 4: Crear un índice y buscar documentos

Un índice agrupa documentos con un mapping que define el tipo de cada campo. Crea un índice de artículos con el analizador spanish en el título, que elimina palabras vacías y reduce las palabras a su raíz. En un nodo único, usa number_of_replicas: 0, porque las réplicas nunca se podrían asignar y el clúster quedaría en amarillo:

curl -s --insecure -u "admin:${OS_PASS}" -X PUT https://localhost:9200/articulos \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "titulo":    {"type": "text", "analyzer": "spanish"},
        "categoria": {"type": "keyword"},
        "fecha":     {"type": "date"},
        "precio":    {"type": "float"}
      }
    }
  }'

{"acknowledged":true,"shards_acknowledged":true,"index":"articulos"}

Indexa dos documentos. refresh=true hace que sean visibles para la búsqueda de inmediato, algo útil en pruebas pero que no conviene usar en cargas masivas:

curl -s --insecure -u "admin:${OS_PASS}" -X PUT "https://localhost:9200/articulos/_doc/1?refresh=true" \
  -H "Content-Type: application/json" \
  -d '{"titulo": "Portátiles ligeros para programar", "categoria": "informatica", "fecha": "2026-09-01", "precio": 999.0}'

curl -s --insecure -u "admin:${OS_PASS}" -X PUT "https://localhost:9200/articulos/_doc/2?refresh=true" \
  -H "Content-Type: application/json" \
  -d '{"titulo": "Monitor para diseño gráfico", "categoria": "informatica", "fecha": "2026-09-10", "precio": 349.0}'

Busca por texto combinado con un filtro. Gracias al analizador en español, portátil encuentra el documento que contiene Portátiles:

curl -s --insecure -u "admin:${OS_PASS}" "https://localhost:9200/articulos/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "must":   {"match": {"titulo": "portátil"}},
        "filter": {"term":  {"categoria": "informatica"}}
      }
    }
  }' | grep -E '"(value|titulo)"'

      "value" : 1,
          "titulo" : "Portátiles ligeros para programar",

Lista los índices con su estado y tamaño:

curl -s --insecure -u "admin:${OS_PASS}" "https://localhost:9200/_cat/indices/articulos?v"

Paso 5: Instalar OpenSearch Dashboards

OpenSearch Dashboards es la interfaz web para explorar datos, crear visualizaciones y administrar usuarios y políticas. Usa la misma clave de firma, así que solo tienes que añadir su repositorio:

echo "deb [signed-by=/etc/apt/keyrings/opensearch.gpg] https://artifacts.opensearch.org/releases/bundle/opensearch-dashboards/3.x/apt stable main" | sudo tee /etc/apt/sources.list.d/opensearch-dashboards-3.x.list
sudo apt update
sudo apt install -y opensearch-dashboards

La configuración por defecto de /etc/opensearch-dashboards/opensearch_dashboards.yml ya apunta a https://localhost:9200 con los usuarios de la configuración de demostración, y Dashboards escucha solo en localhost. Instala la versión de Dashboards que coincida con la de OpenSearch; si apt instala versiones distintas, fija ambas con apt install opensearch=<versión> opensearch-dashboards=<versión>. Habilita y arranca el servicio:

sudo systemctl enable --now opensearch-dashboards

Comprueba que escucha en el puerto 5601:

sudo ss -tlnp | grep 5601

LISTEN 0      511        127.0.0.1:5601       0.0.0.0:*    users:(("node",pid=5122,fd=20))

Desde tu equipo, abre un túnel SSH (sustituye your_user y your_server_ip):

ssh -L 5601:127.0.0.1:5601 your_user@your_server_ip

Visita http://localhost:5601 e inicia sesión con el usuario admin y tu contraseña. En Dev Tools puedes lanzar las mismas peticiones del paso 4 sin curl.

Paso 6: Gestionar el ciclo de vida de los índices

Si guardas logs o métricas en índices diarios, el disco se llenará si nadie borra los antiguos. Index State Management (ISM) lo automatiza con políticas. Esta política pasa a solo lectura los índices de más de 7 días y los elimina a los 30. El bloque ism_template aplica la política automáticamente a cada índice nuevo cuyo nombre empiece por logs-:

curl -s --insecure -u "admin:${OS_PASS}" -X PUT https://localhost:9200/_plugins/_ism/policies/logs-30d \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "description": "Solo lectura a los 7 días, borrado a los 30",
      "default_state": "activo",
      "states": [
        {
          "name": "activo",
          "actions": [],
          "transitions": [{"state_name": "lectura", "conditions": {"min_index_age": "7d"}}]
        },
        {
          "name": "lectura",
          "actions": [{"read_only": {}}],
          "transitions": [{"state_name": "borrado", "conditions": {"min_index_age": "30d"}}]
        },
        {
          "name": "borrado",
          "actions": [{"delete": {}}],
          "transitions": []
        }
      ],
      "ism_template": {
        "index_patterns": ["logs-*"],
        "priority": 100
      }
    }
  }' | grep -o '"_id":"[^"]*"'

"_id":"logs-30d"

Comprueba que la política se aplica creando un índice que encaje con el patrón y consultando su estado:

curl -s --insecure -u "admin:${OS_PASS}" -X PUT https://localhost:9200/logs-2026.09.25 \
  -H "Content-Type: application/json" -d '{"settings": {"number_of_replicas": 0}}'
curl -s --insecure -u "admin:${OS_PASS}" "https://localhost:9200/_plugins/_ism/explain/logs-2026.09.25?pretty" | grep plugins.index_state_management.policy_id

    "index.plugins.index_state_management.policy_id" : "logs-30d",

ISM evalúa las transiciones periódicamente (cada pocos minutos por defecto), así que el cambio de estado no es instantáneo.

Solución de problemas

El servicio no arranca. Revisa el journal y el log del clúster, cuyo nombre coincide con cluster.name:

sudo journalctl -u opensearch -n 50 --no-pager
sudo tail -n 50 /var/log/opensearch/cubepath-search.log

Si el log menciona max virtual memory areas vm.max_map_count [65530] is too low, repite el paso 1. Si menciona Duplicate field, alguna clave de opensearch.yml aparece dos veces.

El proceso muere sin error en el log. Probablemente lo ha matado el OOM killer por falta de memoria. Compruébalo con sudo dmesg | grep -i oom y reduce el heap en heap.options o amplía la RAM del servidor.

401 Unauthorized en las peticiones. La contraseña no es la que definiste en la instalación o la variable OS_PASS está vacía en la sesión actual.

El clúster está en amarillo. Hay índices con réplicas que no se pueden asignar en un nodo único. Localízalos con _cat/indices?v&health=yellow y pon sus réplicas a cero con PUT /<índice>/_settings y {"index": {"number_of_replicas": 0}}.

Conclusión

Tienes OpenSearch 3 funcionando en un nodo único de Ubuntu 24.04, con un índice que entiende búsquedas en español, Dashboards accesible por túnel SSH y una política que controla el crecimiento del disco. Como siguientes pasos, sustituye los certificados de demostración por los tuyos, crea usuarios con permisos limitados para cada aplicación desde Security en Dashboards y, cuando necesites alta disponibilidad, amplía a un clúster de tres nodos con discovery.seed_hosts y cluster.initial_cluster_manager_nodes.