Kafka: GitHub Actions & GitLab CI

Start een echte Kafka-service vanuit uw GitHub Actions- of GitLab CI-pipeline, voer uw tests erop uit en ruim deze automatisch weer op

👋 Welkom bij de Stackhero-documentatie!

Stackhero maakt het eenvoudig om aan de slag te gaan met een volledig beheerde Kafka cloud oplossing. Dit kunt u verwachten:

  • Onbeperkte berichtgroottes en overdrachten om aan uw groeiende databehoeften te voldoen.
  • Moeiteloze updates, pas de nieuwste verbeteringen toe met één klik.
  • Topklasse prestaties en sterke beveiliging, allemaal ondersteund door uw eigen private en dedicated VM.

Wilt u tijd besparen en uw workflow optimaliseren? Probeer dan Stackhero's Kafka cloud hosting. U bent in ongeveer 5 minuten operationeel!

In deze handleiding leert u hoe u een echte, dedicated Kafka-service binnen uw CI-pipeline draait met GitHub Actions of GitLab CI. Door deze stappen te volgen, kunt u uw code testen tegen een live Kafka-instantie onder productie-achtige omstandigheden, zodat u niet langer afhankelijk bent van mocks of simulaties. Apache Kafka is a distributed event streaming platform built to carry huge streams of events through your systems in real time.

Elke keer dat uw pipeline draait, krijgt u een gloednieuwe Kafka-instantie. Dit betekent dat uw tests communiceren met hetzelfde type service als uw gebruikers in productie. De workflow maakt automatisch een tijdelijke stack aan, voegt Kafka toe, wacht tot deze gereed is, haalt de gegenereerde inloggegevens op, voert een smoke test uit met netcat (a TCP check), en ruimt vervolgens altijd alles op zodra de run is afgerond.

U gebruikt de Stackhero CLI, een zelfstandige command-line tool waarmee u snel en eenvoudig Stackhero-services kunt starten en beheren.

1. Maak een access token aan en sla deze op als CI-secret

Om de CLI non-interactief te laten werken, heeft u een access token nodig (formaat: usr-xxxxxx:tokenId). U hoeft dit token slechts één keer aan te maken en voegt het daarna toe aan uw CI-pipeline als een beveiligde, versleutelde secret.

  1. Token aanmaken: Ga in uw Stackhero-dashboard naar uw profielfoto rechtsboven, kies Your account, vervolgens Access tokens, en klik op Create token.
  2. Voor GitHub Actions: Ga in uw repository naar Settings > Secrets and variables > Actions > New repository secret en voer het token in als STACKHERO_TOKEN.
  3. Voor GitLab CI: Ga in uw project naar Settings > CI/CD > Variables > Add variable, stel de key in op STACKHERO_TOKEN en vink Masked aan (en Protected als uw CI alleen draait op beschermde branches).

Voeg uw access token nooit direct toe aan uw pipeline YAML-bestand. Als het token in YAML staat, kan het zichtbaar zijn voor iedereen met toegang tot de repository en mogelijk in build logs verschijnen. Door het als CI-secret op te slaan, blijft het versleuteld en gemaskeerd, zodat uw token veilig blijft.

2. Het lifecycle-script

Hieronder vindt u een volledig voorbeeldscript dat de volledige levenscyclus van de service beheert. Het laat zien hoe weinig setup er nodig is: slechts een paar commando's. U kunt de kant-en-klare YAML voor uw platform kopiëren uit de secties hieronder.

#!/bin/bash
set -euo pipefail

# STACKHERO_TOKEN wordt geleverd via de CI-secret, de CLI pikt deze automatisch op.

stackName="ci-kafka-$$"          # Unieke stacknaam voor elke run
serviceStore="kafka"             # De Kafka service store
instance="10G"        # Pas aan indien nodig (zie stap 3)
region="europe"                         # Regio-naam (zie stackhero regions-list)

# 1. Installeer de CLI op de runner
curl -fsSL https://www.stackhero.io/install.sh | sh

# 2. Installeer de benodigde client voor smoke testing (jq + curl zijn de basis)
apt-get update && apt-get install -y --no-install-recommends jq curl netcat-openbsd

# 3. Maak een dedicated stack voor deze run
stackId=$(stackhero --format=script stack-create --name="$stackName")
echo "Stack aangemaakt: $stackId"

# 4. Voeg Kafka toe en sla het service-id op
serviceId=$(stackhero --format=script service-add \
  --stack="$stackId" \
  --service-store="$serviceStore" \
  --instance="$instance" \
  --region="$region")
echo "Service toegevoegd: $serviceId"

# 5. Wacht tot de service actief is (dit kan enkele minuten duren)
stackhero service-wait-for --service="$serviceId"

# 6. Lees de configuratie uit (bevat de gegenereerde inloggegevens)
config=$(stackhero service-configuration-get --service="$serviceId" --format=json)

# 7. Haal de benodigde inloggegevens op
host=$(echo "$config" | jq -r '.configuration.domain')

# 8. Smoke test: Open a TCP connection to the broker port.
nc -z -w 5 "$host" 9092

echo "✅ Kafka is bereikbaar vanuit CI."

De teardown-stap, die de service verwijdert, wacht op de verwijdering en verwijdert daarna de stack, wordt behandeld in de platform-specifieke secties hieronder. Deze aanpak zorgt ervoor dat er altijd wordt opgeruimd, zelfs als een smoke test faalt.

Een stack kan alleen verwijderd worden als deze leeg is. Verwijder daarom altijd eerst de service en wacht tot deze verwijderd is, en verwijder daarna de stack. Het service-wait-for-commando zorgt ervoor dat de service daadwerkelijk draait of verwijderd is voordat u verdergaat, en is dus ook geschikt om te wachten op verwijdering.

3. Kies het instance-type

De onderstaande voorbeelden gebruiken standaard de instapinstantie 10G voor Kafka. Dit is een solide keuze voor de meeste workloads, maar u kunt deze aanpassen indien gewenst. Om alle beschikbare instance-types voor Kafka te bekijken, voert u het volgende uit:

# De kolom NAME toont de waarde die u aan --instance moet meegeven
stackhero instances-store-list --service-store=kafka

4. GitHub Actions

Om te beginnen slaat u het volgende op als .github/workflows/ci.yml. Vanaf nu zal elke push en pull request tests uitvoeren tegen een echte Kafka-instantie.

name: CI met Kafka

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      STACKHERO_TOKEN: ${{ secrets.STACKHERO_TOKEN }}
      STACK_NAME: ci-kafka-${{ github.run_id }}-${{ github.run_attempt }}
      INSTANCE: "10G"   # Pas aan indien nodig (zie stap 3)
      REGION: europe
    steps:
      - uses: actions/checkout@v4

      - name: Installeer de Stackhero CLI en de client
        run: |
          curl -fsSL https://www.stackhero.io/install.sh | sh
          apt-get update && apt-get install -y --no-install-recommends jq curl netcat-openbsd

      - name: Maak de Kafka-service aan
        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="kafka" \
            --instance="$INSTANCE" \
            --region="$REGION")
          echo "SERVICE_ID=$SERVICE_ID" >> "$GITHUB_ENV"
          stackhero service-wait-for --service="$SERVICE_ID"

      - name: Voer tests uit tegen Kafka
        run: |
          set -euo pipefail
          config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
          host=$(echo "$config" | jq -r '.configuration.domain')
          # Open a TCP connection to the broker port.
          nc -z -w 5 "$host" 9092
          echo "✅ Kafka is bereikbaar vanuit CI."
          # U kunt hier uw eigen test suite uitvoeren met bovenstaande inloggegevens ...

      - name: Opruimen (altijd, ook bij fouten)
        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

De teardown-stap is ingesteld met if: always() zodat deze altijd wordt uitgevoerd, ongeacht het resultaat. Zo wordt uw Kafka-instantie altijd verwijderd en betaalt u niet voor ongebruikte resources.

5. GitLab CI

U kunt deze configuratie opslaan als .gitlab-ci.yml. Met deze setup start elke pipeline-run een nieuwe, echte Kafka voor uw tests.

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-kafka-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "10G"   # Pas aan indien nodig (zie stap 3)
    REGION: "europe"
    SERVICE_STORE: "kafka"
  # STACKHERO_TOKEN komt uit de CI/CD-variabele die u in stap 1 heeft aangemaakt.
  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 netcat-openbsd
    - 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')
    # Open a TCP connection to the broker port.
    - nc -z -w 5 "$host" 9092
    - echo "✅ Kafka is bereikbaar vanuit CI."
    # U kunt hier uw eigen test suite uitvoeren met bovenstaande inloggegevens ...
  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 vindt het opruimen plaats in after_script. Deze sectie wordt altijd uitgevoerd, zelfs als de job faalt, zodat uw Kafka-resources worden verwijderd en u niet betaalt voor ongebruikte resources.

In GitLab draait after_script in een schone shell. Om hiermee om te gaan, schrijft het script de service- en stack-ID's naar deploy.env tijdens de job en laadt deze opnieuw in vóór het opruimen. Zo worden uw resources altijd opgeruimd, zelfs als er halverwege iets misgaat.

Dit is de volledige CI-levenscyclus voor Kafka: maak een stack aan, voeg de service toe, wacht, haal inloggegevens op, smoke-test en altijd opruimen. Elke pipeline-run krijgt een echte, geïsoleerde service, en er blijft niets draaien als u klaar bent. Voor meer informatie over beschikbare commando's en non-interactieve authenticatie met STACKHERO_TOKEN, kunt u de volledige CLI-documentatie raadplegen.

Andere artikelen voor Kafka

  1. Automatiseren met de CLI
    Start Kafka, haal de inloggegevens op en wijzig de configuratie programmatisch met de Stackhero CLI