Module uri Ansible : appels API REST avec parsing JSON

ansible.builtin.uri: fait des appels HTTP/HTTPS depuis le managed node : GET, POST, PUT, DELETE. C'est l'équivalent d'un curl mais avec idempotence explicite, parsing JSON automatique, et gestion d'erreurs structurée.

Cas d'usage RHCE 2026 : healthchecks applicatifs, création de ressources via API (Kubernetes, Vault, Grafana), récupération de tokens OAuth, notifications webhook (Slack, Teams).

Options critiques : url:, method: (GET défaut), status_code: (liste de codes acceptés), return_content: true (capture la réponse), body: + body_format:, headers:.

Ce que vous allez apprendre

Faire un GET simple et capturer la réponse JSON parsée.
Faire un POST avec body JSON automatiquement sérialisé.
Authentifier via Basic Auth ou Bearer token.
Accepter plusieurs codes de retour (200, 201, 204).
Faire un healthcheck avec until: + retries: + delay:.

Prérequis

Connaître les méthodes HTTP (GET, POST, PUT, DELETE) et les codes de retour (2xx, 4xx, 5xx).
Comprendre la structure d'un body JSON.

GET simple + parsing JSON

- name: Recuperer la derniere release Ansible
  ansible.builtin.uri:
    url: https://api.github.com/repos/ansible/ansible/releases/latest
    method: GET
    return_content: true
  register: api_response

- name: Afficher la version
  ansible.builtin.debug:
    msg: "Derniere release : {{ api_response.json.tag_name }}"

Comportement :

return_content: true capture la réponse dans register.content (raw) ET register.json (parsé si Content-Type: application/json).
Pas besoin de from_json, Ansible parse automatiquement.
method: GET est le défaut, peut être omis.

POST avec body JSON

- name: Creer une ressource via POST
  ansible.builtin.uri:
    url: https://httpbin.org/post
    method: POST
    body_format: json
    body:
      name: myapp
      version: "1.0.0"
      env: prod
    status_code: [200, 201]
    return_content: true
  register: post_result

Détails :

body_format: json sérialise automatiquement le dict Ansible en JSON pour le body HTTP.
status_code: [200, 201] : la tâche réussit si le serveur retourne 200 OU 201. Sinon, failed.
Sans status_code:, le défaut est [200], un 201 ferait failer la tâche.

Autres body_format: :

json, sérialise dict → JSON (le plus courant).
form-urlencoded, sérialise dict → key=value&key2=value2.
raw, body brut, vous gérez la sérialisation.

Authentification

# Basic Auth (utilisateur/password)
- name: Appeler l'API
  ansible.builtin.uri:
    url: https://api.private.com/v1/resources
    method: GET
    url_username: "{{ vault_api_user }}"
    url_password: "{{ vault_api_password }}"
    force_basic_auth: true
    return_content: true

# Bearer Token (OAuth, JWT, GitHub, GitLab)
- name: Appeler l'API
  ansible.builtin.uri:
    url: https://api.github.com/user
    method: GET
    headers:
      Authorization: "Bearer {{ vault_github_token }}"
      Accept: application/vnd.github+json
    return_content: true

force_basic_auth: true envoie l'en-tête Authorization: Basic ... dès la première requête. Sans, Ansible attend un 401 du serveur avant de re-tenter avec auth (souvent OK, mais coûte un round-trip).

Secrets : toujours dans Ansible Vault.

Healthcheck applicatif (`until: + retries: + delay:`)

Pattern classique : après déploiement d'une app, vérifier qu'elle répond avant de continuer.

- name: Demarrer myapp
  ansible.builtin.systemd_service:
    name: myapp
    state: restarted

- name: Attendre que le port soit ouvert
  ansible.builtin.wait_for:
    port: 8080
    host: 127.0.0.1
    timeout: 30

- name: Verifier le healthcheck HTTP
  ansible.builtin.uri:
    url: http://localhost:8080/health
    method: GET
    status_code: 200
    return_content: true
  register: health
  until: health.json.status == "ok"
  retries: 5
  delay: 2

- name: Afficher la version deployee
  ansible.builtin.debug:
    msg: "myapp version : {{ health.json.version }}"

until: + retries: + delay: = polling. Ansible relance la tâche jusqu'à ce que la condition soit vraie (max retries fois, avec delay secondes entre chaque essai). Idéal pour des services qui mettent quelques secondes à démarrer.

Upload de fichier

- name: Upload de config
  ansible.builtin.uri:
    url: https://api.private.com/v1/configs
    method: POST
    src: /tmp/myapp.yml
    headers:
      Authorization: "Bearer {{ vault_token }}"
      Content-Type: application/yaml
    status_code: [200, 201]

src: envoie le contenu du fichier comme body HTTP. Pour multipart/form-data : body_format: form-multipart (Ansible 2.10+).

`uri:` vs `get_url:`

Cas	Module
Télécharger un fichier (binaire, archive)	`get_url:`
Télécharger avec checksum	`get_url:`
Appeler une API REST (GET, POST, PUT, DELETE)	`uri:`
Parser une réponse JSON	`uri:` + `register.json`
Healthcheck HTTP	`uri:` + `until:`
Upload de fichier vers API	`uri:` + `src:`

Règle : get_url: pour le téléchargement de fichiers (idempotence par checksum/ETag/taille). uri: pour toute interaction HTTP où la réponse compte autant que le statut.

Pièges courants

Symptôme	Cause	Fix
Tâche failed sur HTTP 201	Défaut `status_code: [200]`	Ajouter `[200, 201]`
`register.json` est `null`	`Content-Type` non JSON	Vérifier les headers ou parser manuellement avec `from_json`
Polling infini	Condition `until:` jamais vraie	Limiter `retries:` à un maximum raisonnable
MITM ne déclenche pas d'erreur	`validate_certs: false`	Ne jamais désactiver TLS sauf cas dev

À retenir

uri: = appels HTTP REST (GET, POST, PUT, DELETE).
return_content: true capture la réponse, JSON parsé automatiquement.
status_code: liste les codes acceptés (défaut [200]).
body_format: json sérialise un dict en JSON automatiquement.
Auth : url_username/url_password (Basic) ou headers: (Bearer).
until: + retries: + delay: = polling pour healthchecks.

Mettre en pratique

Piloter une API depuis un playbook demande de gérer trois choses que ce lab fait travailler ensemble. Vous enchaînez un GET dont la réponse JSON est parsée, un POST avec un body_format: json, puis vous élargissez les codes acceptés via status_code: pour qu'une création déjà faite ne casse pas le run. La dernière tâche boucle un healthcheck avec until / retries jusqu'à ce que le service réponde.

Module uri : appels API REST

$ dsoxlab run modules-reseau-uri

Environnement : VM·Durée : ~50 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI dsoxlab, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
git clone https://github.com/stephrobert/ansible-training.git
cd ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run modules-reseau-uri
dsoxlab check modules-reseau-uri

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress.

Pour aller plus loin

Modules assert et fail : Valider le contenu JSON renvoyé par l'API plutôt que de le supposer correct.
Modules wait_for et pause : Attendre l'ouverture du port avant d'appeler l'API, en complément du polling until et retries.
debug, setup, add_host, group_by : Afficher proprement la réponse enregistrée, et ajouter à l'inventaire un hôte découvert par API.