Ligne de commande et Terraform

Deux outils pilotent graal Data Platform hors de la console, par la même API REST : graalctl, la ligne de commande, et le fournisseur Terraform graalsystems, pour décrire projets, identités, jobs et workflows dans un dépôt Git. Tous deux sont open source, sous licence Apache 2.0.

graalctl

Un binaire unique pour Linux, macOS et Windows (github.com/graalsystems/graalctl).

curl -fsSL https://raw.githubusercontent.com/graalsystems/graalctl/main/install.sh | sh

Le script télécharge la dernière version pour votre système, vérifie sa somme SHA-256 et l’installe dans /usr/local/bin (ou ~/.local/bin). Sous Windows, prenez graalctl-windows-x86_64.exe sur la page des versions.

Se connecter

Un contexte désigne une installation et un locataire :

graalctl config set-context prod \
  --api-url https://graal.example.com/api/v1 \
  --auth-url https://sso.example.com \
  --tenant acme
graalctl login            # identifiant et mot de passe
graalctl login --device   # SSO : une URL et un code à saisir dans n'importe quel navigateur

--auth-url est l’adresse du serveur OpenID Connect de l’installation, sans /realms/… : le realm se déduit du locataire. Pour un script, une intégration ou un agent, préférez les identifiants d’une application à ceux d’une personne :

echo "$SECRET" | graalctl login --client-id mon-application --client-secret-stdin

Les commandes

graalctl projects list
graalctl libraries upload first_job.py           # affiche la clé de la bibliothèque
graalctl jobs create --project <PROJET> -f job.json
graalctl jobs run <JOB> --follow                 # lance un run et suit ses logs
graalctl jobs schedule <JOB> "0 6 * * *"         # JSON Patch sur /schedule
graalctl runs list --job <JOB>
graalctl api /instance-types                     # n'importe quelle opération de l'API

-o json rend les objets de l’API, -o id un identifiant par ligne. Le fichier job.json a la forme décrite dans le démarrage rapide.

Dans une chaîne d’intégration continue

Rien n’est à stocker sur l’agent de CI : l’adresse de l’API, le locataire et les identifiants de l’application passent par l’environnement.

export GRAAL_API_URL=https://graal.example.com/api/v1
export GRAAL_KEYCLOAK_URL=https://sso.example.com
export GRAAL_TENANT=acme
export GRAAL_CLIENT_ID=ci GRAAL_CLIENT_SECRET=…    # secrets de la CI
graalctl jobs run <JOB> --follow --timeout 3600

Le code de sortie suit le run : 0 s’il réussit, 1 s’il échoue ou est annulé, 124 si --timeout est atteint.

Fournisseur Terraform

Le fournisseur graalsystems (github.com/graalsystems/terraform-provider-graalsystems) gère les projets, identités, jobs, workflows, espaces de travail, utilisateurs et groupes.

terraform {
  required_providers {
    graalsystems = {
      source  = "graalsystems/graalsystems"
      version = "~> 1.4.0"
    }
  }
}

# Identifiants : GRAAL_CLIENT_ID et GRAAL_CLIENT_SECRET.
provider "graalsystems" {
  api_url  = "https://graal.example.com/api/v1"
  auth_url = "https://sso.example.com"
  tenant   = "acme"
}

resource "graalsystems_project" "analytique" {
  name = "Analytique"
}

Une modification devient un JSON Patch sur la ressource : l’API n’a pas de PUT complet.

Des exemples

github.com/graalsystems/examples rassemble des jobs prêts à lancer, un par type (Python, bash, Spark, Dask, Ray, Flink, dbt…), chacun avec son job.json, et un exemple de CI GitHub Actions avec graalctl.

Le dossier projects/ y ajoute des projets complets : plusieurs jobs qui se passent leurs données par des tables Iceberg, l’identité qui les exécute avec ses seuls droits, et le workflow qui les enchaîne. Un pipeline de données quotidien (ingestion, agrégation, contrôles qualité) et une prévision de la demande (préparation, notebook d’entraînement suivi dans MLflow, publication) se déploient chacun en une commande :

projects/deploy-project.sh projects/energy-consumption --run