# Run Strategies

## Overview

VirtualMachines have a `Running` setting that determines whether or not there should be a guest running or not. Because KubeVirt will always immediately restart a VirtualMachineInstance for VirtualMachines with `spec.running: true`, a simple boolean is not always enough to fully describe desired behavior. For instance, there are cases when a user would like the ability to shut down a guest from inside the virtual machine. With `spec.running: true`, KubeVirt would immediately restart the VirtualMachineInstance.

## RunStrategy

To allow for greater variation of user states, the `RunStrategy` field has been introduced. This is mutually exclusive with `Running` as they have somewhat overlapping conditions. There are currently four RunStrategies defined:

* Always: A VirtualMachineInstance will always be present. If the VirtualMachineInstance crashed, a new one will be spawned. This is the same behavior as `spec.running: true`.
* RerunOnFailure: A VirtualMachineInstance will be respawned if the previous instance failed in an error state. It will not be re-created if the guest stopped successfully (e.g. shut down from inside guest).
* Manual: The presence of a VirtualMachineInstance or lack thereof is controlled exclusively by the start/stop/restart VirtualMachine subresource endpoints.
* Halted: No VirtualMachineInstance will be present. If a guest is already running, it will be stopped. This is the same behavior as `spec.running: false`.

*Note*: RunStrategy and Running are mutually exclusive, because they can be contradictory. The API server will reject VirtualMachine resources that define both.

### Virtctl

The `start`, `stop` and `restart` methods of virtctl will invoke their respective subresources of VirtualMachines. This can have an effect on the runStrategy of the VirtualMachine as below:

| RunStrategy        | start    | stop     | restart          |
| ------------------ | -------- | -------- | ---------------- |
| **Always**         | `-`      | `Halted` | `Always`         |
| **RerunOnFailure** | `-`      | `Halted` | `RerunOnFailure` |
| **Manual**         | `Manual` | `Manual` | `Manual`         |
| **Halted**         | `Always` | `-`      | `-`              |

Table entries marked with `-` don't make sense, so won't have an effect on RunStrategy.

## RunStrategy Examples

### Always

An example usage of the Always RunStrategy.

```
apiVersion: kubevirt.io/v1alpha3
kind: VirtualMachine
metadata:
  labels:
    kubevirt.io/vm: vm-cirros
  name: vm-cirros
spec:
  runStrategy: Always
  template:
    metadata:
      labels:
        kubevirt.io/vm: vm-cirros
    spec:
      domain:
        devices:
          disks:
          - disk:
              bus: virtio
            name: containerdisk
      terminationGracePeriodSeconds: 0
      volumes:
      - containerDisk:
          image: kubevirt/cirros-container-disk-demo:latest
        name: containerdisk
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kubevirtlegacy.gitbook.io/user-guide/docs/virtual_machines/run_strategies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.