How do idempotent runs work?

Background

tip

To learn about what idempotent runs are in Kurtosis and the motivation behind this feature, go here.

When running the kurtosis run command, you may notice the following message get printed:

SKIPPED - This instruction has already been run in this enclave

The reason this happens is because Kurtosis will optimize each run of a Starlark package based on what has already been run in a given enclave, thus reducing execution time and resources.

This means when you try to run the exact same package twice in a row, Kurtosis will skip all the instructions for the second run because they were already executed in the first run.

info

This feature is still experimental and can be deactivated by adding --experimental NO_INSTRUCTIONS_CACHING parameter to the kurtosis run command.

How it works

Definitions

The enclave plan is defined as the sequence of Starlark instructions that were previously executed inside a given enclave. Meanwhile, the submitted plan is defined as the set of instructions generated by interpreting the package before it gets executed.

Within a plan, whether it be an enclave or submitted plan, Kurtosis considers a given instruction instruction_2 to be dependent on another instruction instruction_1 if and only if instruction_2 is sequenced to take place after instruction_1 in the plan's instruction sequence.

Two instructions are said to be equivalent if and only if their Starlark representations are strictly equal.

Criteria to skip an instruction

Kurtosis uses the following heuristic to determine which parts of a plan to skip in order to optimize runs:

1. Any instruction from the submitted plan that is executed inside the enclave is appended to the enclave plan
2. For any given instruction from the submitted plan, it is effectively skipped (i.e. not executed) if:
   1. There exists one instruction in the enclave plan that is equivalent to this instruction in the enclave plan(called the matched instruction below)
   2. And if at least ONE of the following assertions is true:
      1. There is no direct dependent instruction for the given instruction in the submitted plan. Put it simply, it is the last instruction of the submitted plan.
      2. There is no direct dependent instruction for the matched instruction in the enclave plan. Put it simply, the matched instruction is the last instruction of the enclave plan.
      3. The sequence of direct dependent instructions for the matched instruction in the enclave plan is a prefix of the sequence of direct dependent instructions of the instruction from the submitted plan.

Examples

Case of a submitted plan being disjoint from the enclave plan

No instruction get skipped, all instructions from the submitted plan are appended to the enclave plan.

Case of a submitted plan being a sub-sequence of the enclave plan

All instructions from the submitted plan are skipped because they were all present in the enclave plan (therefore already executed inside this enclave).

Case of a submitted plan partially overlapping the enclave plan

The overlapping instructions from the submitted plan are skipped but the new ones (i.e. non-overlapping ones) are executed and appended to the enclave plan.

Case of a submitted plan incompatible with the enclave plan

Even though there are overlapping instructions in the submitted plan, the sequence of instructions itself is incompatible with the enclave plan because there exist at least one dependent instruction in the enclave plan that is not in the submitted plan. Kurtosis cannot optimize the submitted plan, and therefore falls back to the naive behaviour of considering the submitted plan as a sequence of new instructions.

Note that in this case, it is possible (and even likely) the execution of the submitted plan will fail. In the example above, execution will fail because instruction 1 is an add_service instruction and a service cannot be added twice within the same enclave.