Run Units

Run phases

Kapps pass through various run phases as part of their lifecycle. The phases are:

  • plan_install - plans the installation of kapps but shouldn’t make any destructive changes to the target cluster. Good uses for this phase would be to lint helm charts or run terraform plan. This phase is executed when running kapps install without the --yes/-y flag.
  • apply_install - should actually install kapps. This phase is executed when running kapps install with the --yes/-y flag.
  • plan_delete - this phase should explain what destructive changes will be made to the cluster but not actually execute any. It should provide sufficient output for someone to feel confident approving the deletion. This phase is executed when running kapps delete without the --yes/-y flag.
  • apply_delete - kapps should actually be deleted. This phase is executed when running kapps delete with the --yes/-y flag.
  • output - if the kapp produces output, these commands generate it. This phase is executed multiple times while installing/deleting kapps, and also when running kapps output.
  • clean - used to delete generated files, etc. from the the kapp’s workspace directory. This phase is executed when running kapps clean.

To speed up development the kapps install command has a --one-shot flag. When this is given Sugarkube will execute plan_install and then immediately execute apply_install as if you’d invoked kapps install first without the --yes/-y flag and then again with it.

Sugarkube doesn’t track what’s already been installed/deleted from a cluster. What it’ll install or delete for any given invocation is entirely controlled by selectors and the DAG for the target stack. For this to work, kapps must be able to be installed multiple times without adverse effects; installing kapps must be idempotent. However the same is not true of deletions. Kapps can fail if Sugarkube attempts to delete an already deleted kapp.

Run units

Run units encapsulate the list of commands to execute for each of the above run phases. Run units have the following configuration:

  • working_dir - the name of the directory to execute commands from
  • conditions - a list of conditions that must evaluate to the string true. If any evaluate to the string false the entire run unit will not be executed
  • plan_install - a list of run steps for this phase
  • apply_install - a list of run steps for this phase
  • plan_delete - a list of run steps for this phase
  • apply_delete - a list of run steps for this phase
  • output - a list of run steps for this phase
  • clean - a list of run steps for this phase

Run steps

Run steps have the following configuration:

  • name (required) - a name for this run step
  • command (required) - the path to the binary to execute for this step
  • args - a single string containg all the arguments for the command. The string will be tokenised similarly to how the shell would tokenise it (i.e. splitting on whitespace while respecting quotes)
  • env_vars - a map of environment variables to set while executing the command
  • stdout - the path to write stdout to
  • stderr - the path to write stderr to
  • print - if set to verbose, stdout/stderr will be printed to the console when sugarkube is run with the --verbose/-v flag. Any other non-empty value will always cause output to be printed regardless
  • expected_exit_code - use this to tell Sugarkube that if the command exits with a particular non-zero error code it’s not an error. The value of this setting should be the numeric value of the error code the command returns on success. You don’t need to use this setting if the command returns 0 on success.
  • conditions - a list of conditions that must evaluate to true. If any evaluate to false the run step will not be executed
  • working_dir - the name of the directory to execute commands from
  • merge_priority - an integer value. The lower the number the earlier the step will be executed when all a kapp’s run units are merged together. This allows control over how commands are interleaved when merging the steps for run phases from different run units together
  • call - the name of another run step or an entire run phase to execute.
  • load_outputs - instructs Sugarkube to load and parse any outputs defined by the kapp after running this step. This makes it easy to ,make output from one run step available in a subsequent one.
  • timeout - number of seconds the command must complete within

You can see examples of defining run steps in our sample kapps. You’ll probably rarely need to declare so many run steps, but this is a comprehensive example that shows how flexible run steps are.