Provision a KVM virtual machine on demand

id: kvm-provision-vm
namespace: company.infra

inputs:
  - id: vm_name
    type: STRING
    defaults: kestra-worker-01
    description: >
      Libvirt domain name to define and boot. Rendered directly into the domain
      XML, so it is constrained by a regex validator. Treat as a trusted,
      operator-supplied value, not free web input.
    validator: ^[a-z0-9][a-z0-9-]{0,62}$

  - id: memory_mib
    type: INT
    defaults: 2048
    description: Memory allocated to the VM in MiB.

  - id: vcpus
    type: INT
    defaults: 2
    description: Number of virtual CPUs.

  - id: base_volume
    type: STRING
    defaults: ubuntu-22.04-base.qcow2
    description: >
      Name of the read-only golden-image qcow2 in the default pool. The flow
      clones this into a fresh per-VM boot disk so provisioning is repeatable.

  - id: os_volume
    type: STRING
    defaults: kestra-worker-01-os.qcow2
    description: >
      Name of the per-VM boot disk to create in the default pool by cloning
      base_volume. Rendered into the domain XML; constrained by a regex
      validator.
    validator: ^[a-z0-9][a-z0-9._-]{0,127}$

  - id: disk_size_gb
    type: INT
    defaults: 20
    description: Size of the cloned boot disk in GiB.

variables:
  libvirt_uri: "{{ secret('LIBVIRT_URI') }}"

pluginDefaults:
  - type: io.kestra.plugin.kvm
    values:
      uri: "{{ vars.libvirt_uri }}"

concurrency:
  limit: 1

tasks:
  - id: clone_boot_disk
    type: io.kestra.plugin.scripts.shell.Commands
    description: >
      Create the per-VM boot disk by cloning the golden base image, so the flow
      provisions a real disk instead of assuming one was staged by hand.
    # Script tasks default to the Docker runner. This one needs host-side libvirt
    # tooling (qemu-img/virsh against the local hypervisor), so it uses the Process
    # runner to execute on the host. Remove this block to run in Docker, or switch
    # the type to Kubernetes/Docker if your hypervisor tooling lives in a container.
    taskRunner:
      type: io.kestra.plugin.core.runner.Process
    retry:
      type: constant
      interval: PT15S
      maxAttempt: 3
    env:
      LIBVIRT_DEFAULT_URI: "{{ vars.libvirt_uri }}"
      BASE_VOLUME: "{{ inputs.base_volume }}"
      OS_VOLUME: "{{ inputs.os_volume }}"
      DISK_SIZE_GB: "{{ inputs.disk_size_gb }}"
    commands:
      - set -euo pipefail
      - echo "Cloning ${BASE_VOLUME} into ${OS_VOLUME} in the default pool"
      - |
        if virsh vol-info --pool default "${OS_VOLUME}" >/dev/null 2>&1; then
          echo "Volume ${OS_VOLUME} already exists; reusing it (clone is idempotent by name)"
        else
          virsh vol-clone --pool default "${BASE_VOLUME}" "${OS_VOLUME}"
          virsh vol-resize --pool default "${OS_VOLUME}" "${DISK_SIZE_GB}G"
        fi
      - virsh vol-info --pool default "${OS_VOLUME}"

  - id: create_vm
    type: io.kestra.plugin.kvm.CreateVm
    description: >
      Define the libvirt domain from the rendered XML and boot it. CreateVm is
      idempotent by name: re-running keeps the definition in sync and the boot
      is a no-op if the domain is already running.
    name: "{{ inputs.vm_name }}"
    startAfterCreate: true
    retry:
      type: constant
      interval: PT15S
      maxAttempt: 3
    xmlDefinition: |
      <domain type='kvm'>
        <name>{{ inputs.vm_name }}</name>
        <memory unit='MiB'>{{ inputs.memory_mib }}</memory>
        <vcpu placement='static'>{{ inputs.vcpus }}</vcpu>
        <os>
          <type arch='x86_64' machine='pc-q35-6.2'>hvm</type>
          <boot dev='hd'/>
        </os>
        <devices>
          <disk type='volume' device='disk'>
            <driver name='qemu' type='qcow2'/>
            <source pool='default' volume='{{ inputs.os_volume }}'/>
            <target dev='vda' bus='virtio'/>
          </disk>
          <interface type='network'>
            <source network='default'/>
            <model type='virtio'/>
          </interface>
        </devices>
      </domain>

  - id: wait_for_running
    type: io.kestra.plugin.kvm.StartVm
    description: >
      Confirm the freshly defined domain reaches RUNNING before notifying.
      RUNNING means libvirt has started the domain; it does not guarantee the
      guest OS has finished booting or is reachable over the network.
    name: "{{ inputs.vm_name }}"
    waitForRunning: true
    timeToWait: PT2M
    retry:
      type: constant
      interval: PT15S
      maxAttempt: 3

  - id: notify_provisioned
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Post a Slack message announcing the domain reached RUNNING.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    retry:
      type: constant
      interval: PT10S
      maxAttempt: 3
    payload: |
      {
        "blocks": [
          {
            "type": "header",
            "text": {
              "type": "plain_text",
              "text": "VM reached RUNNING: {{ outputs.create_vm.name }}"
            }
          },
          {
            "type": "section",
            "fields": [
              {
                "type": "mrkdwn",
                "text": "*UUID:*\n{{ outputs.create_vm.uuid }}"
              },
              {
                "type": "mrkdwn",
                "text": "*State:*\n{{ outputs.wait_for_running.state }}"
              },
              {
                "type": "mrkdwn",
                "text": "*vCPUs:*\n{{ inputs.vcpus }}"
              },
              {
                "type": "mrkdwn",
                "text": "*Memory (MiB):*\n{{ inputs.memory_mib }}"
              }
            ]
          },
          {
            "type": "context",
            "elements": [
              {
                "type": "mrkdwn",
                "text": "Boot disk {{ inputs.os_volume }} cloned from {{ inputs.base_volume }} | execution {{ execution.id }}"
              }
            ]
          }
        ]
      }

errors:
  - id: alert_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert operators when provisioning fails so they learn about
      failures, not only successes.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    retry:
      type: constant
      interval: PT10S
      maxAttempt: 3
    messageText: ":rotating_light: {{ flow.namespace }}.{{ flow.id }} failed
      provisioning {{ inputs.vm_name }} (execution {{ execution.id }})."