Ansible URI Module Explained with Examples

The Ansible URI module is a powerful tool for interacting with HTTP and REST APIs. It allows you to send HTTP requests and handle responses directly from your playbooks, making it an essential module for managing web services and APIs.

This article will delve deep into the Ansible URI module with examples.

Introduction to the Ansible URI Module

The URI module in Ansible sends HTTP requests to a given URL and retrieves the responses. It supports a wide range of HTTP methods such as GET, POST, PUT, DELETE, and more. This makes it highly versatile for tasks like:

• Validating the availability of a web service.
• Automating REST API calls.
• Managing remote resources programmatically.

The module can handle authentication, manage headers, and work with JSON payloads, making it ideal for working with RESTful APIs.

Basic Syntax

Here is the basic syntax:

- name: Example of Ansible URI Module
  ansible.builtin.uri:
    url: URL
    method: HTTP_METHOD
    headers: HTTP_HEADERS
    body: REQUEST_BODY
    status_code: EXPECTED_STATUS_CODES
    return_content: BOOLEAN
  register: OUTPUT_VARIABLE

Key Parameters:

• url: The target URL for the request.
• method: The HTTP method (GET, POST, PUT, etc.).
• headers: Additional headers to include in the request.
• body: Data to send with the request, typically in JSON format.
• status_code: List of acceptable HTTP status codes.
• return_content: If set to true, returns the response body.

Example 1: Checking the Status of a Web Service

This example checks if a web service is running by sending a GET request.

- name: Verify the status of a web service
  hosts: webservers
  tasks:
    - name: Send GET request to check if the web service is running
      ansible.builtin.uri:
        url: "http://example.com/health"
        method: GET
        status_code: 200
        return_content: yes
      register: response

    - name: Validate the response content for specific keywords
      debug:
        msg: >
          The web service returned the following response:
          {{ response.content }}

    - name: Ensure the response contains 'healthy'
      fail:
        msg: "The web service is not healthy!"
      when: "'healthy' not in response.content"

In this example:

• GET Request: Checks the service availability.
• Validate Content: Inspect the response for keywords like healthy using the debug module.
• Fail Condition: Halts execution if the response does not contain the expected string using the when condition.

Example 2: Making a POST Request

Here, we send a POST request with a JSON payload.

- name: Create a resource using API
  hosts: webservers
  tasks:
    - name: Send POST request to create a resource
      ansible.builtin.uri:
        url: "http://example.com/api/resource"
        method: POST
        headers:
          Content-Type: "application/json"
        body: '{"name": "New Resource", "type": "example"}'
        status_code: 201
        return_content: yes
      register: create_response

    - name: Display the creation response
      debug:
        var: create_response.json

This playbook sends a POST request to an API to create a resource, verifies the success with a 201 status code, and displays the API response content.

Example 3: Handling Authentication

Many APIs require authentication. Here’s an example using a basic authentication header.

- name: Fetch data from an API with authentication
  hosts: webservers
  tasks:
    - name: Send GET request with Bearer token
      ansible.builtin.uri:
        url: "http://example.com/api/protected"
        method: GET
        headers:
          Authorization: "Bearer {{ token }}"
        status_code: 200
        return_content: yes
      register: auth_response

    - name: Display the authenticated API response
      debug:
        var: auth_response.json

This playbook retrieves data from a protected API using a Bearer token for authentication and displays the API response content.

Example 4: Working with Headers and JSON Payloads

In this example, we retrieve specific data from a web service by sending custom headers.

- name: Fetch data with custom headers
  hosts: webservers
  tasks:
    - name: Send GET request with custom headers
      ansible.builtin.uri:
        url: "http://example.com/api/data"
        method: GET
        headers:
          Accept: "application/json"
          User-Agent: "Ansible-URI-Example"
        status_code: 200
        return_content: yes
      register: data_response

    - name: Display fetched data
      debug:
        var: data_response.json

This example fetches data from an API using custom headers and displays the JSON response content.

Example 5: Handling Non-200 Status Codes

The URI module provides mechanisms to handle errors gracefully:

- name: Handle non-200 status codes
  hosts: webservers
  tasks:
    - name: Send GET request to a non-existing resource
      ansible.builtin.uri:
        url: "http://example.com/api/unknown"
        method: GET
        status_code:
          - 200
          - 404
        return_content: yes
      register: error_response

    - name: Display message if the resource is missing
      debug:
        msg: "Resource not found!"
      when: error_response.status == 404

This playbook sends a GET request to handle both successful (200) and missing resource (404) responses, displaying a specific message if the resource is not found.

Conclusion

The Ansible URI module is an essential tool for interacting with web services and APIs directly from your playbooks. It supports a wide range of HTTP methods, headers, and authentication mechanisms, enabling seamless automation of API-driven tasks.

FAQs