Environnement de Développement

Ce guide couvre la configuration d'un environnement de développement local IceGate pour contribuer au code, exécuter les tests et déboguer.

Prérequis

  • Rust >= 1.92.0 (édition Rust 2024)
  • Docker (pour la construction des images de conteneurs)
  • Git
  • Un cluster Kubernetes local (pour Skaffold)

Installer Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
        source $HOME/.cargo/env
        rustc --version  # Should be >= 1.92.0

Cloner le Dépôt

git clone https://github.com/icegatetech/icegate.git
        cd icegate

Skaffold (Recommandé)

Skaffold est la méthode recommandée pour développer IceGate. Il compile les images depuis les sources, les déploie sur un cluster Kubernetes local et surveille les modifications de fichiers pour recompiler automatiquement.

Installer Skaffold

# macOS
        brew install skaffold
        
        # Linux
        curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64
        chmod +x skaffold && sudo mv skaffold /usr/local/bin/

Cluster Kubernetes Local

Vous avez besoin d'un cluster Kubernetes local. Options :

Runtime Installation Notes
OrbStack macOS uniquement Léger, démarrage rapide. Utiliser le profil -p orbstack
Docker Desktop macOS, Windows, Linux Activer Kubernetes dans les paramètres
minikube Toutes les plateformes minikube start
kind Toutes les plateformes kind create cluster

Exécuter avec Skaffold

# Profil par défaut (k8s local avec RustFS + le catalogue S3 intégré)
        skaffold dev
        
        # Profil OrbStack
        skaffold dev -p orbstack
        
        # Profil AWS Glue (pousse les images vers le registre)
        skaffold dev -p aws-glue
        
        # Profil S3 externe
        skaffold dev -p k3s-external-s3

Ce que Skaffold Déploie

Skaffold utilise des overlays Kustomize qui composent plusieurs charts Helm :

Namespace IceGate (icegate) :

Composant Description
icegate-ingest Récepteurs OTLP (gRPC 4317, HTTP 4318) + processus shift
icegate-query APIs de requête (Loki 3100, Prometheus 9090, Tempo 3200)
icegate-migrate Job de création de schéma (hook Helm pre-install)

Namespace Infrastructure (infra) :

Composant Description
RustFS Stockage compatible S3 avec les buckets : warehouse, queue, jobs

Namespace Observabilité (observability) :

Composant Description
Prometheus Collecte de métriques (kube-prometheus-stack)
Grafana Tableaux de bord avec panneaux IceGate Ingest et Query pré-configurés
Jaeger Traçage distribué pour les services IceGate

Profils Skaffold

Profil Overlay Cas d'utilisation
(défaut) skaffold Développement local avec RustFS + le catalogue S3 intégré
orbstack orbstack Kubernetes OrbStack (macOS)
aws-glue aws-glue Catalogue AWS Glue (pousse les images)
k3s-external-s3 external-s3 S3 externe + Nessie (pousse les images)

Accéder aux Services

# Rediriger les ports des services IceGate
        kubectl port-forward -n icegate svc/icegate-query 3100:3100 &
        kubectl port-forward -n icegate svc/icegate-ingest 4318:4318 4317:4317 &
        
        # Rediriger les ports de l'observabilité
        kubectl port-forward -n observability svc/grafana 3000:80 &
        kubectl port-forward -n observability svc/jaeger-query 16686:16686 &

Modifier le Code

Skaffold surveille le répertoire crates/ et recompile automatiquement les images lorsque les fichiers changent. Le cycle de recompilation-déploiement prend environ 1 à 2 minutes pour un build release.

Pour itérer plus rapidement sur un service spécifique sans reconstruire les images, vous pouvez exécuter cargo build localement et lancer le binaire directement avec un fichier de configuration (voir Compilation).

Docker Compose (Alternative)

Docker Compose est disponible comme alternative plus simple qui ne nécessite pas Kubernetes.

Démarrer la Stack de Développement

# Services principaux avec rechargement à chaud (build debug)
        make dev
        
        # Services principaux en mode release
        make run-core-release
        
        # Avec générateur de charge
        make run-load-release
        
        # Avec monitoring (Jaeger, Prometheus)
        make run-monitoring-release
        
        # Avec analytique (Trino SQL)
        make run-analytics-release
        
        # Arrêter tous les services
        make down

Services Docker Compose

Service Port Description
RustFS 9000, 9001 Stockage compatible S3 + console
Ingest 4317, 4318 Récepteurs OTLP gRPC et HTTP
Query 3100, 9090, 3200, 8815 APIs Loki, Tempo, Arrow Flight SQL ; les routes Prometheus retournent 501 sauf /-/ready
Grafana 3000 Tableaux de bord

Les profils Docker Compose ajoutent des services optionnels :

Profil Services
load otelgen (générateur de charge de logs)
monitoring Jaeger (16686), Prometheus (9092), node-exporter, cAdvisor
analytics Nessie (19120) et moteur SQL Trino (8082)

Build Docker

Construire des images de conteneurs individuelles :

# En utilisant le Dockerfile release (multi-arch, cargo-chef en cache)
        docker build -t icegate/query:latest \
          --build-arg BINARY=query \
          -f config/docker/release.Dockerfile .
        
        # En utilisant le Dockerfile dev (plus simple, single-arch)
        docker build -t icegate/query:dev \
          --build-arg BINARY=query \
          --build-arg PROFILE=debug \
          -f config/docker/Dockerfile .

Variables d'Environnement

Pour le développement local avec RustFS :

export AWS_ACCESS_KEY_ID=rustfsadmin
        export AWS_SECRET_ACCESS_KEY=rustfsadmin
        export AWS_REGION=us-east-1

Étapes Suivantes

Précédent
Dépannage
Suivant
Compilation