Operator guide for Valet Dedicated 0.10.1

Upgrade

An upgrade moves an installation to a new release. It follows the same order as the install: fetch, apply, upgrade, check.

An upgrade only moves forward. upgrade migrates the database, and an older release does not run against a newer database. If a release misbehaves, tell Valet. Valet fixes it in a newer release, and you upgrade to that one.

Run each command from a machine that reaches the installation, as in Install.

List the published releases with valet-dedicated releases list. check warns when a newer one exists. An unavailable index is only a warning; it does not make an otherwise healthy installation fail.

Before you start

  1. Set the two releases. Replace <running release> with the version the installation runs now, which the first line of check shows. Replace <new release> with the version Valet told you to install.

    FROM=<running release>
    TO=<new release>

    Every command on this page uses them, so run it in this shell.

  2. Read the new release's notes.md. It lists what changed and anything you must do first.

    aws s3 cp s3://valet-dedicated-releases/releases/$TO/notes.md - \
      --region us-east-1
  3. Run check on the installation as it stands.

    ./vendor/valet-dedicated-$FROM check

    You see a check mark on every line. Fix each cross before you continue.

1. Fetch the new release

Fetch into the directory of the earlier fetch. Fetch replaces its module, and your module block's source stays the same.

./vendor/valet-dedicated-$FROM releases fetch "$TO" --dir vendor/valet-dedicated

You see the module path and the new binary, vendor/valet-dedicated-<new release>. Fetch verifies both against the manifest. It writes nothing if a check fails.

Use the new binary from here on:

export VD=./vendor/valet-dedicated-$TO

2. Initialize Terraform

Run terraform init again so Terraform reads the new module.

terraform init -upgrade

3. Apply the module

  1. Read the plan.

    terraform plan
  2. Apply it.

    terraform apply

A change to a task's configuration takes effect at the next upgrade, not at the apply. The services keep running on the old release until then.

Read the plan before you apply it. A plan that replaces the database or a bucket is not an upgrade. Stop and ask Valet.

4. Run the upgrade

Preview the changes after applying the module:

$VD upgrade "$TO" --plan

The plan shows images, task definitions, service counts, migrations, catalog reconciliation, and any required snapshot. It writes nothing. Upgrade refuses a mismatched module, a downgrade, or a release that does not name your installed version as a predecessor. Ask Valet when refused; there is no override for an unsafe release path.

Run the upgrade:

$VD upgrade "$TO"

upgrade takes a lock on the installation, so two operators cannot upgrade at once. First it verifies the release's catalog snapshot and uploads missing objects into your catalog bucket. A repeat uploads nothing. A digest mismatch stops before any service deployment.

Before migration, it creates <name>-pre-<version> when the release raises the recorded schema floor. Stable version dots become hyphens. Other tags use letters, digits, and single hyphens with a digest suffix. Names stay within 255 characters; truncation also adds a digest suffix. Upgrade waits for the snapshot to become available. A retry reuses that snapshot; status and the deployment record name it only after it becomes available. To restore from it, see Restore.

It copies the new images, migrates the database, registers new task definitions, updates only the services that changed, and waits until they answer. After health checks, it reconciles catalog rows inside your VPC. It writes a deployment record whether it succeeds or fails. A failed reconciliation fails the upgrade; read the task logs and retry.

You see Catalog ready: <count> objects uploaded to <bucket-prefix>, then the deployment steps and Running catalog reconciliation.... The last line names the deployment record.

A retry reuses completed work and skips migrations already recorded as applied. It still runs settings bootstrap and catalog reconciliation. Before submitting migration, upgrade writes a durable intent. An unfinished migration requires retrying that version or choosing a newer release that lists it as a predecessor. A preparation failure imposes no new target restriction. Never delete records to bypass the check. See Troubleshoot for the errors you may see.

5. Check the installation

$VD check --wait 15m

You see a check mark on every line. check also reports the running release, which must be the one you just installed.

6. Clean up

Remove the old binary. The new binary replaces it for every command.

rm ./vendor/valet-dedicated-$FROM

Roll tasks after a secret change

Preview with $VD roll, then run $VD roll --yes to replace platform tasks. Use --service api to select one service. Use $VD roll --runtimes --yes to replace running runtimes in batches. Platform rolls preserve each service's task definition and count. Runtime replacements use the currently configured runtime image and keep each process's active release. Neither command runs migrations.