The kubiya_trigger resource allows you to create and manage workflow triggers in the Kubiya platform. This resource creates a workflow and automatically publishes it with a webhook trigger, providing a URL that can be used to execute the workflow via HTTP requests.
Triggers combine the power of workflows with webhook accessibility, enabling external systems to initiate complex automation processes with a simple HTTP call.

​
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. A configured runner (or use “kubiya-hosted” for cloud execution)

​
Quick Start

resource "kubiya_trigger" "simple_trigger" {
  name   = "hello-world-trigger"
  runner = "kubiya-hosted"
  
  workflow = jsonencode({
    name    = "Hello World Workflow"
    version = 1
    steps = [
      {
        name = "greeting"
        executor = {
          type = "command"
          config = {
            command = "echo 'Hello from Kubiya Workflow!'"
          }
        }
      }
    ]
  })
}

output "webhook_url" {
  value       = kubiya_trigger.simple_trigger.url
  sensitive   = true
  description = "POST to this URL to trigger the workflow"
}

​
Configuration Examples

Create a trigger with custom tool executors for system monitoring:
resource "kubiya_trigger" "monitoring_trigger" {
  name   = "system-health-check"
  runner = "kubiya-hosted"
  
  workflow = jsonencode({
    name    = "System Health Monitoring"
    version = 1
    steps = [
      {
        name        = "check-disk-usage"
        description = "Check disk usage on all systems"
        executor = {
          type = "tool"
          config = {
            tool_def = {
              name        = "disk-checker"
              description = "Check disk usage"
              type        = "docker"
              image       = "alpine:latest"
              content     = "df -h | awk '$5+0 > 80 {print \"Warning: \" $1 \" is \" $5 \" full\"}'"
            }
          }
        }
        output = "DISK_STATUS"
      },
      {
        name        = "check-memory"
        description = "Check memory usage"
        executor = {
          type = "tool"
          config = {
            tool_def = {
              name        = "memory-checker"
              description = "Check memory usage"
              type        = "docker"
              image       = "alpine:latest"
              content     = "free -m | awk 'NR==2{printf \"Memory Usage: %.2f%%\\n\", $3*100/$2}'"
            }
          }
        }
        output = "MEMORY_STATUS"
      },
      {
        name        = "generate-report"
        description = "Generate health report"
        executor = {
          type = "command"
          config = {
            command = "echo 'System Health Report Generated'"
          }
        }
      }
    ]
  })
}

​
Advanced Configurations

Create a trigger for automated database backups with S3 upload:
resource "kubiya_trigger" "backup_trigger" {
  name   = "database-backup"
  runner = "kubiya-hosted"
  
  workflow = jsonencode({
    name    = "Database Backup Workflow"
    version = 1
    steps = [
      {
        name        = "create-backup"
        description = "Create database backup"
        executor = {
          type = "command"
          config = {
            command = "pg_dump -h localhost -U postgres -d production > /tmp/backup_$(date +%Y%m%d_%H%M%S).sql"
          }
        }
        output = "BACKUP_FILE"
      },
      {
        name        = "compress-backup"
        description = "Compress backup file"
        depends     = ["create-backup"]
        executor = {
          type = "command"
          config = {
            command = "gzip /tmp/backup_*.sql"
          }
        }
      },
      {
        name        = "upload-to-s3"
        description = "Upload backup to S3"
        depends     = ["compress-backup"]
        executor = {
          type = "command"
          config = {
            command = "aws s3 cp /tmp/backup_*.sql.gz s3://company-backups/postgres/$(date +%Y/%m/%d)/"
          }
        }
      },
      {
        name        = "cleanup-local"
        description = "Clean up local backup files"
        depends     = ["upload-to-s3"]
        executor = {
          type = "command"
          config = {
            command = "rm -f /tmp/backup_*.sql.gz"
          }
        }
      },
      {
        name        = "verify-backup"
        description = "Verify backup in S3"
        depends     = ["upload-to-s3"]
        executor = {
          type = "command"
          config = {
            command = "aws s3 ls s3://company-backups/postgres/$(date +%Y/%m/%d)/ --recursive"
          }
        }
        output = "BACKUP_VERIFICATION"
      }
    ]
  })
}
Create a trigger for automated incident response:
resource "kubiya_trigger" "incident_response" {
  name   = "incident-response"
  runner = "kubiya-hosted"
  
  workflow = jsonencode({
    name    = "Incident Response Automation"
    version = 1
    steps = [
      {
        name        = "gather-metrics"
        description = "Collect system metrics"
        executor = {
          type = "tool"
          config = {
            tool_def = {
              name        = "metrics-collector"
              description = "Gather system metrics"
              type        = "docker"
              image       = "python:3.11-slim"
              with_files = [
                {
                  destination = "/collect_metrics.py"
                  content     = <<-PYTHON
                    import json
                    import datetime
                    
                    metrics = {
                        "timestamp": datetime.datetime.now().isoformat(),
                        "cpu_usage": "75%",
                        "memory_usage": "82%",
                        "disk_usage": "65%",
                        "active_connections": 1250,
                        "error_rate": "2.5%"
                    }
                    
                    print(json.dumps(metrics, indent=2))
                  PYTHON
                }
              ]
              content = "python /collect_metrics.py"
            }
          }
        }
        output = "SYSTEM_METRICS"
      },
      {
        name        = "analyze-logs"
        description = "Analyze error logs"
        depends     = ["gather-metrics"]
        executor = {
          type = "command"
          config = {
            command = "tail -n 100 /var/log/application.log | grep -i error | head -10"
          }
        }
        output = "ERROR_LOGS"
      },
      {
        name        = "create-incident-ticket"
        description = "Create JIRA incident ticket"
        depends     = ["analyze-logs"]
        executor = {
          type = "agent"
          config = {
            teammate_name = "incident-agent"
            message       = "Create a JIRA ticket for incident with metrics: ${SYSTEM_METRICS} and errors: ${ERROR_LOGS}"
          }
        }
        output = "TICKET_ID"
      },
      {
        name        = "notify-oncall"
        description = "Notify on-call team"
        depends     = ["create-incident-ticket"]
        executor = {
          type = "agent"
          config = {
            teammate_name = "notification-agent"
            message       = "Send Slack alert to #incidents about ticket ${TICKET_ID}"
          }
        }
      },
      {
        name        = "initiate-remediation"
        description = "Start auto-remediation"
        depends     = ["notify-oncall"]
        executor = {
          type = "command"
          config = {
            command = "kubectl scale deployment/app --replicas=5 && kubectl rollout restart deployment/app"
          }
        }
      }
    ]
  })
}

​
Triggering Workflows

Once the trigger resource is created, you can execute the workflow by making HTTP requests to the webhook URL. 
# Get the webhook URL from Terraform output
WEBHOOK_URL=$(terraform output -raw webhook_url)

# Trigger the workflow
curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -d '{}'

​
Arguments Reference

​
Required Arguments

​
name
string
required
Name of the trigger. This will be used as the workflow name and must be unique within your organization.
​
runner
string
required
Runner to use for executing the workflow. Common values:
  • kubiya-hosted - Use Kubiya’s cloud-hosted runners
  • Custom runner names from your organization
​
workflow
string
required
JSON-encoded workflow definition. Use jsonencode() for better readability. Structure includes:
​
workflow.name
string
required
Name of the workflow for identification.
​
workflow.version
number
required
Version number of the workflow. Increment when making changes.
​
workflow.steps
array
required
Array of workflow steps, each containing:
​
workflow.steps[].name
string
required
Unique name for the step within the workflow.
​
workflow.steps[].description
string
Description of what the step does.
​
workflow.steps[].executor
object
required
Executor configuration with type and config:
  • type: “command”, “tool”, or “agent”
  • config: Configuration object specific to the executor type
​
workflow.steps[].depends
array
Array of step names this step depends on for execution order.
​
workflow.steps[].output
string
Variable name to store step output for use in subsequent steps.

​
Attributes Reference

In addition to all arguments above, the following attributes are exported:
​
id
string
The unique identifier of the trigger.
​
url
string
The webhook URL for triggering the workflow (sensitive).
​
status
string
Current status of the workflow (e.g., “draft”, “published”).
​
workflow_id
string
The ID of the created workflow in Kubiya.

​
Import

Trigger resources can be imported using their ID: 
terraform import kubiya_trigger.example <trigger-id>

​
Best Practices

Security

  • Store the webhook URL as a sensitive output to prevent accidental exposure
  • Use proper authentication headers when triggering workflows
  • Implement input validation in your workflow steps
  • Restrict webhook access through network controls when possible

Workflow Design

  • Use descriptive names and descriptions for steps to improve maintainability
  • Design workflows to be idempotent where possible
  • Include error checking and recovery steps in your workflows
  • Use step dependencies to control execution order and enable parallelism

Versioning & Updates

  • Increment the workflow version when making significant changes
  • Test workflows in a non-production environment first
  • Document breaking changes in version updates
  • Keep backward compatibility when possible

Monitoring & Operations

  • Set up logging and monitoring for workflow executions
  • Implement proper error handling and notifications
  • Use output variables to pass data between steps
  • Monitor execution times and resource usage

​
Executor Types

Execute shell commands directly:
{
  "type": "command",
  "config": {
    "command": "echo 'Hello World' && ls -la"
  }
}

​
Compatibility

Requirements:
  • Kubiya Terraform Provider version >= 1.0.0
  • Terraform >= 1.0
  • The workflow is automatically published when the trigger resource is created
  • The webhook URL remains stable across updates unless the resource is recreated
Important Considerations:
  • Updating the workflow definition will update the published workflow
  • Deleting the trigger resource will delete both the workflow and webhook
  • Ensure proper runner permissions for workflow execution
  • Test complex workflows thoroughly before production deployment

​
Troubleshooting

  • Verify the runner is active and has proper permissions
  • Check workflow step dependencies for circular references
  • Ensure all required tools and images are accessible
  • Review step executor configurations for syntax errors
  • Verify the webhook URL is accessible and not blocked
  • Check authorization headers and API key validity
  • Ensure payload format matches workflow expectations
  • Review webhook logs for error messages
  • Validate that dependency step names match exactly
  • Check for circular dependencies in the workflow
  • Ensure dependent steps produce expected output variables
  • Review execution logs for dependency resolution errors