01 Construire l'environnement source

Exécutez ce module depuis le répertoire des ressources de l'atelier :

cd "$(git rev-parse --show-toplevel)/workshops/elasticsearch_migration_lab/part1"

Durée estimée : 20 à 30 minutes

Présentation

Déployez une plateforme d'observabilité Elasticsearch réaliste pour la production, avec deux charges de travail distinctes. Vous disposerez ainsi d'un état « avant » crédible, comportant plusieurs parcours de migration à analyser dans les parties 2 et 3.

• Charge de travail 1 : collecte de journaux avec Filebeat — trois générateurs de journaux (accès web, application et infrastructure) alimentent les flux de données Elasticsearch par l'intermédiaire de Filebeat et de pipelines d'ingestion.
• Charge de travail 2 : OpenTelemetry Demo (Astronomy Shop) — 16 microservices (Go, Java, .NET, Python, Rust, Node.js, PHP et Ruby) instrumentés avec des SDK OTel envoient traces, métriques et journaux à Elastic APM Server par l'intermédiaire d'un OTel Collector.

Ce dont vous disposerez à la fin

• Elasticsearch 8.15 s'exécutant avec la sécurité désactivée (mode atelier) et recevant environ 300 événements par minute dans 3 flux de données (charge de travail 1)
• Kibana 8.15 avec 6 tableaux de bord prédéfinis : Web Traffic Overview, Application Health, Infrastructure Overview, OTel Demo — APM Traces, OTel Demo — Latency et OTel Demo — Logs
• Filebeat 8.15 collectant les journaux de 3 générateurs : accès web (JSON), application (JSON) et infrastructure (syslog)
• Elastic APM Server 8.15 recevant des traces OTLP provenant à la fois de l'exemple d'application Flask et de l'environnement OTel Demo complet
• 4 pipelines d'ingestion actifs qui effectuent un enrichissement geoip, l'analyse de l'agent utilisateur, une extraction grok et la normalisation de champs par script
• Une politique ILM (lab-observability-policy) gérant le cycle de vie chaud/tiède/suppression des 3 flux de données
• La vitrine OTel Demo accessible à l'adresse http://localhost:8090, avec plus de 15 microservices instrumentés qui génèrent du trafic en continu
• Tous les contrôles de validation réussis : bash validation/check.sh

Prérequis

Remarque : pour l'option B (EC2), vous avez également besoin de Terraform ≥1.5 et d'un compte AWS comportant une paire de clés EC2. Consultez l'étape B.1 pour en savoir plus.

Choisir votre environnement

Sélectionnez l'option qui correspond à votre configuration :

Les deux options utilisent les mêmes fichiers Compose et produisent un environnement actif identique. Seul l'emplacement d'exécution des conteneurs diffère.

Option A : en local (Docker Compose)

Étape A.1 : définir le paramètre noyau requis (Linux et WSL2 uniquement)

Elasticsearch nécessite vm.max_map_count=262144 pour éviter les erreurs de mémoire insuffisante. Les utilisateurs de macOS peuvent ignorer cette étape : Docker Desktop définit ce paramètre en interne.

Linux :

sudo sysctl -w vm.max_map_count=262144

Pour conserver ce réglage après un redémarrage :

echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

WSL2 (Windows) :

# Run in WSL2 terminal
sudo sysctl -w vm.max_map_count=262144

Vérification : sysctl vm.max_map_count doit afficher vm.max_map_count = 262144.

Étape A.2 : démarrer la charge de travail 1 (environnement Elasticsearch)

cd docker
docker compose -f docker-compose.source.yml up -d --build

Sortie attendue (démarrage des conteneurs) :

[+] Running 10/10
 [+] Network docker_default       Created
 [+] Container elasticsearch      Started
 [+] Container kibana             Started
 [+] Container elastic-apm-server Started
 [+] Container es-bootstrap       Started
 [+] Container filebeat           Started
 [+] Container log-generator-web  Started
 [+] Container log-generator-app  Started
 [+] Container log-generator-infra Started
 [+] Container sample-app         Started

Laissez 2 à 3 minutes à Elasticsearch pour démarrer complètement et au conteneur d'amorçage pour terminer la configuration des flux de données, des politiques ILM, des pipelines d'ingestion et des tableaux de bord Kibana.

Étape A.3 : démarrer la charge de travail 2 (OpenTelemetry Demo)

Remarque : la charge de travail 2 nécessite environ 9 Go de RAM pour 16 microservices. Lancez-la une fois la charge de travail 1 saine.

Depuis le même répertoire docker/, ajoutez les services OTel Demo au réseau existant :

docker compose -f docker-compose.source.yml -f docker-compose.otel-demo.yml up -d

Fonctionnement : les deux fichiers Compose partagent le même projet et le même réseau Docker Compose. Le conteneur otelcol-demo collecte tous les signaux des microservices de démonstration et les transmet au conteneur elastic-apm-server démarré par la charge de travail 1.

Au premier lancement, environ 1,5 Go d'images OTel Demo sont téléchargés. Attendez 3 à 5 minutes que tous les services soient sains.

Étape A.4 : surveiller l'amorçage

Le conteneur es-bootstrap crée tous les flux de données, politiques ILM, pipelines d'ingestion et modèles d'index composables, puis importe les tableaux de bord Kibana. Suivez son exécution jusqu'à la fin :

docker compose -f docker-compose.source.yml logs -f es-bootstrap

Sortie finale attendue une fois l'amorçage terminé :

es-bootstrap  | ILM policy created.
es-bootstrap  | ...
es-bootstrap  | Dashboards imported.
es-bootstrap  | Bootstrap complete!

Appuyez sur Ctrl+C pour cesser de suivre les journaux.

Étape A.5 : vérifier l'arrivée des données

Vérifiez la santé du cluster Elasticsearch :

curl -s http://localhost:9200/_cluster/health | python3 -m json.tool

Valeur attendue : "status": "green" ou "status": "yellow" (l'état jaune est normal pour un cluster à un seul nœud).

Vérifiez que les 3 flux de données existent et contiennent des documents :

curl -s http://localhost:9200/_data_stream/logs-* | python3 -m json.tool | grep '"name"'

Sortie attendue :

"name": "logs-application-lab"
"name": "logs-infrastructure-lab"
"name": "logs-web_access-lab"

Vérifiez le nombre de documents dans tous les flux de données :

curl -s "http://localhost:9200/logs-*/_count" | python3 -m json.tool

Après 2 à 3 minutes de génération de données, "count" devrait se compter en milliers. Si la valeur affichée est 0, il est possible que les générateurs de journaux soient encore en phase de démarrage : attendez 1 minute, puis réessayez.

Vérifiez que les 4 pipelines d'ingestion existent :

curl -s "http://localhost:9200/_ingest/pipeline/web-access-enrichment,app-log-enrichment,infra-log-parsing,default-enrichment" \
  | python3 -m json.tool | grep -E '"web-access|app-log|infra-log|default-enrich"'

Étape A.6 : accéder à la vitrine OTel Demo

Lorsque la charge de travail 2 est en cours d'exécution (3 à 5 minutes après l'étape A.3), ouvrez Astronomy Shop :

• Vitrine : http://localhost:8090
• Interface du générateur de charge : http://localhost:8090/loadgen (affiche les statistiques de trafic Locust)
• Indicateurs de fonctionnalité : http://localhost:8090/feature (permet d'activer l'ingénierie du chaos)

Vérification : la vitrine Astronomy Shop doit s'afficher. Le générateur de charge simule automatiquement environ 5 utilisateurs simultanés ; des traces APM apparaîtront dans Kibana sous 1 à 2 minutes.

Pour vérifier que les données APM parviennent à Elasticsearch :

curl -s "http://localhost:9200/traces-apm-*/_count" | python3 -m json.tool

Résultat attendu : "count" devient supérieur à 0 sous 2 minutes et continue d'augmenter.

Option B : EC2 (Terraform)

La configuration Terraform située dans terraform/ provisionne une instance EC2 t3.2xlarge (8 vCPU / 32 Go de RAM), installe Docker et Docker Compose par l'intermédiaire des données utilisateur, définit automatiquement vm.max_map_count=262144, clone le dépôt de l'atelier et démarre la charge de travail 1 (l'environnement Elasticsearch). Vous n'avez pas à définir manuellement le paramètre noyau. Vous démarrerez vous-même la charge de travail 2 (OpenTelemetry Demo) à l'étape B.4, une fois la charge de travail 1 saine ; l'instance t3.2xlarge est dimensionnée pour les deux.

Étape B.1 : copier le modèle de variables

cd terraform
cp terraform.tfvars.example terraform.tfvars

Ouvrez terraform.tfvars et renseignez vos valeurs :

aws_region       = "us-east-1"          # AWS region to deploy in
instance_type    = "t3.2xlarge"         # 8 vCPU / 32 GB; required for dual-workload stack
ssh_key_name     = "my-key-pair"        # Name of your EC2 key pair in AWS (without .pem extension)
allowed_ssh_cidr = "0.0.0.0/0"         # Restrict to your IP for security: "x.x.x.x/32"
lab_repo_url     = "https://github.com/ClickHouse/clickhouse-partner-labs.git"

Où trouver ssh_key_name : Console AWS → EC2 → Key Pairs. Utilisez le nom qui y figure (sans .pem).

Trouver votre adresse IP : exécutez curl -s ifconfig.me pour obtenir votre adresse IP publique, puis utilisez <YOUR_IP>/32 comme valeur de allowed_ssh_cidr.

Étape B.2 : initialiser et appliquer

terraform init
terraform plan
terraform apply

Vérifiez le plan, puis saisissez yes lorsque vous y êtes invité. Le provisionnement prend environ 2 à 3 minutes.

Exemple de sortie en cas de réussite :

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Outputs:

elasticsearch_url    = "http://54.198.12.34:9200"
instance_public_dns  = "ec2-54-198-12-34.compute-1.amazonaws.com"
instance_public_ip   = "54.198.12.34"
kibana_url           = "http://54.198.12.34:5601"
ssh_command          = "ssh -i ~/.ssh/my-key-pair.pem ec2-user@54.198.12.34"

Étape B.3 : se connecter et suivre le démarrage

Récupérez la commande SSH dans la sortie de Terraform, puis connectez-vous :

# Get the exact SSH command
terraform output ssh_command

# Connect (replace with the actual output from above)
ssh -i ~/.ssh/<key-name>.pem ec2-user@<EC2_PUBLIC_IP>

Une fois connecté, commencez par vérifier si le script de données utilisateur d'EC2 a déjà démarré l'environnement pour vous :

cd ~/lab/partner_labs/02-elasticsearch-migration-lab/part1/docker
docker compose -f docker-compose.source.yml ps

• Si des conteneurs apparaissent (elasticsearch, kibana, elastic-apm-server, etc.), les données utilisateur ont exécuté automatiquement docker compose up -d au premier démarrage. Passez à la suite.
• Si rien n'apparaît, les données utilisateur sont encore en cours d'exécution, n'ont pas encore démarré ou ont échoué. Attendez 60 à 90 secondes, relancez la commande ps et, si la liste est toujours vide, démarrez vous-même l'environnement :

docker compose -f docker-compose.source.yml up -d

Suivez ensuite les journaux du conteneur d'amorçage afin de confirmer que l'initialisation se termine :

docker compose -f docker-compose.source.yml logs -f es-bootstrap

Dernière ligne attendue : es-bootstrap | [INFO] Bootstrap complete!

Appuyez sur Ctrl-C pour cesser le suivi lorsque cette ligne apparaît.

Étape B.4 : démarrer la charge de travail 2 (OpenTelemetry Demo)

Remarque : la charge de travail 2 nécessite environ 9 Go de RAM pour 16 microservices. Lancez-la uniquement lorsque la charge de travail 1 est saine et que le conteneur es-bootstrap a terminé (étape B.3).

Depuis le même répertoire docker/ de la session SSH, ajoutez les services OTel Demo au réseau existant :

docker compose -f docker-compose.source.yml -f docker-compose.otel-demo.yml up -d

Fonctionnement : les deux fichiers Compose partagent le même projet et le même réseau Docker Compose. Le conteneur otelcol-demo collecte tous les signaux des microservices de démonstration et les transmet au conteneur elastic-apm-server démarré par la charge de travail 1.

Au premier lancement, environ 1,5 Go d'images OTel Demo sont téléchargés. Attendez 3 à 5 minutes que tous les services soient sains.

Étape B.5 : effectuer les vérifications depuis l'instance EC2

Exécutez ces commandes dans la session SSH, en utilisant localhost. Depuis l'extérieur de l'instance EC2, le groupe de sécurité limite l'accès aux ports 9200 et 5601 à votre CIDR autorisé ; ils ne sont pas ouverts à l'ensemble d'Internet :

# Cluster health
curl -s http://localhost:9200/_cluster/health | python3 -m json.tool

# Data streams
curl -s http://localhost:9200/_data_stream/logs-* | python3 -m json.tool | grep '"name"'

# Document counts
curl -s "http://localhost:9200/logs-*/_count" | python3 -m json.tool

Vérifiez que les conteneurs de la charge de travail 2 fonctionnent et que les traces APM arrivent :

# OTel demo containers (should list 16+ services like frontend, cartservice, otelcol-demo, etc.)
docker compose -f docker-compose.source.yml -f docker-compose.otel-demo.yml ps

# APM trace count (should be > 0 and growing 2 minutes after Workload 2 starts)
curl -s "http://localhost:9200/traces-apm-*/_count" | python3 -m json.tool

Vous pouvez également effectuer la vérification d'Elasticsearch depuis votre ordinateur à l'aide de l'adresse IP publique indiquée par terraform output :

curl -s http://<EC2_PUBLIC_IP>:9200/_cluster/health | python3 -m json.tool

Remarque concernant l'interface de la vitrine OTel : l'interface Astronomy Shop (port 8090) n'est pas exposée dans le groupe de sécurité par défaut. Pour y accéder depuis votre ordinateur, ouvrez le port 8090 dans terraform/main.tf (puis appliquez à nouveau la configuration), ou utilisez une redirection de port SSH : ssh -i ~/.ssh/<key-name>.pem -L 8090:localhost:8090 ec2-user@<EC2_PUBLIC_IP>, puis ouvrez http://localhost:8090.

Étape 1.6 : ouvrir Kibana (deux options)

Accéder à Kibana

• En local : http://localhost:5601
• EC2 : http://<EC2_PUBLIC_IP>:5601 (utilisez l'adresse IP fournie par terraform output kibana_url)

Lors du premier accès, Kibana peut afficher un écran de chargement pendant 30 à 60 secondes au cours de son initialisation.

Accéder aux tableaux de bord

1. Dans la barre latérale gauche de Kibana, cliquez sur Analytics → Dashboards
2. Quatre tableaux de bord doivent apparaître :
   • Web Traffic Overview — taux de requêtes, codes d'état, répartition géographique
   • Application Health — volume des journaux par niveau de gravité, suivi des erreurs
   • Infrastructure Overview — volume syslog par hôte, principaux processus
   • OTel Demo — APM Traces — volume de traces et principaux services (apparaît après le démarrage de la charge de travail 2)
3. Cliquez sur Web Traffic Overview et réglez l'intervalle sur Last 15 minutes (en haut à droite)

Vérification : le tableau de bord doit afficher des données en temps réel, avec des graphiques qui s'actualisent. Si tous les panneaux sont vides, attendez 2 minutes que les générateurs de journaux produisent suffisamment de données, puis actualisez la page.

Pour afficher dans Kibana les traces APM d'OTel Demo, accédez à Observability → APM → Services une fois la charge de travail 2 démarrée.

Étape 1.7 : exécuter le script de validation

Exécutez le script de validation afin de confirmer que tous les composants de la partie 1 sont sains avant de poursuivre.

En local :

bash validation/check.sh

EC2 (depuis votre ordinateur) :

bash validation/check.sh http://<EC2_IP>:9200 http://<EC2_IP>:5601

EC2 (dans la session SSH) :

bash ~/lab/partner_labs/02-elasticsearch-migration-lab/part1/validation/check.sh

Sortie attendue lorsque tous les contrôles réussissent (exécutez le script environ 5 minutes après le démarrage des deux charges de travail) :

============================================
 Part 1 Validation — Source Environment
 ES:      http://localhost:9200
 Kibana:  http://localhost:5601
 OTelCol: http://localhost:8888
============================================

[PASS] Elasticsearch is reachable
[PASS] Data streams exist (3 found: logs-web_access-lab, logs-application-lab, logs-infrastructure-lab)
[PASS] ILM policy 'lab-observability-policy' exists
[PASS] Ingest pipeline 'web-access-enrichment' exists
[PASS] Ingest pipeline 'app-log-enrichment' exists
[PASS] Ingest pipeline 'infra-log-parsing' exists
[PASS] Ingest pipeline 'default-enrichment' exists
[PASS] Data stream 'logs-web_access-lab' has data (3,241 docs)
[PASS] Data stream 'logs-application-lab' has data (1,876 docs)
[PASS] Data stream 'logs-infrastructure-lab' has data (2,104 docs)
[PASS] GeoIP enrichment working (country: United States)
[PASS] Kibana is reachable
[PASS] Kibana dashboards imported (4 found)
[PASS] OTel Collector (otelcol-demo) is reachable
[PASS] APM traces indexed from OTel Demo (5,832 spans)
[PASS] OTel Demo storefront reachable at http://localhost:8090

============================================
 Results: 16 passed, 0 failed, 0 skipped
============================================

Remarque : les contrôles 14 à 16 (OTel Demo) affichent [SKIP] tant que la charge de travail 2 n'est pas entièrement démarrée. Relancez la validation au bout de 5 minutes.

Résolution des problèmes

Toutes les commandes ci-dessous supposent que vous vous trouvez dans part1/docker/ (le répertoire de travail utilisé dans les étapes précédentes). Si vous avez changé de répertoire, exécutez d'abord cd part1/docker.

1. Mémoire insuffisante pour Elasticsearch / valeur de vm.max_map_count trop faible

Symptôme : le conteneur elasticsearch s'arrête immédiatement ou redémarre sans cesse. La commande docker compose logs elasticsearch affiche :

max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

Correction (Linux / WSL2) :

sudo sysctl -w vm.max_map_count=262144
# Then restart the container:
docker compose -f docker-compose.source.yml restart elasticsearch

Correction (macOS) : cette erreur ne devrait pas se produire sous macOS, car Docker Desktop définit ce paramètre automatiquement. Si elle survient, redémarrez Docker Desktop.

2. Échec de l'amorçage — Elasticsearch n'est pas prêt à temps

Symptôme : le conteneur es-bootstrap s'arrête avec une erreur telle que Connection refused ou curl: (7) Failed to connect. Cela se produit lorsque le démarrage d'Elasticsearch est lent, ce qui est fréquent sur les machines soumises à une forte pression mémoire.

Correction : redémarrez uniquement le conteneur d'amorçage une fois Elasticsearch sain :

# Wait for Elasticsearch to be fully up
until curl -sf http://localhost:9200/_cluster/health > /dev/null 2>&1; do
  echo "Waiting for Elasticsearch..."; sleep 5
done

# Re-run bootstrap
docker compose -f docker-compose.source.yml restart es-bootstrap

# Watch it complete
docker compose -f docker-compose.source.yml logs -f es-bootstrap

3. Le pipeline GeoIP indique un pays MISSING

Symptôme : le script de validation signale [FAIL] GeoIP enrichment not working — geo.country_name missing from web access docs, ou un contrôle manuel affiche "country_name": null.

Cause : Elasticsearch télécharge la base de données GeoIP lors du premier démarrage. Cette opération prend 1 à 2 minutes. Les documents indexés avant que la base ne soit disponible ne sont pas enrichis rétroactivement.

Correction : attendez 2 minutes, puis relancez la validation :

bash validation/check.sh

Vous pouvez confirmer que la base de données est chargée :

curl -s "http://localhost:9200/_ingest/geoip/stats" | python3 -m json.tool | grep '"databases_count"'

Résultat attendu : "databases_count": 1 (ou davantage). Si la valeur est 0, attendez encore une minute et réessayez.

Jalon

Avant de passer à la partie 2, vérifiez tous les points suivants :

Charge de travail 1 (Elasticsearch) :

• Elasticsearch est sain : curl http://localhost:9200/_cluster/health
• 3 flux de données existent : curl http://localhost:9200/_data_stream/logs-*
• La politique ILM est associée : curl http://localhost:9200/_ilm/policy/lab-observability-policy
• Kibana affiche des tableaux de bord alimentés en temps réel à l'adresse http://localhost:5601

Charge de travail 2 (OTel Demo) :

• La vitrine se charge à l'adresse http://localhost:8090
• Des traces APM apparaissent dans Kibana : Observability → APM → Services (plus de 15 services visibles)
• curl http://localhost:9200/traces-apm-*/_count renvoie count > 0

Les deux :

• Tous les contrôles de validation réussissent : bash validation/check.sh

Étape suivante : Partie 2 : Analyse architecturale →