ryvn update to change a few fields on a resource and leave everything else alone. Use ryvn replace to overwrite a resource with a complete file. Both change resources through the same API as the dashboard, and neither watches a task. To follow what a change started, see Tasks and approvals.
For install, authentication, and the other verbs, see CLI.
Choose update or replace
update merges your patch into the current resource. replace treats the file as the whole resource. Anything the file omits can be removed or returned to its default or inherited value, so a partial file can wipe config, env vars, secrets, variable groups, autoscaling, or networking. See Replace a resource.
Read, then patch
Read the current resource first. A patch uses the same field names thatget -o yaml prints, so you can copy the shape of the fields you change from that output.
Installations and blueprint installations need
-e <environment>, because their names are unique only within an environment.
Patch a resource
-p or --patch-file, not both. A patch is required. Prefer a file for multi-line values such as spec.config, because inline JSON is easy to mangle. Inline patches also land in your shell history and process list, which matters for anything sensitive.
Put the fields you change under spec, as get -o yaml shows them. A field at the top level of the patch, such as releaseChannel without spec, is rejected as unknown.
Which kinds update accepts
ryvn update <kind> <name> accepts these kinds:
environment, service, and variable-group have their own update subcommands with different rules. See Environments, Services, and Variable groups.
The CLI recognizes a few more kinds, such as blueprint, preview, promotion-pipeline, and access-policy, but the server rejects them:
unknown resource kind and a list of the names it does know. For a kind that update doesn’t accept, save the resource with get -o yaml, edit it, and use replace -f.
Preview a patch
--dry-run merges and validates the patch on the server, prints the merged document, and writes nothing:
--dry-run exists only on ryvn update <kind> <name>. The update environment, update service, and update variable-group subcommands don’t take it.
What update returns
Without--dry-run, update prints one line per changed resource, with the action created, updated, or unchanged, and exits. If the patch fails validation, nothing is written, each error prints as Error: <kind> <name>: <message>, and the exit code is 1. Add -o json for the full result.
update doesn’t print a task ID and doesn’t accept --reason, --no-watch, --timeout, or --poll-interval. When the change triggers a deployment, find it with ryvn get installation-task my-app -e production.
How patches merge
A patch is a strategic merge patch. Objects merge field by field. Lists behave in one of two ways, depending on the field. Merged by key. The patch lists only the items you touch. Items you don’t list stay as they are, and an item that already exists is updated in place.
Replaced wholesale. The patch value becomes the whole field. Send the complete list or string, because anything you leave out is dropped.
Two directives change the defaults:
-
Add
$patch: deleteto a keyed list item to remove it: -
Set a field to
nullto clear it. If that leaves the resource invalid, the patch is rejected and nothing is written.
patch cannot be merged into the ServiceInstallation document: ... does not contain declared merge key: key.
Unknown and protected fields
The server rejects a patch that names a field the kind doesn’t have, so a typo fails instead of being dropped. The error lists every bad path, so you can fix them all in one edit:spec:
Other fields aren’t patchable because the kind doesn’t have them. A blueprint installation has no
spec.blueprintVersion or spec.autoUpgradeEnabled. Change its version with ryvn set blueprint-version, and turn automatic upgrades off with spec.disableAutoUpgrade: true.
Installations
ryvn update installation my-app -e production accepts the fields in the installation’s YAML, and the merge rules above apply.
Environment variables
spec.env merges by key. Add or change a variable by listing it, and remove one with $patch: delete.
Config
spec.config is a string, and a patch replaces it wholesale. The patch value becomes the entire config. A patch that doesn’t mention spec.config leaves the stored config untouched, including any {{ ... }} template expressions in it.
To change one value, read the resource, edit the config in the file, and send the whole resource back:
config: [{path: ./values.yaml}], is rejected, because the server can’t read files on your machine:
ryvn create -f, ryvn replace -f, and ryvn plan -f read the local files that config references and include them for you, so the array form works there. See Helm chart installation config.
Secrets
spec.secrets merges by name, and each secret’s values merge by key. A secret has a name and either generated or values. Remove a secret with $patch: delete:
value field on a secret is rejected as unknown (unknown fields: spec.secrets[0].value). To give an installation a secret value, store it as a sensitive variable in a variable group. Server, job, and Pulumi installations attach the group with spec.variableGroups. Helm chart and Terraform installations can read every variable group in their environment already, and reject spec.variableGroups.
Ports and domains
spec.networking.ports merges by port number, but each port’s domains list is replaced. To change the domains on port 8080, list all of them:
Rollout mode
--rollout-mode synchronous|asynchronous|inherit sets how future deployment tasks wait for rollout readiness. inherit clears the installation’s override and falls back to the service’s setting. Running tasks keep their current mode. Use synchronous if your chart has post-install or post-upgrade hooks that need ready workloads. In asynchronous mode, those hooks run before rollout readiness.
-e is required. --rollout-mode can’t be combined with -p, --patch-file, or --dry-run, and the setting isn’t part of the YAML, so git sync doesn’t manage it.
Blueprint installations
spec.inputs merges by name. Inputs you don’t list keep their values, and $patch: delete drops one:
ryvn set blueprint-input and ryvn unset blueprint-input are shorthand for the same input changes.
Maintenance windows and release channels
spec.intervals is replaced wholesale, so send the full list when you change it:
Promotion pipelines
update doesn’t accept promotion-pipeline. A pipeline’s spec.paths is also a single value that any change replaces in full, so work from the whole document: read it, edit the full spec.paths, check it with ryvn plan, and replace it.
Environments
ryvn update environment <name> is a separate command with its own rules. It takes a patch with -p or --patch-file. It has no -e and no --dry-run.
platform.inputs uses the API input shape, not the shape of the exported resource YAML. To remove a platform input, use ryvn unset blueprint-input <platform-installation> -e <environment> --name <name>.
Fields that the command doesn’t recognize are ignored when the patch also has a recognized field. A patch with no recognized field fails with no recognized fields in patch — nothing was updated. Unknown keys under spec.platform are rejected, because only inputs is patchable. To change other environment fields, such as maintenanceWindow or namespaces, use ryvn replace -f on the whole environment document.
The command applies its steps in order: labels and the other direct fields, then config, then platform inputs. If a later step fails, the earlier ones stay applied. Check the result with ryvn get environment <name> -o yaml.
Services
ryvn update service <name> changes a service’s labels and two settings that live outside its YAML. It can’t change any other service field.
metadata.labelsreplaces all existing labels. An empty object clears them.--rollout-mode synchronous|asynchronoussets the service-level default, and an installation’s own setting overrides it. It applies to future tasks only.--helm-timeout <duration>sets the Helm timeout for a Helm chart service, for example6h30m. It must be at least one second, and a service of another type is rejected. Tasks that are already running keep their timeout.
no recognized fields in patch — nothing was updated.
Variable groups
ryvn update variable-group <name> -e <environment> uses its own patch shape, not the resource YAML. A group belongs to one environment, so pass -e.
-p so they don’t land in your shell history. See Variable groups for revisions and how groups attach to installations.
Rename a resource
A resource’s name is its identity, so a patch can’t change it. The same goes forspec.service, spec.environment, and spec.blueprint on an installation.
To rename a Terraform installation without destroying its infrastructure, create a new installation whose spec.renamedFrom names the old one. Don’t delete the old installation first. Deleting runs the destroy task and removes the infrastructure.
Start from the old installation’s full document. After seeding, Ryvn applies your file to the new installation, so config, secrets, or variable groups that the file leaves out are removed.
metadata.name to the new name and add renamedFrom:
renamedFrom is a one-time directive that applies only when the new installation is created, and only for Terraform services. The command fails if the old installation isn’t found (renamedFrom source installation "my-old-name" not found in environment production), has been deleted, has already been renamed, or has tasks in progress. Wait for those tasks to finish and try again. In a git-synced repo, remove the old installation’s file in the same commit.
You can also rename a standalone Terraform installation from Actions > Rename installation in the dashboard.
For any other installation type, or to point an installation at a different service or environment, create the installation you want and delete the old one. Deleting removes the running workload, so plan for the interruption. See Delete installations and environments.
Replace a resource
ryvn replace -f <file> replaces an existing resource from a complete YAML or JSON file. The kind field in the file picks the resource type, and -f - reads stdin. The resource must already exist, or nothing changes. Use ryvn create for a new one.
The file replaces the resource in full. Anything it omits is treated as no longer wanted. That can remove current values or restore inherited or default behavior, for example installation config, env vars, secrets, variable groups, autoscaling, networking, lifecycle, or channel settings.
So start from the saved resource, edit it, check it, then replace:
ServiceInstallation, metadata.name, spec.service, and spec.environment are required, and the namespace can’t change after creation. To change a few settings, use update, ryvn set, or ryvn unset instead.
replace also takes -o json. It accepts the array form of spec.config and reads the referenced files from disk, relative to the file that declares them.
Validate before applying
Four checks answer different questions.
A typical loop for a file change is
lint, then plan, then replace. For a small change, update --dry-run then update.
ryvn lint
ryvn lint validates resource files against the schema without applying anything. With no flags it lints every Ryvn resource file under the current directory. Use -f <file-or-directory> to narrow it, or -f - for stdin.
ryvn plan
ryvn plan -f <file> shows what applying a file would do, without writing anything. It reports the fields that differ, the externals an apply would invoke, anything that blocks the apply, and a rollup. For a blueprint, it also shows what happens to every service installation under each blueprint installation.
--installation limits a blueprint plan to one blueprint installation. --verbose shows the full config body instead of only the changed hunks.
Environment and installation plans compare the declared spec, not resolved runtime state. Each such plan says so in its notices, and resolved config, env, and secret values aren’t compared. A kind that has no planner fails with plan is not yet supported for kind: <kind>.
For a CI gate, add --detailed-exitcode:
ryvn command dry-run
ryvn command dry-run previews a deployment of an installation as it is stored now, optionally at another version: a Helm diff or a Terraform plan, without applying it. Use it after an update to see what the next deployment will do.
--disable-approvals creates a preview that can’t be applied. See Tasks and approvals.
Resources managed by git sync
If git sync manages a resource, a change from the CLI counts as drift. With drift protection on, the next import skips the resource and reports it as drifted. Your change stays in place, but git no longer controls the resource until you resolve the drift. That applies toupdate and replace alike.
To keep the change, export it back to git. To discard it and let git overwrite the resource, resolve the drift:
ryvn update changes outside the resource YAML, such as --rollout-mode, aren’t part of what git sync manages. See Git sync selectors for the selector forms.
Related pages
- Tasks and approvals: follow, approve, and debug the tasks that a change starts.
- Drift protection: how git sync treats resources that you change outside git.
- Variable groups: create groups and attach them to installations.
- Infrastructure as code: manage the same resources as YAML in git.