AnsibleByExample

Ansible BYOK Example: Add Company Runbooks to the Intelligent Assistant RAG

Beginner
2024-01-014By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

Red Hat AAP 2.7 introduces BYOK ("Bring Your Own Knowledge") as a Tech Preview feature, announced at Red Hat Tech Day Netherlands 2026 in Bunnik. BYOK lets you inject internal documents — runbooks, change-management procedures, network naming conventions, compliance policies — into the Intelligent Assistant's RAG pipeline, so chatbot answers reflect your organization's own standards instead of generic Ansible documentation. Below is an example playbook that uploads a runbook document into the BYOK knowledge source.

---
- name: Add a company runbook to the Intelligent Assistant BYOK knowledge base
  hosts: localhost
  gather_facts: false
  vars:
    aap_controller_host: "https://aap.example.internal"
    aap_byok_knowledge_source: "network-ops-runbooks"
    runbook_file: "./runbooks/incident-response-vlan-outage.md"

  tasks:
    - name: Ensure the BYOK knowledge source exists (Tech Preview API)
      ansible.builtin.uri:
        url: "{{ aap_controller_host }}/api/gateway/v1/byok/knowledge_sources/"
        method: POST
        headers:
          Authorization: "Bearer {{ aap_token }}"
        body_format: json
        body:
          name: "{{ aap_byok_knowledge_source }}"
          description: "Runbooks and change-management procedures for network ops"
        status_code: [201, 400]
      register: knowledge_source
      no_log: true

    - name: Upload the runbook document for RAG ingestion
      ansible.builtin.uri:
        url: "{{ aap_controller_host }}/api/gateway/v1/byok/knowledge_sources/{{ aap_byok_knowledge_source }}/documents/"
        method: POST
        headers:
          Authorization: "Bearer {{ aap_token }}"
        body_format: form-multipart
        body:
          file:
            content: "{{ lookup('file', runbook_file) }}"
            filename: "incident-response-vlan-outage.md"
            mime_type: "text/markdown"
          tags: "runbook,network,incident-response"
        status_code: 202
      register: upload_result

    - name: Show ingestion job status
      ansible.builtin.debug:
        msg: "Runbook queued for RAG ingestion, job id: {{ upload_result.json.job_id }}"

What it does and why

The play targets two Tech Preview BYOK endpoints exposed by AAP 2.7's gateway API. The first task creates (or confirms) a named knowledge source — a logical bucket for related documents, such as network-ops-runbooks or pci-dss-controls. The second task uploads a Markdown runbook (incident-response-vlan-outage.md) into that source as a multipart file; AAP queues it for chunking, embedding, and indexing into the Intelligent Assistant's vector store. Once ingestion completes, the chatbot embedded in the AAP UI can cite that runbook when a user asks about the specific incident procedure, instead of falling back to generic upstream Ansible guidance.

BYOK targets the Intelligent Assistant only — it does not extend to the Coding Assistant (the VS Code extension), which has a separate BYOM provider matrix.

Notes / Gotchas

  • BYOK is Tech Preview in AAP 2.7 as of Red Hat Tech Day Netherlands 2026 — the API paths above are illustrative of the shape of the feature; confirm exact endpoint names against your AAP 2.7 gateway API reference before running in production.
  • The Intelligent Assistant's BYOM matrix matters here: BYOK content is retrieved and passed to whichever chat model backs your Intelligent Assistant deployment (Red Hat AI, OpenAI, or Azure OpenAI on AAP 2.6+). IBM watsonx is not supported for the Intelligent Assistant, so BYOK content won't reach a watsonx-backed chatbot. Google Gemini/Vertex support for the Intelligent Assistant was listed as Coming Soon.
  • Keep runbooks in plain Markdown or plain text where possible — cleaner source formatting produces better chunking and retrieval quality in the RAG pipeline.
  • Treat compliance documents (PCI-DSS, HIPAA, SOC2 policies) as sensitive: apply the same access controls to the BYOK knowledge source as you would to the source documents themselves, since retrieved chunks can surface verbatim in chatbot answers.
  • Because this is Tech Preview, don't build hard production dependencies around it yet — expect API and behavior changes before general availability.

BYOK turns the Intelligent Assistant from a generic Ansible help bot into one that answers with your organization's own runbooks and policies, but until it graduates from Tech Preview, pin your automation to a specific AAP 2.7 point release and re-verify the API shape on each upgrade.

References

All Tutorials