Find and fix drift

For feature teams. This page explains what Joomiz does when someone changes a resource by hand after an apply.

What drift is

Drift is a difference between the applied state and what really exists. Someone can change a resource outside Joomiz, for example the size of a database. Joomiz does not see the change until the next plan.

How Joomiz works explains the applied state.

How a plan shows drift

Before a plan computes the changes, it asks each provisioner what really exists. If a resource differs from what Joomiz recorded at the last apply, the plan starts with a drift block.

In this example, someone changed the storage of a database to 21 GB. The file and the record say 20 GB:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  Drift detected: 1 resource differs from what Joomiz recorded; the plan below restores the file's values
    managed-resource/postgres shop-db-drift-spec-storage-gb: changed
      storage-gb: recorded 20, real 21
  managed-resource/postgres: succeeded — Planned 1 change for managed-resource/postgres.
    shop-db-drift-spec-storage-gb (updated): succeeded — Would update 'shop-db-drift-spec-storage-gb' (managed-resource/postgres) in environment 'test'. Nothing was changed.
      outputs.password: https://vault.example.com/secrets/quick-start-shop-db-password
  1 resource type, 1 resource
plan succeeded (revision 14872eff-26fc-4254-8db6-65cf082f9930, plan 230874a3-9e1f-4184-bf68-2170d2558fe2)

Read the block:

The line Drift detected says how many resources differ from the record.
Under it, each line names the category and the type, the resource ID, and the printed word changed. This guide says different.
A line below it names the setting: storage-gb: recorded 20, real 21.
The plan then lists the change that puts the values of your file back. Here the database gets an (updated) line.

What a plan does about drift

A plan restores the values of your file. It does not take the real values into your file. If the real value is the one you want, change your file to it, and plan again.

Fix the drift

Apply the plan. The apply sets the resource back to the values of your file:

applied joomiz.yaml to environment test (via https://joomiz.example.com/apply?environment=test)
  managed-resource/postgres: succeeded — Applied 1 change for managed-resource/postgres.
    shop-db-drift-spec-storage-gb (updated): succeeded — Updated 'shop-db-drift-spec-storage-gb' (managed-resource/postgres) in environment 'test'. Nothing real was changed — this is a stub.
      outputs.password: https://vault.example.com/secrets/quick-start-shop-db-password
  1 resource type, 1 resource
apply succeeded (plan 230874a3-9e1f-4184-bf68-2170d2558fe2, apply 356fc479-80bf-4ae9-990e-17b16cf0f992)

Plan again. A plan with no changes and no drift block shows that the real resource and your file agree:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  0 resource types, 0 resources
plan succeeded (revision 14872eff-26fc-4254-8db6-65cf082f9930, plan f52a3e71-6f68-4511-86f7-8a37c84a2a20)

Which values you see

For a number or a value that is true or false, the plan shows the recorded value and the real value.
For a text value, the plan says that the value differs, and it shows only the recorded value:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  Drift detected: 1 resource differs from what Joomiz recorded; the plan below restores the file's values
    managed-resource/postgres shop-db-drift-spec-flavor: changed
      flavor: differs (recorded "cf-plan-small")
  managed-resource/postgres: succeeded — Planned 1 change for managed-resource/postgres.
    shop-db-drift-spec-flavor (updated): succeeded — Would update 'shop-db-drift-spec-flavor' (managed-resource/postgres) in environment 'test'. Nothing was changed.
      outputs.password: https://vault.example.com/secrets/quick-start-shop-db-password
  1 resource type, 1 resource
plan succeeded (revision d72081f3-4918-4d33-a4d6-07f17d0be9b7, plan 98e60d90-b4c4-4553-8cdb-f8b138120a87)

A setting that holds a ${{ ... }} reference is not compared.
A resource that does not exist any more is printed as absent. This guide says missing. The plan creates the resource again.

When drift cannot be checked

A provisioner may not answer, or it may say that it cannot read a resource. The plan then says so, and it does not call the resource different. A plan that could not check some resources ends with the line incomplete. Preview a change shows the output and the option --strict for a pipeline.

Learn what to do when a command fails in Fix an error.