12 Verwendung von curl in Verbindung mit OpenSearch

curl ist ein leichtgewichtiges und vielseitiges Kommandozeilen-Tool zur Interaktion mit Web-APIs. Für OpenSearch ist es besonders nützlich, da es alle relevanten HTTP-Methoden unterstützt und zur Verwaltung, Abfrage und Konfiguration des Clusters verwendet werden kann. Im Folgenden wird der Fokus auf die spezifische Nutzung von curl in Verbindung mit OpenSearch gelegt, ohne allgemeine Grundlagen zu wiederholen.

12.1 Vorteile von curl für OpenSearch

• Unabhängigkeit: Kein zusätzliches Tool oder UI erforderlich, ideal für Skripte und Automatisierungen.
• Flexibilität: Unterstützung aller HTTP-Methoden wie GET, POST, PUT, DELETE und HEAD.
• Präzision: Möglichkeit, Header und Payloads individuell zu definieren.
• Transparenz: Zeigt detaillierte Debug-Informationen zu Request und Response.

12.2 Grundlegende Nutzung von curl mit OpenSearch

12.2.1 Abfragen des Cluster-Status

Die einfachste Anfrage an OpenSearch:

curl -X GET "http://localhost:9200"

Antwort:

{
  "name" : "opensearch-node1",
  "cluster_name" : "opensearch-cluster",
  "cluster_uuid" : "abcd1234",
  "version" : {
    "number" : "2.8.0",
    "build_flavor" : "default",
    "build_type" : "docker",
    "build_hash" : "xyz123",
    "minimum_wire_compatibility_version" : "7.10.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

12.2.2 Cluster-Gesundheit prüfen

curl -X GET "http://localhost:9200/_cluster/health?pretty"

Die Option ?pretty formatiert die JSON-Ausgabe für bessere Lesbarkeit.

12.3 Authentifizierung und Sicherheit

Wenn das Security-Plugin aktiviert ist, ist eine Authentifizierung erforderlich. Die Zugangsdaten können über -u übergeben werden:

curl -u "admin:admin" -X GET "https://localhost:9200/_cat/indices?v" -k

• -u: Benutzername und Passwort (Basic Auth).
• -k: Ignoriert SSL-Zertifikatsfehler (für Testzwecke).

12.4 Erstellen und Verwalten von Indizes

12.4.1 Einen neuen Index erstellen

curl -X PUT "http://localhost:9200/my-index"

12.4.2 Index mit Konfiguration anlegen

curl -X PUT "http://localhost:9200/my-index" -H "Content-Type: application/json" -d '{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}'

12.4.3 Index löschen

curl -X DELETE "http://localhost:9200/my-index"

12.5 Dokumentenmanagement

12.5.1 Ein Dokument hinzufügen

curl -X POST "http://localhost:9200/my-index/_doc/1" -H "Content-Type: application/json" -d '{
  "title": "OpenSearch Tutorial",
  "content": "Erstelle und verwalte Dokumente in OpenSearch"
}'

12.5.2 Ein Dokument abrufen

curl -X GET "http://localhost:9200/my-index/_doc/1"

12.5.3 Ein Dokument aktualisieren

curl -X POST "http://localhost:9200/my-index/_update/1" -H "Content-Type: application/json" -d '{
  "doc": {
    "content": "Inhalt wurde aktualisiert"
  }
}'

12.5.4 Ein Dokument löschen

curl -X DELETE "http://localhost:9200/my-index/_doc/1"

12.6 Erweiterte Nutzung

12.6.1 Abfragen mit der DSL (Domain Specific Language)

Suche nach Dokumenten mit bestimmten Kriterien:

curl -X GET "http://localhost:9200/my-index/_search" -H "Content-Type: application/json" -d '{
  "query": {
    "match": {
      "title": "Tutorial"
    }
  }
}'

12.6.2 Debugging mit verbose Modus

curl -v -X GET "http://localhost:9200"

12.6.3 Komplette Header anzeigen

curl -i -X GET "http://localhost:9200"

12.7 Tipps für die Nutzung

12.7.1 Verwendung von Umgebungsvariablen

Häufig benötigte Werte wie URLs oder Zugangsdaten lassen sich bequem mit Umgebungsvariablen speichern: export OS_URL="http://localhost:9200" export OS_AUTH="admin:admin" curl -u "$OS_AUTH" -X GET "$OS_URL/_cat/indices?v"

12.7.2 Automatisierung in Skripten

curl kann in Shell-Skripten genutzt werden, um OpenSearch-Aktionen zu automatisieren: # Beispiel: Liste aller Indizes abrufen curl -u "$OS_AUTH" -X GET "$OS_URL/_cat/indices?v" > indices.txt

12.7.3 Output mit jq verarbeiten

Zur besseren Lesbarkeit oder Weiterverarbeitung der JSON-Antwort: curl -u "$OS_AUTH" -X GET "$OS_URL/_cluster/health" | jq

12.8 SSL und Zertifikate verwenden

Für produktive Umgebungen sollte -k vermieden und ein gültiges Zertifikat genutzt werden: curl --cert /path/to/cert.pem --key /path/to/key.pem -X GET "https://<host>:9200"

12.9 Verwendung von API-Keys zur Vermeidung von Basic Auth (ElasticSearch)

Um die Nutzung von Benutzernamen und Passwörtern (Basic Auth) in Anfragen zu vermeiden und die Sicherheit zu erhöhen, können in OpenSearch API-Keys verwendet werden. Diese werden einmalig generiert und bieten eine flexible Möglichkeit, Anfragen zu authentifizieren.

12.9.1 API-Key erstellen

Ein API-Key wird über die _plugins/_security/api-Schnittstelle erzeugt:

curl -X POST "$OS_URL/_plugins/_security/api/key" \
  -u "admin:admin" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-api-key",
    "role_descriptors": {
      "role1": {
        "cluster": ["all"],
        "index": [
          {
            "names": ["*"],
            "privileges": ["read", "write"]
          }
        ]
      }
    },
    "expiration": "1d"
  }'

Die Antwort enthält den API-Key:

{
  "id": "abc123",
  "name": "my-api-key",
  "expiration": "2025-01-14T10:00:00Z",
  "api_key": "XYZ456"
}

12.9.2 API-Key in Anfragen verwenden

Der API-Key wird als Authorization-Header im Format ApiKey <key> übermittelt:

curl -X GET "$OS_URL/_cat/indices?v" \
  -H "Authorization: ApiKey XYZ456"

12.9.3 Vorteile von API-Keys

• Keine Passwortweitergabe: Reduziert die Risiken, die mit der Speicherung von Passwörtern in Skripten oder Umgebungsvariablen verbunden sind.
• Granularer Zugriff: API-Keys können auf bestimmte Indizes oder Aktionen beschränkt werden.
• Ablaufzeiten: Schlüssel können zeitlich begrenzt sein, um die Sicherheit zu erhöhen.

Durch den Einsatz von API-Keys lässt sich die Verwaltung von Berechtigungen optimieren und gleichzeitig die Sicherheit und Flexibilität erhöhen.

12.10 Token

Das Konzept und die Syntax für API-Keys, wie oben beschrieben, basiert auf Elasticsearch und ist in OpenSearch nicht direkt verfügbar, zumindest nicht in der Standardkonfiguration. In OpenSearch erfolgt die Authentifizierung standardmäßig über Basic Auth oder JWT (JSON Web Tokens), und die Unterstützung für API-Keys in vergleichbarer Weise wie in Elasticsearch fehlt.

12.11 Authentifizierungsmethoden in OpenSearch

OpenSearch verwendet primär folgende Authentifizierungsmethoden: 1. Basic Auth: Benutzername und Passwort (z. B. über das security-Plugin). 2. JWT: JSON Web Tokens als Alternative für die Benutzeranmeldung. 3. Certificate-based Authentication: Authentifizierung mittels Zertifikaten für erhöhte Sicherheit.

12.12 Alternative: Verwendung von Tokens in OpenSearch

Wenn Sie die Nutzung von Benutzernamen und Passwörtern vermeiden möchten, können Sie stattdessen Tokens verwenden, die das Security-Plugin bereitstellt. Diese werden ähnlich wie API-Keys genutzt, sind jedoch spezifisch für OpenSearch.

12.12.1 Erstellung eines Tokens

Ein Token wird über die _plugins/_security/api/authtoken-API erstellt:

curl -X POST "$OS_URL/_plugins/_security/api/authtoken" \
  -H "Content-Type: application/json" \
  -u "admin:admin" \
  -d '{
    "username": "admin",
    "password": "admin"
  }'

Antwort:

{
  "id": "token_id",
  "expiryTime": 1700000000000,
  "role": "admin",
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiJ9.signature"
}

12.12.2 Verwendung des Tokens

Das Token wird anschließend in der Anfrage über den Authorization-Header verwendet:

curl -X GET "$OS_URL/_cat/indices?v" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiJ9.signature"

12.13 Vorteile und Einschränkungen

• Vorteile:
  • Tokens vermeiden die direkte Nutzung von Benutzernamen und Passwörtern in Skripten.
  • Sie sind zeitlich begrenzt und sicherer als Basic Auth.
• Einschränkungen:
  • Tokens sind für kurzlebige Authentifizierungsaufgaben gedacht und nicht so flexibel wie API-Keys in Elasticsearch.