kubiya_trigger

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:

A Kubiya account with API access
An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
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

Database Backup Automation

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

Incident Response Automation

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:

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

Workflow Execution Issues

Webhook Trigger Problems

Step Dependency Issues

Getting Started

Resources

kubiya_trigger

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Triggering Workflows

Arguments Reference

Required Arguments

Attributes Reference

Import

Best Practices

Security

Workflow Design

Versioning & Updates

Monitoring & Operations

Executor Types

Compatibility

Troubleshooting

Getting Started

Resources

​Prerequisites

​Quick Start

​Configuration Examples

​Advanced Configurations

​Triggering Workflows

​Arguments Reference

​Required Arguments

​Attributes Reference

​Import

​Best Practices

Security

Workflow Design

Versioning & Updates

Monitoring & Operations

​Executor Types

​Compatibility

​Troubleshooting

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Triggering Workflows

Arguments Reference

Required Arguments

Attributes Reference

Import

Best Practices

Executor Types

Compatibility

Troubleshooting