The kubiya_scheduled_task resource allows you to create and manage scheduled tasks in the Kubiya platform. Scheduled tasks execute Kubiya agents on defined schedules using cron expressions, enabling automated recurring operations for monitoring, reporting, maintenance, and other routine activities.
Scheduled tasks are essential for automating recurring operations like health checks, backups, reports, and maintenance tasks, ensuring consistent operations without manual intervention.

Prerequisites

Before using this resource, ensure you have:
  1. A Kubiya account with API access
  2. An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
  3. At least one configured agent to execute
  4. Understanding of cron expression syntax

Quick Start

resource "kubiya_agent" "daily_reporter" {
  name         = "daily-reporter"
  runner       = "kubiya-hosted"
  description  = "Daily reporting agent"
  instructions = "You generate daily reports and summaries."
}

resource "kubiya_scheduled_task" "daily_report" {
  name        = "daily-status-report"
  description = "Generate daily status report"
  agent       = kubiya_agent.daily_reporter.name
  schedule    = "0 9 * * *"  # 9 AM daily
  prompt      = "Generate a comprehensive daily status report for all systems"
  enabled     = true
}

Configuration Examples

Schedule comprehensive weekly reporting tasks:
resource "kubiya_scheduled_task" "weekly_report" {
  name        = "weekly-infrastructure-report"
  description = "Generate weekly infrastructure report"
  agent       = "infrastructure-agent"
  schedule    = "0 10 * * MON"  # 10 AM every Monday
  prompt      = <<-EOT
    Generate a comprehensive weekly infrastructure report including:
    - Resource utilization trends
    - Incident summary
    - Performance metrics
    - Cost analysis
    - Recommendations for optimization
  EOT
  enabled     = true
  
  notification {
    method      = "Email"
    destination = "team@example.com"
  }
}

Advanced Configurations

Create scheduled tasks across different environments with varying frequencies:
locals {
  environments = {
    dev = {
      schedule = "0 6 * * *"  # 6 AM daily
      prompt   = "Check development environment health"
      enabled  = false  # Disable for development
    }
    staging = {
      schedule = "0 7 * * *"  # 7 AM daily
      prompt   = "Verify staging environment readiness"
      enabled  = true
    }
    prod = {
      schedule = "*/10 * * * *"  # Every 10 minutes
      prompt   = "Monitor production environment health and performance"
      enabled  = true
    }
  }
}

resource "kubiya_agent" "env_monitors" {
  for_each = local.environments
  
  name         = "${each.key}-monitor"
  runner       = "kubiya-hosted"
  description  = "Monitor for ${each.key} environment"
  instructions = "You monitor the ${each.key} environment health and performance."
  
  environment_variables = {
    ENVIRONMENT = each.key
    LOG_LEVEL   = each.key == "prod" ? "INFO" : "DEBUG"
  }
}

resource "kubiya_scheduled_task" "env_tasks" {
  for_each = local.environments
  
  name        = "${each.key}-health-check"
  description = "Health check for ${each.key} environment"
  agent       = kubiya_agent.env_monitors[each.key].name
  schedule    = each.value.schedule
  prompt      = each.value.prompt
  enabled     = each.value.enabled
  
  notification {
    method      = "Slack"
    destination = "#${each.key}-alerts"
  }
}
Create tasks that perform different actions based on conditions:
resource "kubiya_scheduled_task" "conditional_task" {
  name        = "conditional-deployment-check"
  description = "Check deployments based on conditions"
  agent       = "deployment-agent"
  schedule    = "0 */4 * * *"  # Every 4 hours
  prompt      = <<-EOT
    Check if there are pending deployments:
    1. If pending deployments exist, validate them
    2. If validation passes, approve for next window
    3. If no pending deployments, check system health
    4. Generate appropriate report based on findings
  EOT
  enabled     = true
  
  notification {
    method      = "Slack"
    destination = "#deployments"
  }
}

resource "kubiya_scheduled_task" "smart_scaling" {
  name        = "smart-resource-scaling"
  description = "Intelligent resource scaling based on usage patterns"
  agent       = "scaling-agent"
  schedule    = "*/30 * * * *"  # Every 30 minutes
  prompt      = <<-EOT
    Analyze current resource usage and demand patterns:
    1. Check CPU, memory, and network utilization
    2. Review historical usage patterns for this time of day
    3. Predict upcoming demand based on trends
    4. Scale resources up or down as needed
    5. Report scaling actions taken
  EOT
  enabled     = true
  
  notification {
    method      = "Slack"
    destination = "#infrastructure"
  }
}
Schedule compliance checking and audit tasks:
resource "kubiya_agent" "compliance_agent" {
  name         = "compliance-auditor"
  runner       = "kubiya-hosted"
  description  = "Compliance and security audit agent"
  instructions = <<-EOT
    You perform compliance checks and security audits:
    - Verify access controls and permissions
    - Check for policy violations
    - Generate compliance reports
    - Monitor for security incidents
  EOT
  
  integrations = ["aws", "github", "slack_integration"]
  groups       = ["Security", "Compliance"]
}

# Daily security checks
resource "kubiya_scheduled_task" "daily_security_scan" {
  name        = "daily-security-compliance-check"
  description = "Daily security and compliance verification"
  agent       = kubiya_agent.compliance_agent.name
  schedule    = "0 8 * * *"  # 8 AM daily
  prompt      = "Perform daily security compliance check: access controls, policy adherence, and security posture"
  enabled     = true
  
  notification {
    method      = "Slack"
    destination = "#security-alerts"
  }
}

# Weekly compliance report
resource "kubiya_scheduled_task" "weekly_compliance_report" {
  name        = "weekly-compliance-report"
  description = "Generate weekly compliance report"
  agent       = kubiya_agent.compliance_agent.name
  schedule    = "0 9 * * FRI"  # 9 AM every Friday
  prompt      = "Generate comprehensive weekly compliance report with findings and recommendations"
  enabled     = true
  
  notification {
    method      = "Email"
    destination = "compliance@example.com"
  }
}

# Monthly audit
resource "kubiya_scheduled_task" "monthly_audit" {
  name        = "monthly-security-audit"
  description = "Monthly comprehensive security audit"
  agent       = kubiya_agent.compliance_agent.name
  schedule    = "0 10 1 * *"  # 10 AM on 1st of each month
  prompt      = "Conduct comprehensive monthly security audit including penetration testing and vulnerability assessment"
  enabled     = true
  
  notification {
    method      = "Teams"
    team_name   = "Security Team"
    destination = "Audit Reports"
  }
}

Arguments Reference

Required Arguments

name
string
required
The name of the scheduled task. Must be unique within your organization.
description
string
required
A description of the scheduled task’s purpose and functionality.
agent
string
required
The name of the agent to execute when the task runs.
schedule
string
required
Cron expression defining when the task should run. Format: “minute hour day month weekday”.
prompt
string
required
The prompt to send to the agent when the task executes. This guides the agent’s actions.

Optional Arguments

enabled
boolean
default:"true"
Whether the scheduled task is enabled and will execute on schedule.
notification
object
Notification configuration for task execution results:
notification.method
string
required
Notification method. Available options:
  • Slack - Send notifications to Slack channels
  • Email - Send email notifications
  • Http - Send HTTP webhook notifications
  • Teams - Send Microsoft Teams notifications
notification.destination
string
required
Destination for notifications:
  • Slack: Channel name with ”#” prefix or username with ”@” prefix
  • Email: Email address or distribution list
  • Http: Webhook URL for HTTP notifications
  • Teams: Channel name within the specified team
notification.team_name
string
Team name for Microsoft Teams notifications. Required when method is “Teams”.

Cron Expression Reference

The schedule uses standard cron expression format:
* * * * *
│ │ │ │ │
│ │ │ │ └─── Day of week (0-7, MON-SUN)
│ │ │ └───── Month (1-12, JAN-DEC)
│ │ └─────── Day of month (1-31)
│ └───────── Hour (0-23)
└─────────── Minute (0-59)
# Every minute
* * * * *

# Every 15 minutes
*/15 * * * *

# Every hour at minute 0
0 * * * *

# Daily at 9 AM
0 9 * * *

# Daily at 2:30 AM
30 2 * * *

Attributes Reference

In addition to all arguments above, the following attributes are exported:
id
string
The unique identifier of the scheduled task.
created_at
string
The timestamp when the scheduled task was created.
updated_at
string
The timestamp when the scheduled task was last updated.
last_run
string
The timestamp of the last execution.
next_run
string
The timestamp of the next scheduled execution.
status
string
The current status of the scheduled task.

Import

Scheduled tasks can be imported using their ID:
terraform import kubiya_scheduled_task.example <scheduled-task-id>

Best Practices

Scheduling Strategy

  • Be aware that schedules run in UTC; adjust accordingly for your timezone
  • Avoid overly frequent schedules that may overwhelm the system
  • Schedule intensive tasks during off-peak hours
  • Consider business hours and maintenance windows when setting schedules

Task Design

  • Design tasks to be idempotent to handle potential reruns safely
  • Include error handling and recovery logic in agent prompts
  • Use clear, specific prompts that define expected outcomes
  • Test schedules in development before production deployment

Monitoring & Alerts

  • Configure appropriate notifications for critical tasks
  • Monitor task execution history and success rates
  • Set up alerts for task failures or missed executions
  • Use different notification channels for different types of tasks

Documentation & Maintenance

  • Document the purpose and expected behavior of each task
  • Include contact information for task owners
  • Regular review and cleanup of obsolete scheduled tasks
  • Version control your scheduled task configurations

Notification Methods

notification {
  method      = "Slack"
  destination = "#infrastructure-alerts"
}

# Or notify specific users
notification {
  method      = "Slack"
  destination = "@oncall-engineer"
}

Compatibility

Requirements:
  • Kubiya Terraform Provider version >= 1.0.0
  • Terraform >= 1.0
  • Cron expressions are evaluated in UTC by default
  • Agent must exist and be accessible before task creation
Limitations:
  • Minimum schedule frequency may be limited by platform tier
  • Very frequent schedules (e.g., every minute) may be subject to rate limiting
  • Task execution time limits apply based on your platform configuration
  • Notification delivery depends on integration configuration

Troubleshooting

  • Verify the cron expression syntax is correct
  • Check that the task is enabled
  • Ensure the agent exists and is accessible
  • Review timezone considerations (schedules run in UTC)
  • Check platform limits on schedule frequency
  • Verify the agent name exactly matches an existing agent
  • Check that the agent has proper permissions and integrations
  • Ensure the prompt is clear and actionable
  • Review agent instructions for task compatibility
  • Verify notification method configuration
  • Check destination format (channels, emails, URLs)
  • Ensure integrations are properly configured
  • Test notification channels independently