kubiya_knowledge

The kubiya_knowledge resource allows you to create and manage knowledge resources in the Kubiya platform. Knowledge resources provide specific information, documentation, and context that agents can reference when performing tasks, ensuring consistent and informed responses.

Knowledge resources are essential for providing agents with domain-specific information, procedures, and context that enables more accurate and useful interactions.

Prerequisites

Before using this resource, ensure you have:

A Kubiya account with API access
An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
At least one group configured in your Kubiya organization
Content files prepared (markdown, text, or other supported formats)

Quick Start

resource "kubiya_knowledge" "basic_docs" {
  name        = "basic-documentation"
  description = "Basic system documentation"
  content     = "This is the basic documentation for our system."
  format      = "markdown"
  
  groups = ["Engineering"]
}

Configuration Examples

Create comprehensive troubleshooting documentation:

resource "kubiya_knowledge" "troubleshooting" {
  name        = "troubleshooting-runbooks"
  description = "Runbooks for common issues and their resolution"
  content     = <<-MARKDOWN
    # Troubleshooting Runbooks
    
    ## High Memory Usage
    
    ### Symptoms
    - Memory usage above 90%
    - Application slowness
    - OOM kills
    
    ### Diagnosis Steps
    1. Check memory usage: `free -m`
    2. Identify top consumers: `ps aux --sort=-%mem | head`
    3. Check for memory leaks: `jmap -heap <pid>`
    
    ### Resolution
    1. Restart affected services
    2. Scale horizontally if needed
    3. Investigate code for memory leaks
    
    ## Database Connection Issues
    
    ### Symptoms
    - Connection timeout errors
    - "Too many connections" errors
    
    ### Diagnosis Steps
    1. Check connection count: `SELECT count(*) FROM pg_stat_activity;`
    2. Check for long-running queries
    3. Verify network connectivity
    
    ### Resolution
    1. Kill idle connections
    2. Increase connection pool size
    3. Optimize queries
  MARKDOWN
  format = "markdown"
  
  groups = ["DevOps", "SRE", "Engineering"]
  labels = ["troubleshooting", "runbooks", "operations", "incident-response"]
}

resource "kubiya_agent" "incident_responder" {
  name         = "incident-responder"
  runner       = "kubiya-hosted"
  description  = "Incident response agent"
  instructions = <<-EOT
    You are an incident response agent. 
    Use the troubleshooting-runbooks knowledge base to diagnose and resolve issues.
    Follow the documented procedures exactly.
  EOT
  
  groups = ["DevOps", "SRE"]
}

Advanced Configurations

Compliance and Security Policies

Store compliance documentation and security policies:

resource "kubiya_knowledge" "compliance_policies" {
  name        = "compliance-security-policies"
  description = "Security and compliance policies and procedures"
  content     = file("${path.module}/docs/compliance-policies.md")
  format      = "markdown"
  
  groups = ["Security", "Compliance", "Engineering", "DevOps"]
  labels = ["compliance", "security", "policies", "governance"]
}

resource "kubiya_knowledge" "gdpr_procedures" {
  name        = "gdpr-procedures"
  description = "GDPR compliance procedures"
  content     = file("${path.module}/docs/gdpr-procedures.md")
  format      = "markdown"
  
  groups = ["Compliance", "Legal", "Engineering"]
  labels = ["gdpr", "compliance", "data-privacy", "legal"]
}

resource "kubiya_knowledge" "security_playbooks" {
  name        = "security-incident-playbooks"
  description = "Security incident response playbooks"
  content     = <<-MARKDOWN
    # Security Incident Response Playbooks
    
    ## Data Breach Response
    
    ### Immediate Actions (0-1 hours)
    1. Isolate affected systems
    2. Assess scope of breach
    3. Notify incident commander
    4. Begin evidence collection
    
    ### Short Term Actions (1-24 hours)
    1. Contain the breach
    2. Assess data exposure
    3. Notify legal and compliance
    4. Prepare external communications
    
    ### Recovery Actions (24+ hours)
    1. Implement fixes
    2. Monitor for additional threats
    3. Conduct post-incident review
    4. Update security measures
    
    ## Malware Incident
    
    ### Detection and Analysis
    1. Identify infected systems
    2. Determine malware type
    3. Assess lateral movement
    4. Check for data exfiltration
    
    ### Containment and Eradication
    1. Isolate infected systems
    2. Remove malware
    3. Patch vulnerabilities
    4. Update security controls
  MARKDOWN
  format = "markdown"
  
  groups = ["Security", "DevOps", "SRE"]
  labels = ["security", "incident-response", "playbooks", "malware", "breach"]
}

Team-Specific Documentation

Create documentation organized by team function:

locals {
  team_docs = {
    frontend = {
      name        = "frontend-development-guide"
      description = "Frontend development standards and practices"
      content_file = "frontend-guide.md"
      groups      = ["Frontend", "Engineering"]
      labels      = ["frontend", "react", "development", "standards"]
    }
    backend = {
      name        = "backend-development-guide"
      description = "Backend development standards and API design"
      content_file = "backend-guide.md"
      groups      = ["Backend", "Engineering"]
      labels      = ["backend", "api", "development", "standards"]
    }
    devops = {
      name        = "devops-operational-procedures"
      description = "DevOps operational procedures and best practices"
      content_file = "devops-procedures.md"
      groups      = ["DevOps", "SRE"]
      labels      = ["devops", "operations", "procedures", "infrastructure"]
    }
    security = {
      name        = "security-guidelines"
      description = "Security guidelines and secure coding practices"
      content_file = "security-guidelines.md"
      groups      = ["Security", "Engineering", "DevOps"]
      labels      = ["security", "guidelines", "secure-coding", "compliance"]
    }
  }
}

resource "kubiya_knowledge" "team_documentation" {
  for_each = local.team_docs
  
  name        = each.value.name
  description = each.value.description
  content     = file("${path.module}/docs/${each.value.content_file}")
  format      = "markdown"
  
  groups = each.value.groups
  labels = each.value.labels
}

Arguments Reference

Required Arguments

name

string

required

The name of the knowledge resource. Must be unique within your organization.

description

string

required

A description of the knowledge resource’s content and purpose. Helps users understand what information is contained.

content

string

required

The actual content of the knowledge resource. Can be inline text or loaded from files using the file() function.

format

string

required

The format of the content. Supported formats include:

markdown - Markdown formatted text (recommended)
text - Plain text
json - JSON data structures
yaml - YAML formatted data
html - HTML formatted content

groups

array

required

List of groups that can access this knowledge resource. At least one group is required. Groups must exist in your Kubiya organization.

Optional Arguments

labels

array

Labels for categorizing and searching knowledge resources. Use consistent labeling for better organization and discoverability.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

string

The unique identifier of the knowledge resource.

created_at

string

The timestamp when the knowledge resource was created.

updated_at

string

The timestamp when the knowledge resource was last updated.

created_by

string

The email of the user who created the knowledge resource.

Content Organization Patterns

Structure your documentation for maximum clarity:

# Title

## Overview
Brief description of the topic

## Prerequisites
What users need to know or have

## Step-by-Step Instructions
1. First step
2. Second step
3. Third step

## Examples
Practical examples and use cases

## Troubleshooting
Common issues and solutions

## Related Resources
Links to other relevant knowledge

Import

Knowledge resources can be imported using their ID:

terraform import kubiya_knowledge.example <knowledge-id>

Best Practices

Content Management

Store knowledge content in version-controlled files for better change tracking
Use markdown format for documentation to ensure better readability and formatting
Keep content current with regular updates and reviews
Structure content with clear headings and logical organization

Access Control

Assign appropriate groups based on content sensitivity and relevance
Use granular group assignments to ensure proper access control
Review access permissions regularly to maintain security
Consider creating specialized groups for different types of content

Organization & Discovery

Use consistent labels for easy discovery and categorization
Implement a labeling taxonomy across your organization
Include practical examples in technical documentation
Cross-reference related knowledge resources using labels

Quality & Maintenance

Implement review processes for critical documentation updates
Test all code examples and procedures before publishing
Include troubleshooting sections for complex procedures
Set up regular review cycles for different types of content

Supported Content Formats

Format Support:

Markdown: Full markdown support with tables, code blocks, and formatting
Text: Plain text content for simple documentation
JSON: Structured data for configuration examples and schemas
YAML: Configuration files and structured data
HTML: Rich formatted content with custom styling

Content Limitations:

Maximum content size may be limited by platform tier
Binary content is not supported; use base64 encoding if needed
External references and links should be accessible to users
Keep content focused and relevant to avoid information overload

Compatibility

Requirements:

Kubiya Terraform Provider version >= 1.0.0
Terraform >= 1.0
Groups must exist in your Kubiya organization before being referenced
Content should be properly formatted according to the specified format type

Troubleshooting

Content Loading Issues

Access Control Problems

Search and Discovery Issues

Getting Started

Resources

​Prerequisites

​Quick Start

​Configuration Examples

​Advanced Configurations

​Arguments Reference

​Required Arguments

​Optional Arguments

​Attributes Reference

​Content Organization Patterns

​Import

​Best Practices

Content Management

Access Control

Organization & Discovery

Quality & Maintenance

​Supported Content Formats

​Compatibility

​Troubleshooting

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Optional Arguments

Attributes Reference

Content Organization Patterns

Import

Best Practices

Supported Content Formats

Compatibility

Troubleshooting