Kafka: GitHub Actions & GitLab CI

Inicie um serviço real de Kafka a partir do seu pipeline do GitHub Actions ou GitLab CI, execute os seus testes sobre ele e elimine-o automaticamente

👋 Bem-vindo à documentação da Stackhero!

A Stackhero facilita o arranque com uma solução Kafka cloud totalmente gerida. Eis o que pode esperar:

  • Tamanhos e transferências de mensagens ilimitados para responder ao crescimento das suas necessidades de dados.
  • Atualizações sem esforço, aplique as últimas melhorias com um simples clique.
  • Performance de topo e segurança robusta, tudo suportado pela sua própria VM privada e dedicada.

Se procura poupar tempo e simplificar o seu fluxo de trabalho, experimente o alojamento Kafka cloud da Stackhero. Demora apenas cerca de 5 minutos a começar!

Este guia irá guiá-lo na execução de um serviço real e dedicado de Kafka dentro do seu pipeline CI, utilizando GitHub Actions ou GitLab CI. Ao seguir estes passos, poderá testar o seu código contra uma instância ativa de Kafka em condições semelhantes às de produção, deixando de depender de mocks ou simulações. Apache Kafka is a distributed event streaming platform built to carry huge streams of events through your systems in real time.

Sempre que o seu pipeline for executado, será criada uma nova instância de Kafka. Isto significa que os seus testes interagem com o mesmo tipo de serviço que os seus utilizadores verão em produção. O workflow cria automaticamente uma stack temporária, adiciona o Kafka, aguarda que esteja pronto, obtém as credenciais geradas, executa um smoke test com o netcat (a TCP check) e, no final, garante sempre a limpeza de todos os recursos.

Irá utilizar o Stackhero CLI, uma ferramenta de linha de comandos autónoma que facilita o lançamento e a gestão de serviços Stackhero de forma rápida e simples.

1. Criar um access token e guardá-lo como segredo CI

Para permitir que o CLI funcione de forma não interativa, irá necessitar de um access token (formato: usr-xxxxxx:tokenId). Só precisa de criar este token uma vez e adicioná-lo ao seu pipeline CI como um segredo seguro e encriptado.

  1. Criar o token: No seu dashboard Stackhero, clique na sua foto de perfil no canto superior direito, aceda a A sua conta, depois Access tokens e clique em Criar token.
  2. Para GitHub Actions: No seu repositório, vá a Settings > Secrets and variables > Actions > New repository secret e introduza o token como STACKHERO_TOKEN.
  3. Para GitLab CI: No seu projeto, vá a Settings > CI/CD > Variables > Add variable, defina a chave como STACKHERO_TOKEN e selecione Masked (e Protected se o seu CI só correr em branches protegidas).

Nunca inclua o seu access token diretamente no ficheiro YAML do pipeline. Se estiver presente no YAML, pode ser exposto a qualquer pessoa com acesso ao repositório e pode aparecer nos logs de build. Guardá-lo como segredo CI mantém-no encriptado e mascarado, garantindo a segurança do seu token.

2. O script de ciclo de vida

Segue-se um exemplo completo de script que gere todo o ciclo de vida do serviço. Demonstra como a configuração é simples, bastando apenas alguns comandos. Pode copiar o YAML pronto para a sua plataforma nas secções abaixo.

#!/bin/bash
set -euo pipefail

# STACKHERO_TOKEN é fornecido pelo segredo CI, o CLI deteta-o automaticamente.

stackName="ci-kafka-$$"          # Nome único da stack para cada execução
serviceStore="kafka"             # O serviço store de Kafka
instance="10G"        # Altere se necessário (ver passo 3)
region="europe"                         # Nome da região (ver stackhero regions-list)

# 1. Instalar o CLI no runner
curl -fsSL https://www.stackhero.io/install.sh | sh

# 2. Instalar o cliente necessário para o smoke test (jq + curl são o mínimo)
apt-get update && apt-get install -y --no-install-recommends jq curl netcat-openbsd

# 3. Criar uma stack dedicada para esta execução
stackId=$(stackhero --format=script stack-create --name="$stackName")
echo "Stack criada: $stackId"

# 4. Adicionar Kafka e obter o id do serviço
serviceId=$(stackhero --format=script service-add \
  --stack="$stackId" \
  --service-store="$serviceStore" \
  --instance="$instance" \
  --region="$region")
echo "Serviço adicionado: $serviceId"

# 5. Esperar até o serviço estar operacional (pode demorar alguns minutos)
stackhero service-wait-for --service="$serviceId"

# 6. Ler a configuração (contém as credenciais geradas)
config=$(stackhero service-configuration-get --service="$serviceId" --format=json)

# 7. Extrair as credenciais necessárias
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 está acessível a partir do CI."

O passo de teardown, que elimina o serviço, aguarda a sua remoção e depois elimina a stack, é detalhado nas secções específicas de cada plataforma abaixo. Este método garante que a limpeza é sempre realizada, mesmo que um smoke test falhe.

Uma stack só pode ser eliminada quando estiver vazia. Elimine sempre o serviço primeiro e aguarde a sua remoção, depois elimine a stack. O comando service-wait-for garante que o serviço está em execução ou já foi eliminado antes de prosseguir, sendo a ferramenta adequada também para aguardar pela eliminação.

3. Escolher o tamanho da instância

Os exemplos abaixo utilizam por defeito a instância de entrada 10G para Kafka. É uma escolha sólida para a maioria dos workloads, mas pode ajustá-la conforme necessário. Para ver todos os tipos de instância disponíveis para Kafka, execute:

# A coluna NAME mostra o valor a passar para --instance
stackhero instances-store-list --service-store=kafka

4. GitHub Actions

Para começar, guarde o seguinte conteúdo como .github/workflows/ci.yml. A partir de agora, cada push e pull request irá executar testes contra uma instância real de Kafka.

name: CI com 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"   # Altere se necessário (ver passo 3)
      REGION: europe
    steps:
      - uses: actions/checkout@v4

      - name: Instalar o Stackhero CLI e o cliente
        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: Criar o serviço Kafka
        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: Executar testes sobre 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 está acessível a partir do CI."
          # Pode executar a sua própria suite de testes aqui usando as credenciais acima ...

      - name: Limpeza (sempre, mesmo em caso de falha)
        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

O passo de limpeza está configurado com if: always() para garantir que é sempre executado, assegurando que a sua instância de Kafka é eliminada e que não será cobrado por recursos não utilizados.

5. GitLab CI

Pode guardar esta configuração como .gitlab-ci.yml. Com esta configuração, cada execução do pipeline cria uma nova instância real de Kafka para os seus testes.

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-kafka-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "10G"   # Altere se necessário (ver passo 3)
    REGION: "europe"
    SERVICE_STORE: "kafka"
  # STACKHERO_TOKEN vem da variável CI/CD criada no passo 1.
  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 está acessível a partir do CI."
    # Pode executar a sua própria suite de testes aqui usando as credenciais acima ...
  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

No GitLab, a limpeza é feita na secção after_script. Esta secção é sempre executada, mesmo que o job falhe, garantindo que os recursos de Kafka são eliminados e que não será cobrado por recursos não utilizados.

No GitLab, o after_script corre numa shell nova. Para lidar com isto, o script grava os IDs do serviço e da stack em deploy.env durante o job e volta a carregá-los antes da limpeza. Assim, mesmo que algo falhe a meio do job, os seus recursos são sempre eliminados.

Este é o ciclo CI completo para Kafka: criar uma stack, adicionar o serviço, aguardar, obter credenciais, smoke-test e garantir sempre a limpeza. Cada execução do pipeline recebe um serviço real e isolado, sem nada a correr no final. Para mais informações sobre os comandos disponíveis e autenticação não interativa com STACKHERO_TOKEN, consulte a documentação completa do CLI.

Outros artigos para Kafka

  1. Automatize com a CLI
    Inicie o Kafka, recupere as suas credenciais e altere a sua configuração programaticamente com a Stackhero CLI