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:

apiVersion: ignite.weave.works/v1alpha3
kind: VM
metadata:
  name: my-vm
spec:
  image:
    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:

apiVersion: ignite.weave.works/v1alpha3
kind: VM
metadata:
  # 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
  labels:
    foo: bar
  # Optional, a string-string map with annotation keys and values
  annotations:
    foo: bar
spec:
  # 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]

  image:
    # Required, what OCI image to use as the VM's rootfs
    # For example: weaveworks/ignite-ubuntu:latest
    oci: [OCI image reference]
  kernel:
    # 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]
  sandbox:
    # Optional, what OCI image to use as the ignite sandbox.
    # Default: weaveworks/ignite
    oci: [OCI image reference]

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

  storage:
    # 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
    volumeMounts:
    - 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
    volumes:
    - 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
  copyFiles:
  # 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 pkg/apis/ subfolder of the project.