1. Les blocs de configuration
Attributs, blocs et expressions en langage River.
Comprendre la syntaxe
Votre alloy config s'écrit dans un fichier (généralement config.alloy) utilisant une syntaxe déclarative fortement inspirée de Terraform. Dans cette alloy configuration, un composant est défini par un nom et un identifiant. À l'intérieur du bloc, vous définissez des attributs (ex: url = "http://...") et potentiellement des sous-blocs. Les composants exportent des valeurs qui peuvent être référencées par d'autres composants (comme alloy prometheus ou prometheus.exporter.self), créant ainsi le pipeline.
prometheus.scrape "default" {
targets = [{"__address__" = "localhost:9090"}]
forward_to = [prometheus.remote_write.mimir.receiver]
}Gestion des virgules
En River, la gestion des virgules dans les tableaux et les définitions est très souple. Il est recommandé d'ajouter une virgule après le dernier élément d'une liste ou d'une configuration multi-lignes (trailing comma). Cela facilite l'ajout d'éléments ultérieurs et réduit significativement les risques de conflits lors des fusions de code (merges Git).
prometheus.exporter.unix "example" {
enable_collectors = [
"cpu",
"meminfo",
"diskstats",
"textfile",
]
textfile {
directory = "/var/lib/node_exporter/textfile_collector"
}
}2. River vs HCL
Différences et spécificités du langage River par rapport à HCL.
Inspiration et fonctionnement
Bien que alloy river s'inspire largement du langage HCL (HashiCorp Configuration Language) utilisé par Terraform (syntaxe similaire avec des blocs et attributs), il est spécifiquement pensé pour l'observabilité en continu. Contrairement à HCL qui sert souvent à des déploiements d'infrastructures statiques (évalués une seule fois lors d'un apply), River maintient un graphe acyclique dirigé (DAG) dynamique. Lorsqu'une variable ou un secret est modifié, River réévalue automatiquement et en temps réel tous les composants dépendants, sans nécessiter de redémarrage.
3. Variables et Fonctions
Utiliser la logique pour dynamiser les configurations.
Rendre la configuration dynamique
Le langage River permet d'utiliser des expressions pour rendre votre configuration dynamique. Vous pouvez faire appel à des fonctions intégrées (comme sys.env("VAR_NAME") pour lire des variables d'environnement, ou des fonctions de manipulation de chaînes) et définir des blocs de configuration locaux (local.file) pour réutiliser des valeurs, évitant ainsi la répétition et facilitant la maintenance.
4. Gestion des Secrets
Intégrer des variables d'environnement et des fichiers de coffre-fort.
Sécuriser les accès
Il est crucial de ne pas stocker de mots de passe ou de tokens en clair dans vos fichiers de configuration. Alloy propose plusieurs méthodes pour gérer les secrets : l'utilisation de la fonction sys.env(), la lecture depuis des fichiers sécurisés sur le disque, ou encore l'intégration avec des solutions de gestion de secrets tierces via des composants spécifiques. Les valeurs marquées comme secrètes ne sont jamais affichées en clair dans les logs ou l'UI.
Bonne Pratique : Utilisez le composant local.file pour lire des secrets montés dynamiquement (comme des secrets Kubernetes ou Vault) afin qu'Alloy réagisse automatiquement si le fichier secret change sans relance du processus.Erreur Courante : Coder les API tokens en dur dans le fichier de configuration. Cela expose le secret dans votre dépôt Git et en clair dans l'interface UI (sur le port 12345) d'Alloy.
local.file "mimir_api_key" {
filename = "/etc/alloy/secrets/mimir_token.txt"
is_secret = true
}
prometheus.remote_write "cloud" {
endpoint {
url = "https://mimir-url/api/v1/push"
basic_auth {
username = "admin"
password = local.file.mimir_api_key.content
}
}
}Voici également un exemple d'intégration directe avec HashiCorp Vault en utilisant le composant remote.vault :
remote.vault "api_token" {
server = "https://vault.internal:8200"
path = "secret/data/alloy/api"
auth {
token = sys.env("VAULT_TOKEN")
}
}
prometheus.remote_write "cloud" {
endpoint {
url = "https://mimir-url/api/v1/push"
basic_auth {
username = "admin"
password = remote.vault.api_token.data["password"]
}
}
}5. Observabilité d'Alloy
Surveiller la santé de ses propres pipelines via l'interface UI native.
L'interface utilisateur locale
Alloy intègre un serveur HTTP (via l'alloy port 12345 par défaut) qui expose la grafana alloy ui, une interface graphique très utile. Cette UI permet de visualiser le graphe (DAG) de vos composants, de vérifier leur état (Healthy/Unhealthy), et d'inspecter les arguments évalués et les exports de chaque composant en temps réel. C'est l'outil indispensable pour l'alloy live debugging de vos configurations.