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
Set the two releases. Replace
<running release>with the version the installation runs now, which the first line ofcheckshows. 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.
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-1Run
checkon the installation as it stands../vendor/valet-dedicated-$FROM checkYou 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-dedicatedYou 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-$TO2. Initialize Terraform
Run terraform init again so Terraform reads the new module.
terraform init -upgrade3. Apply the module
Read the plan.
terraform planApply 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" --planThe 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 15mYou 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-$FROMRoll 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.