Skip to content

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.
phenix config [flags]

Options

  -h, --help   help for config

SEE ALSO

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}.
phenix config apply <file>... [-f <file>]... [flags]

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 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.
phenix config create </path/to/filename> ... [flags]

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 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.
phenix config delete <kind/name> ... [flags]

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

      --dry-run   Show what the command would change, and change nothing
  -h, --help      help for delete

SEE ALSO

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.
phenix config delete all [kind] [flags]

Examples

phenix config delete all
phenix config delete all topology
phenix config delete all scenario
phenix config delete all topology --dry-run

Options

      --dry-run   Show what the command would change, and change nothing
  -h, --help      help for all

SEE ALSO

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}.
phenix config diff <file>... [flags]

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 edit

Edit a configuration

Synopsis

Edit a configuration

  This subcommand is used to edit a configuration using your default editor.
phenix config edit <kind/name> [flags]

Options

      --force   override checks (only applies to configs for running experiments)
  -h, --help    help for edit

SEE ALSO

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.
phenix config get <kind/name> [flags]

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 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.
phenix config list <kind> [flags]

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

  -h, --help            help for list
  -o, --output string   Output format (table, json, yaml) (default "table")

SEE ALSO