Skip to content

Run Ignite VMs declaratively

Flags can be convenient for simple use, but have many limitations. For more advanced use cases, and to allow GitOps flows, there is another way: telling Ignite what to do declaratively, using a file containing an API object.

The first commands to support this feature are ignite run and ignite create. Here's an example API object file contents:

kind: VM
  name: my-vm
    oci: weaveworks/ignite-ubuntu
  cpus: 2
  diskSize: 3GB
  memory: 800MB

This API object specifies a need for 2 vCPUs, 800 MB of RAM and 3 GB of disk space.

We can tell Ignite to make this happen by simply running:

$ ignite run --config my-vm.yaml
INFO[0001] Created VM with ID "e04128e6f96176a8" and name "my-vm"
INFO[0002] Networking is handled by "cni"
INFO[0002] Started Firecracker VM "e04128e6f96176a8" in a container with ID "ignite-e04128e6f96176a8"

The full reference format for the VM kind is as follows:

kind: VM
  # Automatically set when the object is created
  created: [RFC3339-formatted date]
  # Required, the name of the VM
  name: [string]
  # Optional, autogenerated if not specified
  uid: [16-char hex UID]
  # Optional, a string-string map with label keys and values
    foo: bar
  # Optional, a string-string map with annotation keys and values
    foo: bar
  # Optional, how many vCPUs should be allocated for the VM
  # Default: 1
  cpus: [uint64]
  # Optional, how much RAM should be allocated for the VM
  # Default: 512MB
  memory: [size]
  # Optional, how much free writable space the VM should have at runtime
  # Default: 4GB
  diskSize: [size]

    # Required, what OCI image to use as the VM's rootfs
    # For example: weaveworks/ignite-ubuntu:latest
    oci: [OCI image reference]
    # Optional, the kernel command line for the VM
    # Default: "console=ttyS0 reboot=k panic=1 pci=off ip=dhcp"
    cmdLine: [string]
    # Required, what OCI image to get the kernel binary (and optionally modules) from
    # Default: weaveworks/ignite-kernel:4.19.47
    oci:  [OCI image reference]

    # Optional, an array of port mappings that map ports bound to the VM to the host
    # Default: unset, no port mappings
    # This example maps UDP port inside the VM to on the physical host
    - hostPort: 433
      vmPort: 6443
      # Optional, specify an address to bind to on the host
      # Default:, any address
      # Optional, specify a protocol for the port mapping (tcp or udp)
      # Default: tcp
      protocol: udp

    # Optional, an array of mountPath and name pairs,
    # set the mount points for named volumes inside the VM.
    # Names must match configured named volumes.
    # Default: unset, no mount points
    - mountPath: /mnt
      name: volume0
    # Optional, an array of blockDevice and name pairs,
    # expose block devices on the host inside the VM.
    # The blockDevice path must point to a block device formatted
    # with a filesystem providing an UUID (such as ext4 or xfs).
    # Default: unset, no volume forwarding
    - blockDevice:
        path: /dev/sdb1
      name: volume0

  # Optional, an array of files/directories to copy into the VM on creation
  # Default: unset, nothing will be copied
  # This example copies a Kubernetes KubeConfig file from /etc/kubernetes/admin.conf
  # on the host to /home/user/.kube/config inside the VM
  - hostPath: /etc/kubernetes/admin.conf
    vmPath: /home/user/.kube/config

  # Optional, provides automation to easily access your VM with the "ignite ssh" command
  # If "ssh: true" is set, Ignite will generate an SSH key and copy the
  # public key into the VM. This allows for automatic "ignite ssh" logins.
  # Alternatively: specify a path to a public key to put in /root/.ssh/authorized_keys in the VM.
  # Default: unset, no actions regarding SSH automation
  ssh: [true, or public key path]

You can find the full API reference in the api/ subfolder of the project.