kubiya_scheduled_task

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:

A Kubiya account with API access
An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
At least one configured agent to execute
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

Multi-Environment Scheduling

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"
  }
}

Conditional Task Execution

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"
  }
}

Compliance and Audit Tasks

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:

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

Schedule Not Executing

Agent Execution Issues

Notification Problems

Getting Started

Resources

kubiya_scheduled_task

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Optional Arguments

Cron Expression Reference

Attributes Reference

Import

Best Practices

Scheduling Strategy

Task Design

Monitoring & Alerts

Documentation & Maintenance

Notification Methods

Compatibility

Troubleshooting

Getting Started

Resources

​Prerequisites

​Quick Start

​Configuration Examples

​Advanced Configurations

​Arguments Reference

​Required Arguments

​Optional Arguments

​Cron Expression Reference

​Attributes Reference

​Import

​Best Practices

Scheduling Strategy

Task Design

Monitoring & Alerts

Documentation & Maintenance

​Notification Methods

​Compatibility

​Troubleshooting

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Optional Arguments

Cron Expression Reference

Attributes Reference

Import

Best Practices

Notification Methods

Compatibility

Troubleshooting