Bring Your Own Knowledge to Ansible Lightspeed: Custom RAG Pipeline for AAP 2.7

Ansible Automation Platform 2.7 introduces Bring Your Own Knowledge (BYOK) for the Ansible Lightspeed intelligent assistant. With BYOK, organizations can inject their own documentation — internal AAP policies, custom collection guides, operational procedures, and best practices — directly into the assistant's RAG (retrieval-augmented generation) pipeline.

When a user asks the intelligent assistant a question, responses now draw from two knowledge sources: your organization's custom content (highest priority) and Red Hat's AAP documentation (second priority). Your internal knowledge always wins.

How the RAG Pipeline Works in AAP 2.7

The intelligent assistant uses retrieval-augmented generation: before answering a question, it retrieves relevant chunks from indexed documentation, then passes them as context to the language model.

In AAP 2.7, the pipeline supports two RAG images:

1. BYOK RAG image — your organization's custom knowledge (highest priority)
2. Ansible documentation RAG image — Red Hat's official AAP docs (second priority)

User question
    ↓
Search BYOK RAG image (priority 1)
    ↓ (if no relevant content found)
Search Red Hat AAP docs RAG image (priority 2)
    ↓
LLM generates answer with retrieved context
    ↓
Answer shown to user

See also: Ansible Automation Platform MCP Server: Now Generally Available in AAP 2.7

What Can You Include in a BYOK Image?

The build tool supports two file formats:

• Plain text files (.txt) — system logs, procedure outputs, checklists
• Markdown files (.md) — documentation, playbook guides, runbooks, best practices

• Internal collection documentation not published to Automation Hub
• Organization-specific playbook coding standards
• Environment-specific inventory variable references
• Internal AAP credential type guides
• Incident runbooks ("When the patching job fails, do X")
• Team-specific naming conventions and tagging policies
• Approved execution environment base images and versions

Building a Custom Knowledge Image

BYOK images are built outside the AAP deployment using the tooling Red Hat provides. The workflow:

1. Organize Your Documentation

byok-docs/
├── policies/
│   ├── naming-conventions.md
│   ├── approved-collections.md
│   └── credential-types.md
├── procedures/
│   ├── patching-runbook.md
│   ├── onboarding-checklist.md
│   └── incident-response.md
├── collections/
│   ├── internal-network-collection.md
│   └── internal-security-hardening.md
└── environments/
    ├── production-inventory-vars.md
    └── staging-config.md

2. Write Effective Knowledge Documents

Structure your markdown for good retrieval results — short, focused documents with clear headings perform better than long monolithic files:

# AAP Patching Workflow: Troubleshooting Failed Jobs

## Symptom
Job template "Monthly OS Patching" exits with status FAILED during package update phase.

## Common Causes
1. Yum lock held by another process — check /var/run/yum.pid on target hosts
2. Repository unreachable — verify connectivity to satellite.internal.example.com
3. Disk space < 2GB on / partition — patching aborts to prevent failure

## Resolution Steps
1. Run ad-hoc command: `ansible -m shell -a "ls /var/run/yum.pid" failing_hosts`
2. If lock file exists: `ansible -m shell -a "rm -f /var/run/yum.pid" failing_hosts`
3. Re-launch the patching job template
4. If disk space issue: escalate to Unix team via ServiceNow INFRA queue

## Prevention
Enable pre-flight check playbook "infra.checks.disk_space" before patching workflows.
Contact: #ansible-ops Slack channel

3. Build the BYOK Image

# Install the BYOK build tool
pip install aap-byok-builder

# Build the knowledge image from your docs directory
aap-byok-builder build \
  --source-dir ./byok-docs \
  --output ./byok-knowledge-image.tar \
  --name "acme-corp-aap-knowledge" \
  --version "1.0.0"

The tool processes your text and markdown files, chunks them for retrieval, generates embeddings, and packages everything into a portable image archive.

4. Import the Image into AAP

# Import via the AAP API
curl -X POST \
  https://aap.example.com/api/v2/intelligent_assistant/knowledge_images/ \
  -H "Authorization: Bearer ${AAP_TOKEN}" \
  -F "name=acme-corp-knowledge" \
  -F "version=1.0.0" \
  -F "image=@byok-knowledge-image.tar"

Or use the Ansible platform collection:

- name: Import BYOK knowledge image
  ansible.platform.knowledge_image:
    name: "acme-corp-aap-knowledge"
    version: "1.0.0"
    source_file: "/tmp/byok-knowledge-image.tar"
    state: present

5. Configure the Intelligent Assistant

After importing, configure the intelligent assistant to use your BYOK image via the AAP administration section or via CaC:

- name: Configure intelligent assistant with BYOK
  ansible.platform.intelligent_assistant_config:
    byok_knowledge_image: "acme-corp-aap-knowledge:1.0.0"
    byok_enabled: true
    state: present

Updating Your Knowledge Base Over Time

BYOK images are designed for ongoing maintenance. As your procedures, policies, or collection documentation evolves, you rebuild and replace the image:

# Build updated image with version bump
aap-byok-builder build \
  --source-dir ./byok-docs \
  --output ./byok-knowledge-image-v2.tar \
  --name "acme-corp-aap-knowledge" \
  --version "2.0.0"

# Import new version
curl -X POST \
  https://aap.example.com/api/v2/intelligent_assistant/knowledge_images/ \
  -H "Authorization: Bearer ${AAP_TOKEN}" \
  -F "name=acme-corp-knowledge" \
  -F "version=2.0.0" \
  -F "image=@byok-knowledge-image-v2.tar"

Administrators can also remove a BYOK image to fall back to Red Hat documentation only:

- name: Remove BYOK image (fall back to Red Hat docs)
  ansible.platform.knowledge_image:
    name: "acme-corp-aap-knowledge"
    state: absent

See also: Red Hat Ansible Automation Platform 2.7: What's New — Features, AI, and Security Enhancements

Deployment Support

BYOK is designed for both AAP deployment methods in 2.7:

• OpenShift Operator — build image externally, push to an OCI registry accessible by the operator, reference via the intelligent assistant configuration
• Containerized installer — build image externally, import the .tar archive through the API or administration UI

Example Use Cases

1. Internal Collection Documentation

Your security team maintains acme.hardening, an internal collection for RHEL hardening. The collection is on your private Automation Hub, but the intelligent assistant previously had no knowledge of it. With BYOK, questions like "How do I use acme.hardening to disable USB storage?" now return accurate answers from your internal docs.

2. Environment-Specific Variables

Production inventory variables for your environments are documented internally. After adding them to BYOK, the assistant correctly answers "What is the correct db_port for production PostgreSQL in the us-east region?" without guessing.

3. Incident Runbooks

When an operator asks "The web tier patching job failed again — what do I do?", the assistant surfaces your patching troubleshooting runbook rather than giving a generic answer.

See also: AI-Assisted Inventory Generation in AAP 2.6 — Developer Preview

FAQ

Does BYOK work with disconnected (air-gapped) AAP deployments?

Yes. The BYOK image is built externally and imported as a file archive. In disconnected environments, build the image on a connected system, transfer it to your air-gapped network, and import it via the API.

Is the BYOK content sent to Red Hat or external AI services?

No. The BYOK image is stored locally in your AAP deployment. Content retrieval happens within your environment before any LLM call. Consult your specific AAP AI configuration for details on where LLM inference occurs.

How large can the BYOK documentation set be?

Red Hat has not published a hard limit, but practical guidance is to focus on the most frequently queried content. Large images with low-relevance content reduce retrieval precision. Start with your most important 20–50 documents and expand from there.

Can I have multiple BYOK images?

AAP 2.7 supports one active BYOK image at a time. If you need to segment knowledge by team, consolidate into a single image or rotate between versions as needed.

Conclusion

BYOK for Ansible Lightspeed transforms the intelligent assistant from a generic Ansible resource into a tool that understands your specific environment. By loading internal procedures, collection documentation, and operational knowledge, the assistant provides accurate, organization-specific answers that generic AI tools cannot match.

Related Articles

• Red Hat Ansible Automation Platform 2.7: What's New
• Ansible Automation Platform MCP Server: Now Generally Available
• ansible.platform Collection: Configuration as Code for AAP 2.7