cisco.radkit.http module – Execute HTTP/HTTPS requests on devices via Cisco RADKit

Note

This module is part of the cisco.radkit collection (version 2.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install git+https://wwwin-github.cisco.com/scdozier/cisco.radkit-ansible.git. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: cisco.radkit.http.

New in cisco.radkit 0.3.0

Synopsis

  • Executes HTTP and HTTPS requests on devices or services managed by Cisco RADKit

  • Supports all standard HTTP methods with comprehensive request configuration

  • Provides structured response data including status, headers, and content

  • Handles authentication, cookies, and custom headers

Requirements

The below requirements are needed on the host that executes this module.

  • cisco-radkit-client

Parameters

Parameter

Comments

client_ca_path

string

Alternate path to client ca cert for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_CA_PATH will be used instead.

client_cert_path

string

Alternate path to client cert for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_CERT_PATH will be used instead.

client_key_password_b64

aliases: radkit_client_private_key_password_base64

string / required

Client certificate password in base64 If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_PRIVATE_KEY_PASSWORD_BASE64 will be used instead.

client_key_path

string

Alternate path to client key for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_KEY_PATH will be used instead.

content

string

Raw request body content as string

Mutually exclusive with ‘json’ and ‘data’ parameters

cookies

dictionary

Cookie values to include in the request

Provided as a dictionary of cookie names and values

data

dictionary

Data to be form-encoded and sent in the request body

Mutually exclusive with ‘json’ and ‘content’ parameters

device_name

string / required

Name of the device or service as it appears in RADKit inventory

Must be a valid device accessible through RADKit

files

dictionary

Files to upload with the request (multipart form data)

Can be used alone or with ‘data’ parameter

headers

dictionary

Custom HTTP headers to include in the request

Common headers include ‘Content-Type’, ‘Authorization’, etc.

identity

aliases: radkit_identity

string / required

Identity to authentiate with RADKit (xxxx@cisco.com). If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_IDENTITY will be used instead.

json

dictionary

Request body to be JSON-encoded and sent with appropriate Content-Type

Mutually exclusive with ‘content’ and ‘data’ parameters

method

string / required

HTTP method to use for the request

Supports all standard REST API methods

Choices:

  • "GET"

  • "POST"

  • "PUT"

  • "PATCH"

  • "DELETE"

  • "OPTIONS"

  • "HEAD"

  • "get"

  • "post"

  • "put"

  • "patch"

  • "delete"

  • "options"

  • "head"

params

dictionary

URL parameters to append to the request

Will be properly URL-encoded and appended to the path

path

string / required

URL path for the HTTP request, must start with ‘/’

Can include query parameters or use the ‘params’ option separately

service_serial

aliases: radkit_serial, radkit_service_serial

string / required

Radkit service serial If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_SERVICE_SERIAL will be used instead.

status_code

list / elements=integer

List of valid HTTP status codes that indicate successful requests

Request will be considered failed if response code is not in this list

Default: [200]

timeout

float

Timeout for the request on the Service side, in seconds

If not specified, the Service default timeout will be used

Examples

# Simple GET request
- name: Execute HTTP GET request
  cisco.radkit.http:
    device_name: api-server-01
    path: /api/v1/status
    method: GET
  register: status_response
  delegate_to: localhost

# POST request with JSON payload
- name: Create new resource via POST
  cisco.radkit.http:
    device_name: api-server-01
    path: /api/v1/resources
    method: POST
    headers:
      Content-Type: application/json
      Authorization: Bearer {{ api_token }}
    json:
      name: "new-resource"
      type: "configuration"
      enabled: true
    status_code: [201, 202]
  register: create_response
  delegate_to: localhost

# GET request with query parameters
- name: Fetch filtered data
  cisco.radkit.http:
    device_name: monitoring-server
    path: /metrics
    method: GET
    params:
      start_time: "2024-01-01T00:00:00Z"
      end_time: "2024-01-02T00:00:00Z"
      format: json
    headers:
      Accept: application/json
  register: metrics_data
  delegate_to: localhost

# PUT request with authentication cookies
- name: Update configuration
  cisco.radkit.http:
    device_name: config-server
    path: /api/config/network
    method: PUT
    cookies:
      sessionid: "{{ login_session.cookies.sessionid }}"
      csrftoken: "{{ csrf_token }}"
    content: |
      interface GigabitEthernet0/1
       ip address 192.168.1.1 255.255.255.0
       no shutdown
    headers:
      Content-Type: text/plain
    status_code: [200, 204]
    timeout: 30.0
  register: config_update
  delegate_to: localhost

# POST request with form data
- name: Submit form data
  cisco.radkit.http:
    device_name: web-server
    path: /api/form-submit
    method: POST
    data:
      username: "admin"
      password: "secret"
      action: "login"
    headers:
      User-Agent: "Ansible-HTTP-Client"
  register: form_response
  delegate_to: localhost

# File upload with multipart form data
- name: Upload firmware file
  cisco.radkit.http:
    device_name: device-01
    path: /api/firmware/upload
    method: POST
    files:
      firmware: "/path/to/firmware.bin"
    data:
      version: "1.2.3"
      description: "Latest firmware"
    timeout: 300.0
  register: upload_response
  delegate_to: localhost

# Display response data
- name: Show HTTP response
  debug:
    msg: "Status: {{ status_response.status_code }}, Data: {{ status_response.json }}"

# Handle different response types
- name: Process API response
  debug:
    msg: "{{ create_response.json.id if create_response.json is defined else create_response.data }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Whether any changes were made (depends on HTTP method used)

Returned: always

Sample: false

cookies

dictionary

Response cookies as dictionary

Returned: when cookies are present in response

Sample: {"sessionid": "abc123", "token": "xyz789"}

data

string

Response body content as string

Returned: success

Sample: "{\"result\": \"success\", \"message\": \"Operation completed\"}"

headers

dictionary

Response headers as dictionary

Returned: always

Sample: {"content-type": "application/json", "server": "nginx/1.18"}

json

dictionary

Response body content parsed as JSON (if valid JSON)

Returned: when response contains valid JSON

Sample: {"message": "Operation completed", "result": "success"}

status_code

integer

HTTP response status code

Returned: always

Sample: 200

Authors

  • Scott Dozier (@scdozier)