phenix config¶
Every command on this page also accepts the global flags.
phenix config¶
Configuration file management
Synopsis¶
Configuration file management
This subcommand is used to manage the different kinds of phenix configuration
files: topology, scenario, experiment, or image.
Options¶
SEE ALSO¶
- phenix - A cli application for phēnix
- phenix config apply - Create or update configurations from files
- phenix config create - Create a configuration(s)
- phenix config delete - Delete a configuration(s)
- phenix config diff - Show how configuration files differ from the stored configurations
- phenix config edit - Edit a configuration
- phenix config get - Get a configuration
- phenix config list - Show table of stored configuration files
phenix config apply¶
Create or update configurations from files
Synopsis¶
Create or update configurations from files
This subcommand creates each configuration in the given JSON or YAML files
that is not stored, updates each stored configuration that is different,
and does not change a configuration that is the same. Give the files as
arguments, with -f, or both. Each one is the path of a file with the
extension .json, .yaml or .yml. A directory is an error. To read the files
of a directory, let the shell give them: "phenix config apply DIR/*".
The command applies Topology configurations first, then Scenario, then
Experiment, then Image and Role configurations, because a scenario and an
experiment refer to a topology. It does not apply User configurations,
because their files do not hold the password hash and the tokens.
A comparison looks at the apiVersion, kind, name, annotations and spec. It
ignores the fields that phenix sets: created, updated, revision, status and
the experiment name. "phenix config diff" shows the differences. phenix
adds values to an experiment configuration when it stores it. Thus, apply
an experiment file that "phenix config get" wrote, or the file is always
different.
An update goes through the same checks as config edit. phenix refuses to
update the configuration of a running experiment, and refuses an update
when the configuration changes while the command runs. The command prints
one line for each configuration. It tries all configurations, and then
exits with an error if one or more failed.
With --dry-run, the command checks each configuration as for an apply,
shows the configurations that it would create or update, and changes
nothing.
The command fills in the ${NAME} and ${NAME:default} placeholders of each
file before it reads the file. A value comes from -e, else from an env
file of --env-file, else from the shell. The shell gives no PHENIX_
variable unless -e NAME names it. A placeholder with no value and no
default is an error, and so is a -e variable that no file uses: the
command then changes nothing. Write ${NAME:} for an optional variable and
$${NAME} for the literal text ${NAME}.
Examples¶
phenix config apply topology.yml scenario.yml
phenix config apply -f topology.yml -f scenario.yml
phenix config apply ./configs/* --dry-run
phenix config apply topology.yml -e NODES=3 --env-file site.env
Options¶
--dry-run Show what the command would change, and change nothing
-e, --env stringArray set a variable for the ${NAME} placeholders: NAME=value, or NAME to copy the value from the shell (repeatable)
--env-file stringArray read variables from an env file of NAME=value lines; a relative path starts at the working directory (repeatable)
-f, --filename stringArray Configuration file to apply (repeatable); the same as an argument
-h, --help help for apply
--skip-validation Skip schema validation of new configurations (updates are always validated)
SEE ALSO¶
- phenix config - Configuration file management
phenix config create¶
Create a configuration(s)
Synopsis¶
Create a configuration(s)
This subcommand is used to create one or more configurations from JSON or
YAML file(s). Each argument is the path of a file with the extension
.json, .yaml or .yml. A directory is an error. To read the files of a
directory, let the shell give them: "phenix config create DIR/*".
A Builder document (the Builder's JSON or YAML export), a Builder
template file, a Builder package and a Builder layer set file are not
configurations. The command refuses such a file. Use the Builder in the web
UI, or the Builder REST API below /api/v1/builder/, for these files. Upload
a document and publish it to create its topology. Use Import templates to
add the templates of a template file. Use Upload to open a package. Use
Upload layer set on the Layers tab to add a layer set file.
The command fills in the ${NAME} and ${NAME:default} placeholders of each
file before it reads the file. A value comes from -e, else from an env
file of --env-file, else from the shell. The shell gives no PHENIX_
variable unless -e NAME names it. A placeholder with no value and no
default is an error, and so is a -e variable that no file uses: the
command then changes nothing. Write ${NAME:} for an optional variable and
$${NAME} for the literal text ${NAME}.
The command reads every file and checks every variable before it stores a
configuration.
Examples¶
phenix config create topology.yml scenario.yml
phenix config create ./configs/*.yml
phenix config create topology.yml -e NODES=3 --env-file site.env
Options¶
-e, --env stringArray set a variable for the ${NAME} placeholders: NAME=value, or NAME to copy the value from the shell (repeatable)
--env-file stringArray read variables from an env file of NAME=value lines; a relative path starts at the working directory (repeatable)
-h, --help help for create
--skip-validation Skip configuration spec validation against schema
SEE ALSO¶
- phenix config - Configuration file management
phenix config delete¶
Delete a configuration(s)
Synopsis¶
Delete a configuration(s)
This subcommand is used to delete one or more configurations. With
--dry-run, it shows the configurations that it would delete, and deletes
nothing.
A name can contain the wildcard *, which matches zero or more characters.
For example, topology/cm-* selects each topology whose name starts with
"cm-". Put quotation marks around a pattern, so that your shell does not
expand it. The kind cannot contain *. The pattern <kind>/* does the same
as "delete all <kind>", and */* does the same as "delete all". Another
pattern that selects no configuration is an error. Before phenix deletes
the configurations that a pattern selects, it shows their names. A pattern
does not delete the configuration of a running experiment.
When phenix cannot delete a configuration, it continues with the other
ones. Then it exits with an error that names each failure.
Examples¶
phenix config delete topology/foo
phenix config delete topology/foo scenario/bar
phenix config delete 'topology/cm-*'
phenix config delete 'topology/cm-*' --dry-run
Options¶
SEE ALSO¶
- phenix config - Configuration file management
- phenix config delete all - Delete all configurations (optionally by kind)
phenix config delete all¶
Delete all configurations (optionally by kind)
Synopsis¶
Delete all configurations
This subcommand is used to delete all configurations, or all configurations
of a specific kind. It does not delete the configuration of a running
experiment. With --dry-run, it shows the configurations that it would
delete, and deletes nothing.
Examples¶
phenix config delete all
phenix config delete all topology
phenix config delete all scenario
phenix config delete all topology --dry-run
Options¶
SEE ALSO¶
- phenix config delete - Delete a configuration(s)
phenix config diff¶
Show how configuration files differ from the stored configurations
Synopsis¶
Show how configuration files differ from the stored configurations
This subcommand prints a unified diff from each stored configuration to the
configuration of the same kind and name in the given JSON or YAML files. It
prints "new" for a configuration that is not stored. It prints nothing for a
configuration that is the same. Each argument is the path of a file with
the extension .json, .yaml or .yml. A directory is an error. To read the
files of a directory, let the shell give them: "phenix config diff DIR/*".
The diff shows the apiVersion, kind, name, annotations and spec, as YAML
with sorted keys. It ignores the fields that phenix sets: created, updated,
revision, status and the experiment name. A configuration that config diff
shows as the same is one that config apply does not change.
The command exits with 0 when no configuration differs, 1 when one or more
differ, and 2 when it cannot read or compare a configuration.
The command fills in the ${NAME} and ${NAME:default} placeholders of each
file before it reads the file. A value comes from -e, else from an env
file of --env-file, else from the shell. The shell gives no PHENIX_
variable unless -e NAME names it. A placeholder with no value and no
default is an error, and so is a -e variable that no file uses: the
command then changes nothing. Write ${NAME:} for an optional variable and
$${NAME} for the literal text ${NAME}.
Examples¶
phenix config diff topology.yml
phenix config diff ./configs/*
phenix config diff topology.yml -e NODES=3 --env-file site.env
Options¶
-e, --env stringArray set a variable for the ${NAME} placeholders: NAME=value, or NAME to copy the value from the shell (repeatable)
--env-file stringArray read variables from an env file of NAME=value lines; a relative path starts at the working directory (repeatable)
-h, --help help for diff
SEE ALSO¶
- phenix config - Configuration file management
phenix config edit¶
Edit a configuration
Synopsis¶
Options¶
SEE ALSO¶
- phenix config - Configuration file management
phenix config get¶
Get a configuration
Synopsis¶
Get a configuration
This subcommand is used to get a specific configuration file by kind/name.
Valid options for kinds of configuration files are the same as described
for the parent config command.
Examples¶
phenix config get topology/foo
phenix config get scenario/bar
phenix config get experiment/foobar
phenix config get topology/foo -o json
Options¶
-h, --help help for get
-o, --output string Output format (yaml, json) (default "yaml")
-p, --pretty Pretty print the JSON output (JSON output is always indented)
SEE ALSO¶
- phenix config - Configuration file management
phenix config list¶
Show table of stored configuration files
Synopsis¶
Show table of stored configuration files
The JSON and YAML output give the apiVersion, kind and metadata of each
configuration, as GET /api/v1/configs does, without the spec.
Examples¶
phenix config list all
phenix config list topology
phenix config list scenario
phenix config list experiment
phenix config list image
phenix config list user
phenix config list topology -o json
Options¶
SEE ALSO¶
- phenix config - Configuration file management