OpenSearch: GitHub Actions & GitLab CI

Starten Sie einen echten OpenSearch-Service direkt aus Ihrer GitHub Actions- oder GitLab CI-Pipeline, führen Sie Ihre Tests dagegen aus und fahren Sie ihn anschließend automatisch wieder herunter

👋 Willkommen in der Stackhero-Dokumentation!

Stackhero bietet eine einsatzbereite OpenSearch-Cloud-Lösung, die zahlreiche Vorteile bietet, darunter:

Optimale Performance und robuste Sicherheit durch eine private und dedizierte VM.

Anpassbarer Domainname gesichert mit HTTPS-Verschlüsselungsunterstützung.

Integrierte OpenSearch Dashboards für nahtlose Datenvisualisierung.

Sparen Sie Zeit und vereinfachen Sie Ihr Leben: Es dauert nur 5 Minuten, um die OpenSearch-Cloud-Hosting-Lösung von Stackhero auszuprobieren!

In dieser Anleitung erfahren Sie, wie Sie einen echten, dedizierten OpenSearch-Service innerhalb Ihrer CI-Pipeline mit GitHub Actions oder GitLab CI betreiben. Mit diesen Schritten können Sie Ihren Code gegen eine Live-OpenSearch-Instanz unter produktionsähnlichen Bedingungen testen – Sie müssen sich also nicht mehr auf Mocks oder Simulationen verlassen. OpenSearch is an open source distributed search and analytics engine for fast full-text search and rich dashboards.

Bei jedem Durchlauf Ihrer Pipeline wird eine neue OpenSearch-Instanz bereitgestellt. Das bedeutet, Ihre Tests interagieren mit genau dem Service-Typ, den Ihre Nutzer später in Produktion verwenden. Der Workflow erstellt automatisch einen temporären Stack, fügt OpenSearch hinzu, wartet auf die Betriebsbereitschaft, liest die generierten Zugangsdaten aus, führt einen Smoke-Test mit curl durch und räumt am Ende immer alles wieder auf.

Sie verwenden dazu das Stackhero CLI, ein eigenständiges Kommandozeilen-Tool, mit dem Sie Stackhero-Services schnell und unkompliziert starten und verwalten können.

1. Access Token erstellen und als CI-Secret speichern

Damit das CLI nicht-interaktiv arbeiten kann, benötigen Sie ein Access Token (Format: usr-xxxxxx:tokenId). Dieses Token müssen Sie nur einmalig erstellen und dann als sicheres, verschlüsseltes Secret in Ihrer CI-Pipeline hinterlegen.

Token erstellen: Öffnen Sie Ihr Stackhero Dashboard, klicken Sie oben rechts auf Ihr Profilbild, gehen Sie zu Ihr Konto, dann Access Tokens und klicken Sie auf Token erstellen.
Für GitHub Actions: Gehen Sie in Ihrem Repository zu Settings > Secrets and variables > Actions > New repository secret und tragen Sie das Token als STACKHERO_TOKEN ein.
Für GitLab CI: Gehen Sie in Ihrem Projekt zu Settings > CI/CD > Variables > Add variable, setzen Sie den Schlüssel auf STACKHERO_TOKEN und aktivieren Sie Masked (und Protected, falls Ihre CI nur auf geschützten Branches läuft).

Platzieren Sie Ihr Access Token niemals direkt in der Pipeline-YAML-Datei. Ist es dort enthalten, kann es für alle mit Repository-Zugriff sichtbar sein und möglicherweise in Build-Logs auftauchen. Die Speicherung als CI-Secret sorgt dafür, dass Ihr Token verschlüsselt und maskiert bleibt und somit sicher ist.

2. Das Lifecycle-Skript

Hier finden Sie ein vollständiges Beispielskript, das den gesamten Lebenszyklus des Services abbildet. Es zeigt, wie wenig Setup nötig ist – nur wenige Befehle. Die fertigen YAML-Beispiele für Ihre Plattform finden Sie in den folgenden Abschnitten.

#!/bin/bash
set -euo pipefail

# STACKHERO_TOKEN wird als CI-Secret bereitgestellt und vom CLI automatisch erkannt.

stackName="ci-opensearch-$$"          # Eindeutiger Stack-Name pro Lauf
serviceStore="opensearch"             # Der OpenSearch-Service Store
instance="20G"        # Bei Bedarf anpassen (siehe Schritt 3)
region="europe"                         # Regionsname (siehe stackhero regions-list)

# 1. CLI auf dem Runner installieren
curl -fsSL https://www.stackhero.io/install.sh | sh

# 2. Client für den Smoke-Test installieren (jq + curl sind die Basis)
apt-get update && apt-get install -y --no-install-recommends jq curl

# 3. Dedizierten Stack für diesen Lauf erstellen
stackId=$(stackhero --format=script stack-create --name="$stackName")
echo "Stack erstellt: $stackId"

# 4. OpenSearch hinzufügen und Service-ID erfassen
serviceId=$(stackhero --format=script service-add \
  --stack="$stackId" \
  --service-store="$serviceStore" \
  --instance="$instance" \
  --region="$region")
echo "Service hinzugefügt: $serviceId"

# 5. Warten, bis der Service läuft (dauert ggf. einige Minuten)
stackhero service-wait-for --service="$serviceId"

# 6. Konfiguration auslesen (enthält die generierten Zugangsdaten)
config=$(stackhero service-configuration-get --service="$serviceId" --format=json)

# 7. Benötigte Zugangsdaten extrahieren
host=$(echo "$config" | jq -r '.configuration.domain')
user=$(echo "$config" | jq -r '.configuration.credentials.login')
password=$(echo "$config" | jq -r '.configuration.credentials.password')

# 8. Smoke-Test: Call the cluster health endpoint.
curl -fsS -u "$user:$password" "https://$host:9200/_cluster/health" | grep -q '"status"'

echo "✅ OpenSearch ist aus der CI erreichbar."

Der Teardown-Schritt, der den Service löscht, auf dessen Entfernung wartet und anschließend den Stack entfernt, ist in den plattformspezifischen Abschnitten unten beschrieben. So wird sichergestellt, dass immer aufgeräumt wird – auch wenn ein Smoke-Test fehlschlägt.

Ein Stack kann nur gelöscht werden, wenn er leer ist. Löschen Sie daher immer zuerst den Service und warten Sie auf dessen Entfernung, bevor Sie den Stack löschen. Der Befehl service-wait-for stellt sicher, dass der Service entweder läuft oder bereits gelöscht ist, und eignet sich daher auch zum Warten auf die Löschung.

3. Instanzgröße wählen

Die folgenden Beispiele verwenden standardmäßig die Einstiegsinstanz 20G für OpenSearch. Diese ist für die meisten Workloads eine solide Wahl, kann aber bei Bedarf angepasst werden. Um alle verfügbaren Instanztypen für OpenSearch anzuzeigen, führen Sie aus:

# Die Spalte NAME zeigt den Wert für --instance
stackhero instances-store-list --service-store=opensearch

4. GitHub Actions

Speichern Sie den folgenden Inhalt als .github/workflows/ci.yml. Ab sofort werden bei jedem Push und Pull Request Tests gegen eine echte OpenSearch-Instanz ausgeführt.

name: CI mit OpenSearch

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      STACKHERO_TOKEN: ${{ secrets.STACKHERO_TOKEN }}
      STACK_NAME: ci-opensearch-${{ github.run_id }}-${{ github.run_attempt }}
      INSTANCE: "20G"   # Bei Bedarf anpassen (siehe Schritt 3)
      REGION: europe
    steps:
      - uses: actions/checkout@v4

      - name: Stackhero CLI und Client installieren
        run: |
          curl -fsSL https://www.stackhero.io/install.sh | sh
          apt-get update && apt-get install -y --no-install-recommends jq curl

      - name: OpenSearch-Service erstellen
        run: |
          set -euo pipefail
          STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
          echo "STACK_ID=$STACK_ID" >> "$GITHUB_ENV"
          SERVICE_ID=$(stackhero --format=script service-add \
            --stack="$STACK_ID" \
            --service-store="opensearch" \
            --instance="$INSTANCE" \
            --region="$REGION")
          echo "SERVICE_ID=$SERVICE_ID" >> "$GITHUB_ENV"
          stackhero service-wait-for --service="$SERVICE_ID"

      - name: Tests gegen OpenSearch ausführen
        run: |
          set -euo pipefail
          config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
          host=$(echo "$config" | jq -r '.configuration.domain')
user=$(echo "$config" | jq -r '.configuration.credentials.login')
password=$(echo "$config" | jq -r '.configuration.credentials.password')
          # Call the cluster health endpoint.
          curl -fsS -u "$user:$password" "https://$host:9200/_cluster/health" | grep -q '"status"'
          echo "✅ OpenSearch ist aus der CI erreichbar."
          # Sie können hier Ihre eigene Test-Suite mit den oben extrahierten Zugangsdaten ausführen ...

      - name: Aufräumen (immer, auch bei Fehlern)
        if: always()
        run: |
          if [ -n "${SERVICE_ID:-}" ]; then
            stackhero service-delete --service="$SERVICE_ID" --confirm
            stackhero service-wait-for --service="$SERVICE_ID"
          fi
          if [ -n "${STACK_ID:-}" ]; then
            stackhero stack-delete --stack="$STACK_ID" --confirm
          fi

Der Teardown-Schritt ist mit if: always() konfiguriert, sodass er unabhängig vom Pipeline-Ergebnis ausgeführt wird. So wird Ihre OpenSearch-Instanz immer gelöscht und Sie zahlen nicht für ungenutzte Ressourcen.

5. GitLab CI

Speichern Sie diese Konfiguration als .gitlab-ci.yml. Mit diesem Setup wird bei jedem Pipeline-Lauf eine frische, echte OpenSearch-Instanz für Ihre Tests bereitgestellt.

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-opensearch-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "20G"   # Bei Bedarf anpassen (siehe Schritt 3)
    REGION: "europe"
    SERVICE_STORE: "opensearch"
  # STACKHERO_TOKEN stammt aus der in Schritt 1 angelegten CI/CD-Variable.
  script:
    - set -euo pipefail
    - curl -fsSL https://www.stackhero.io/install.sh | sh
    - apt-get update && apt-get install -y --no-install-recommends jq curl
    - STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
    - echo "STACK_ID=$STACK_ID" >> deploy.env
    - SERVICE_ID=$(stackhero --format=script service-add --stack="$STACK_ID" --service-store="$SERVICE_STORE" --instance="$INSTANCE" --region="$REGION")
    - echo "SERVICE_ID=$SERVICE_ID" >> deploy.env
    - stackhero service-wait-for --service="$SERVICE_ID"
    - config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
    - host=$(echo "$config" | jq -r '.configuration.domain')
user=$(echo "$config" | jq -r '.configuration.credentials.login')
password=$(echo "$config" | jq -r '.configuration.credentials.password')
    # Call the cluster health endpoint.
    - curl -fsS -u "$user:$password" "https://$host:9200/_cluster/health" | grep -q '"status"'
    - echo "✅ OpenSearch ist aus der CI erreichbar."
    # Sie können hier Ihre eigene Test-Suite mit den oben extrahierten Zugangsdaten ausführen ...
  after_script:
    - test -f deploy.env && . ./deploy.env || true
    - >
      if [ -n "${SERVICE_ID:-}" ]; then
        stackhero service-delete --service="$SERVICE_ID" --confirm
        stackhero service-wait-for --service="$SERVICE_ID"
      fi
    - >
      if [ -n "${STACK_ID:-}" ]; then
        stackhero stack-delete --stack="$STACK_ID" --confirm
      fi

In GitLab erfolgt das Aufräumen im Abschnitt after_script. Dieser wird immer ausgeführt, auch wenn der Job fehlschlägt, sodass Ihre OpenSearch-Ressourcen entfernt werden und keine unnötigen Kosten entstehen.

In GitLab läuft after_script in einer frischen Shell. Um dies zu berücksichtigen, schreibt das Skript die Service- und Stack-IDs während des Jobs in deploy.env und lädt sie vor dem Aufräumen wieder ein. So wird sichergestellt, dass Ihre Ressourcen auch bei einem Fehler im Job entfernt werden.

Damit ist der komplette CI-Lebenszyklus für OpenSearch abgedeckt: Stack erstellen, Service hinzufügen, warten, Zugangsdaten abrufen, Smoke-Test, und immer aufräumen. Jeder Pipeline-Lauf erhält einen echten, isolierten Service – nach Abschluss bleibt nichts zurück. Weitere Informationen zu verfügbaren Befehlen und zur nicht-interaktiven Authentifizierung mit STACKHERO_TOKEN finden Sie in der vollständigen CLI-Dokumentation.