Preview a change

Goal

For feature teams. In this task you run joomiz plan to see what joomiz apply would change in one environment. A plan changes nothing.

Before you start

Register your application, and check your file with joomiz validate.
Choose the environment. The name must be in the environments key of your file, for example test.
Sign in, and set JOOMIZ_SERVER_URL.

Steps

Run the command

joomiz plan --environment test

You see:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  target/cloud-foundry-space: succeeded — Planned 1 change for target/cloud-foundry-space.
    test-foundation (created): succeeded — Would create 'test-foundation' (target/cloud-foundry-space) in environment 'test'. Nothing was changed.
      outputs.org-guid: 3b1f6c0e-52a4-4d8e-9a7b-0c4e8d2f7a11
      outputs.space-guid: 9d2e4b7a-61c3-4f05-8b3a-5e7c1a0d9f22
  managed-resource/postgres: succeeded — Planned 1 change for managed-resource/postgres.
    shop-db (created): succeeded — Would create 'shop-db' (managed-resource/postgres) in environment 'test'. Nothing was changed.
      outputs.password: https://vault.example.com/secrets/quick-start-shop-db-password
  deployment/cloud-foundry-app: succeeded — Planned 1 change for deployment/cloud-foundry-app.
    shop-test-deployment (created): succeeded — Would create 'shop-test-deployment' (deployment/cloud-foundry-app) in environment 'test'. Nothing was changed. 1 spec value is not known until apply.
      env.DB_PASSWORD: (known after apply)
  3 resource types, 3 resources
plan succeeded (revision 736be6a9-2dfe-4d17-b493-375814064ef5, plan ae519fe1-052d-41e0-8b4d-56e4e6547c3b)

Read the plan

Read the output from the top:

Each block starts with a category and a type, for example managed-resource/postgres. The block holds the resources of one type.
A resource line shows the resource ID and then its change in parentheses: (created), (updated) or (removed). This guide says delete for removed.
The text after succeeded — comes from the provisioner. Your platform might word it in another way. A plan never changes anything.
A line outputs.<name> shows an output that the provisioner reports. A sensitive output shows the address of a secret, not the secret.
The blocks come in an order that fits the references: a database comes before the deployment that uses its password.
The last line gives the revision of your file and the ID of the plan. A revision is one exact file that was submitted for an application, identified by a hash.

A resource that does not change is not in the plan. When nothing changes, the plan says so:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  0 resource types, 0 resources
plan succeeded (revision 736be6a9-2dfe-4d17-b493-375814064ef5, plan a841ec56-ba28-4190-9c92-4556449a8fff)

Read known after apply

The line env.DB_PASSWORD: (known after apply) means that the value does not exist yet. A plan never fills a reference to an output. Point one value at another explains this.

Read the drift block

Before a plan computes the changes, it asks each provisioner what really exists. If a resource differs from what Joomiz recorded, the plan shows a block that starts with Drift detected. Find and fix drift explains it.

Read an incomplete plan

Sometimes a provisioner cannot answer. The plan then says that the drift check is incomplete. The CLI prints the word incomplete for this case. Here the provisioner of the database was not reachable:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  warning: drift detection failed for managed-resource/postgres: unreachable
plan succeeded, but incomplete (revision 736be6a9-2dfe-4d17-b493-375814064ef5, plan 40a498ec-8d32-4670-bb7b-41a9397f0257)
  0 resource types, 0 resources
incomplete: drift was not checked for 1 resource type and 0 resources. The plan may miss changes.

The plan still exits with 0, because the control plane gave a complete answer with a warning. A pipeline that must not go on without a complete check adds --strict. The plan then exits with 5:

joomiz plan --environment test --strict

You see the same text, and the exit code 5:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  warning: drift detection failed for managed-resource/postgres: unreachable
plan succeeded, but incomplete (revision 736be6a9-2dfe-4d17-b493-375814064ef5, plan e3ff529c-2072-4224-b1ce-12ac98ffecc6)
  0 resource types, 0 resources
incomplete: drift was not checked for 1 resource type and 0 resources. The plan may miss changes.

Wait for slow provisioners

A provisioner can take a long time. While a step runs, the control plane sends a blank line every 5 seconds, so the CLI knows that the plan is alive. The CLI stops when it receives nothing for 20 seconds. It also stops when a plan takes longer than 5 minutes. It then names the run, so that you can look at it with joomiz runs show. Read your runs explains runs.

Plan while an apply runs

A plan never takes the apply lock, and an apply in the same environment does not block a plan.

Check

A good plan ends with plan succeeded, and its exit code is 0. Read each change. The plan is the preview of what the next apply does with the same file.

Troubleshooting

Symptom	Cause	Fix
`Missing required option: '--environment=<name>'` and exit code `2`	You did not name an environment.	Add `--environment` with a name from your file.
`this file declares no environment named`	The name is not in `environments`.	Use a name from the file.
`No provisioner registered`	No provisioner handles a type of your file.	Tell your platform team the type.
`plan failed` and a line `failed` under a resource	A provisioner answered with an error.	Read the message under the resource. Tell your platform team if it is not about your file.
`plan succeeded, but incomplete`	A provisioner could not check drift.	Plan again later, or use `--strict` in a pipeline.

Make the change in Make a change.