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:.

# Healthcheck simple (status_code attendu, sans capture de body)
- ansible.builtin.uri:
    url: http://localhost:8080/health
    method: GET
    status_code: [200, 204]
    timeout: 10
  register: health
  until: health.status == 200
  retries: 6
  delay: 5

# POST JSON avec authentification Bearer (création de ressource API)
- ansible.builtin.uri:
    url: https://api.example.com/v1/projects
    method: POST
    headers:
      Authorization: "Bearer {{ vault_api_token }}"
      Content-Type: application/json
    body_format: json
    body:
      name: "{{ project_name }}"
      visibility: private
    status_code: [201, 200]
    return_content: true
    validate_certs: true
  no_log: true       # masque token + body en debug
  register: api_response
  changed_when: api_response.status == 201

Sécurité non négociable :

no_log: true sur toute tâche uri: qui transmet un token, password ou data sensible, sinon les headers: et le body: apparaissent en clair en mode -v ou en cas d'échec.
validate_certs: true (défaut), ne jamais mettre false sauf debug ponctuel sur cert auto-signé interne. Désactiver TLS = MITM accepté = token volé.
status_code: explicite (liste, jamais juste 200), un endpoint qui répond 204 No Content au lieu de 200 ne doit pas faire échouer le playbook si c'est attendu.
changed_when: explicite sur les requêtes POST/PUT/DELETE, sans ça, Ansible considère toujours changed=true. Comparer le status ou un champ JSON pour distinguer création vs no-op.
timeout: explicite (5-30 s), sans ça, un endpoint qui pend bloque le playbook.
until: + retries: + delay: pour les healthchecks d'application en cours de démarrage, ne pas faire un seul shot qui échoue parce que le service met 8 secondes à devenir prêt.
Token via lookup('community.hashi_vault.vault_kv2_get', ...) plutôt que stocké en clair, c'est l'usage propre.

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)
- 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)
- 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.

Pratiquer dans le lab

Cette page a un lab d'accompagnement : labs/modules-reseau/uri/ dans stephrobert/ansible-training.

Challenge, sur db1.lab :

GET sur https://httpbin.org/json + sauver la réponse.
POST sur https://httpbin.org/post avec body JSON {name: rhce, version: 2026}.

Validation pytest+testinfra :

ansible-playbook solution.yml
pytest -v labs/modules-reseau/uri/challenge/tests/

4 tests vérifient l'écriture des fichiers et le contenu JSON parsé.

Prochaines étapes

Module get_url Pour les downloads de fichiers (binaires, archives) avec checksum

Module wait_for Attendre qu'un port s'ouvre, souvent prérequis avant un appel uri:

Filtres Jinja2 avancés json_query (JMESPath) pour extraire des sous-arborescences d'une réponse JSON volumineuse

Pivot Modules Vue d'ensemble des modules réseau, fichiers, paquets, RHEL système