Skip to content

json_value

One value in a JSON file, which should or should not be there. The rest of the file stays as it was, byte for byte.

Use json_value to own one value in a JSON config file and leave the rest of it alone: an app’s port, a log level, a feature flag. Many Node.js and Java apps keep their settings this way. Every byte the step doesn’t own stays as it was, indentation and key order included, so a diff of the file shows only your change.

Set the port:

step "port" {
json_value {
path = "/etc/myapp/config.json"
key = "server.port"
value = jsonencode(9090)
}
}

Add a setting, making the objects on the way:

step "log_level" {
json_value {
path = "/etc/myapp/config.json"
key = "logging.level"
value = jsonencode("warn")
}
}

Change one element of a list:

step "first_upstream" {
json_value {
path = "/etc/myapp/config.json"
key = "upstreams[0].host"
value = jsonencode("10.0.0.5")
}
}

Take a key out:

step "no_debug" {
json_value {
path = "/etc/myapp/config.json"
key = "debug"
state = "absent"
}
}
Name Type Required Description
create bool No Create the file when it is missing. Otherwise a missing file is an error.
key string Yes Where the value is: object keys joined by dots, with [n] for an array element, such as server.port or upstreams[0].host. Missing objects on the way are made.
on_remove string No “forget” (default) leaves the file as it is, “delete” takes the edit back out.
path string Yes Absolute path of the file.
state string No “present” (default) or “absent”, which takes the key out.
value string No The value, as JSON: write it with jsonencode, such as jsonencode(8080), jsonencode(“info”) or jsonencode({ enabled = true }). Required unless state is “absent”. A value that’s equal already, however it’s written, is left alone.

Conn3x sets these; reference them as conn3x_json_value.<circuit>__<step>["<host>"].<name>.

Name Type Description
in_sync bool Whether the file already matches.
revision string Changes each time Conn3x changes this on the host. Handlers watch it.

A step lowers to the conn3x_json_value resource, one instance per host, and connects with its circuit’s ssh block.

The key. Object keys joined by dots, with [n] after one for an array element, counted from 0. A key with a dot or a bracket in its name can’t be named.

The value. It’s JSON text, so jsonencode keeps its type: jsonencode(9090) is a number, jsonencode("9090") a string, and jsonencode({ enabled = true }) an object. Conn3x compares values, not text, so 8080 and 8080.0 are equal, and an object’s keys can be in any order. An equal value is left as it’s written. A different one is replaced where it is, written compactly.

Adding. A missing key goes after the object’s last member, on its own line and indented as that member is when the object spans lines, or on the same line when it doesn’t. Objects missing on the way are made. Arrays aren’t: an index past the end of an array is an error, and so is an index into something that isn’t there. An empty file starts as {}, and so does a missing one with create = true; without it, a missing file is an error.

Taking out. state = "absent" removes the key with its comma and line, and does nothing when the key isn’t there. The object it was in stays, even when that leaves it empty. Array elements can’t be taken out.

The file. It’s read and written as line reads and writes, with the file’s owner and mode kept, and it must be valid JSON before Conn3x touches it. Comments, as in JSONC, make it invalid. Every plan reads the file again, so a value changed by hand shows the step out of sync, and the next apply puts it back.

Deleting a json_value step leaves the value. With on_remove = "delete", it takes the key out.