Tracked run (deployment)

Tracked runs represent the actual changes to your infrastructure caused by changes to your infrastructure definitions and/or configuration. In that sense, they can be also called deployments. Tracked runs are effectively an extension of proposed runs - instead of stopping at the planning phase, they also allow you to apply the previewed changes.

They are presented on the Runs screen, which is the main screen of the Stack view:

Each of the tracked runs is represented by a separate element containing some information about the attempted deployment:

Also worth noting is the colorful strip present on some runs - as long as the planning phase was successful this visually represents the resources and outputs diff introduced by the change:

Triggering tracked runs

Tracked runs can be triggered in of the three ways - manually by the user, by a Git push or by a trigger policy.

Triggering manually

Any account admin or stack writer can trigger a tracked run on a stack:

Runs triggered by individuals and machine users are marked accordingly:

Run triggered by an individual
Run triggered by a machine user

Triggering from Git events

Tracked runs can also be triggered by Git push and tag events. By default, whenever a push occurs to the tracked branch, a tracked run is started - one for each of the affected stacks. This default behavior can be extensively customized using our push policies.

Runs triggered by Git push and/or tag events can are marked accordingly:

Triggering from policies

Trigger policies can be used to create sophisticated workflows representing arbitrarily complex processes like staged rollouts or cascading updates. This is an advanced topic, which is described in more detail in its dedicated section. But if you see something like this, be aware of the fact that a trigger policy must have been involved:

Handling no-op changes

If the planning phase detects no changes to the resources and outputs managed by the stack, the tracked run is considered a no-op. In that case it transitions directly from planning to finished state, just like a proposed run. Otherwise, it will go through the approval flow.

Approval flow

If the tracked run detects a change to its managed resources or outputs, it goes through the approval flow. This can be automated or manual.

The automated flow involves a direct transition between the planning and applying phase, without an extra human intervention. This is a convenient but not always the safest option.

Changes can be automatically applied if both these conditions are met:

Otherwise, the change will go through the manual flow described below.

Unconfirmed

If a change is detected and human approval is required, a tracked run will transition from the planning state to unconfirmed. At that point the worker node encrypts uploads the entire workspace to a dedicated S3 location and finishes its involvement with the run.

The resulting changes are shown to the user for the final approval:

If the user approves (confirms) the plan, the run transitions to the temporary Confirmed state and waits for a worker node to pick it up. If the user doesn't like the plan and discards it, the run transitions to the terminal Discarded state.

Unconfirmed is a passive state meaning no operations are performed while a run is in this state.

Discarded

Discarded state follows Unconfirmed and indicates that the user did not like the changes detected by the Planning phase.

Discarded is a passive state meaning no operations are performed while a run is in this state. It's also a terminal state meaning that no further state can supersede it.

Confirmed

Confirmed state follows Unconfirmed indicates that a user has accepted the plan generated in the Planning phase and wants to apply it but no worker has picked up the job yet. This state is similar to Queued in a sense that shows only temporarily until one of the workers picks up the associated job and changes the state to Applying. On the other hand, there is no way to stop a run once it's confirmed.

Confirmed is a passive state meaning no operations are performed while a run is in this state.

Applying

If the run required a manual approval step, this phase is preceded by another handover (preparing phase) since the run again needs to be yielded to a worker node. This preparing phase is subtly different internally but ultimately serves the same purpose from the user perspective. Here's an example:

This preparation phase is very unlikely to fail, but if it does (eg. the worker node becomes unavailable during the transition), the run will transition to the terminal failed state. If the handover succeeds, or the run does not go through the manual approval process, the applying phase begins and attempts to deploy the changes. Here's an example:

Success criteria

If the run is a no-op or the applying phase succeeds, the run transitions to the finished state. On the other hand, if anything goes wrong, the run is marked as failed.

Reporting

The results of tracked runs are reported in multiple ways: