Env Variable Operators
These operators are used to handle environment variables usage in expressions and documents. While environment variables can, of course, be passed in via your CLI with string interpolation, this often comes with complex quote escaping and can be tricky to write and read.
There are three operators:
envwhich takes a single environment variable name and parse the variable as a yaml node (be it a map, array, string, number of boolean)strenvwhich also takes a single environment variable name, and always parses the variable as a string.envsubstwhich you pipe strings into and it interpolates environment variables in strings using envsubst.
You can optionally pass envsubst any of the following options:
- nu: NoUnset, this will fail if there are any referenced variables that are not set
- ne: NoEmpty, this will fail if there are any referenced variables that are empty
- ff: FailFast, this will abort on the first failure (rather than collect all the errors)
E.g:
envsubst(ne, ff) will fail on the first empty variable.See Imposing Restrictions in the
envsubst documentation for more information, and below for examples.To replace environment variables across all values in a document,
envsubst can be used with the recursive descent operator as follows:yq '(.. | select(tag == "!!str")) |= envsubst' file.yaml
Running
myenv="cat meow" yq --null-input '.a = env(myenv)'
will output
a: cat meow
Running
myenv="true" yq --null-input '.a = env(myenv)'
will output
a: true
Running
myenv="12" yq --null-input '.a = env(myenv)'
will output
a: 12
Running
myenv="{b: fish}" yq --null-input '.a = env(myenv)'
will output
a: {b: fish}
Running
myenv="true" yq --null-input '.a = strenv(myenv)'
will output
a: "true"
Running
myenv="12" yq --null-input '.a = strenv(myenv)'
will output
a: "12"
The env variable can be any valid yq expression.
Given a sample.yml file of:
a:
b:
- name: dog
- name: cat
then
pathEnv=".a.b[0].name" valueEnv="moo" yq 'eval(strenv(pathEnv)) = strenv(valueEnv)' sample.yml
will output
a:
b:
- name: moo
- name: cat
Given a sample.yml file of:
cat: meow
dog: woof
then
myenv="cat" yq '.[env(myenv)]' sample.yml
will output
meow
Running
myenv="cat" yq --null-input '"the ${myenv} meows" | envsubst'
will output
the cat meows
Running
yq --null-input '"the ${myenvnonexisting} meows" | envsubst'
will output
the meows
(nu) not unset, will fail if there are unset (missing) variables
Running
yq --null-input '"the ${myenvnonexisting} meows" | envsubst(nu)'
will output
Error: variable ${myenvnonexisting} not set
(ne) not empty, only validates set variables
Running
yq --null-input '"the ${myenvnonexisting} meows" | envsubst(ne)'
will output
the meows
(ne) not empty, will fail if a references variable is empty
Running
myenv="" yq --null-input '"the ${myenv} meows" | envsubst(ne)'
will output
Error: variable ${myenv} set but empty
Running
yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst'
will output
the dog meows
Having a default specified skips over the missing variable.
Running
yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst(nu)'
will output
the dog meows
Fails, because the variable is explicitly set to blank.
Running
myEmptyEnv="" yq --null-input '"the ${myEmptyEnv-dog} meows" | envsubst(ne)'
will output
Error: variable ${myEmptyEnv} set but empty
Given a sample.yml file of:
v: ${myenv}
then
myenv="cat meow" yq '.v |= envsubst' sample.yml
will output
v: cat meow
By default, all errors are returned at once.
Running
yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu)'
will output
Error: variable ${notThere} not set
variable ${alsoNotThere} not set
Running
yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu,ff)'
will output
Error: variable ${notThere} not set
Last modified 4mo ago