Introduction The system.yaml file encompasses a multitude of configuration capabilities for JFrog products. These configurations are organized under different sections in the YAML file.
Under the $JFROG_HOME/<JFrog_Product>/var/etc folder, we can find a few different system yaml files:
- System.yaml: This file holds the customized configuration of the product.
- System.basic-template.yaml: It contains commonly used system configurations and mirrors system.yaml after a fresh installation.
- system.full-template.yaml: This includes a comprehensive list of all available configurations.
Every entry in the system.yaml file should correspond to an entry in the system.full-template.yaml file and to the online references:
- Artifactory Yaml Template - https://jfrog.com/help/r/jfrog-installation-setup-documentation/artifactory-system-yaml-configuration-topics
- Xray Yaml Template - https://jfrog.com/help/r/jfrog-installation-setup-documentation/xray-system-yaml
- Distribution Yaml Template - https://jfrog.com/help/r/jfrog-installation-setup-documentation/supported-configurations-in-distribution-system-yaml
- Insight Yaml Template - https://jfrog.com/help/r/jfrog-installation-setup-documentation/supported-configurations-in-insight-system-yaml
- Pipeline Yaml Template - https://jfrog.com/help/r/jfrog-installation-setup-documentation/supported-configurations-in-pipelines-system-yaml
The Error
In case there is no match between a key entered in the system.yaml and the system.full-template.yaml, we will see the following errors:
.artifactory.Your.Key key is misplaced or doesn't apply at this location yaml validation failed 2024-03-17T09:52:50.220Z [shell] [WARN ] [] [installerCommon.sh:817 ] [main] - System.yaml validation failed
This output is printed during startup.
Resolution This error is because we have a mismatch between what is in your system.yaml and the acceptable options specified in the system.full-template.yaml.
To resolve the error we need to make sure the keys we use in the system.yaml are correctly spaced and spelt, and appear in the correct hierarchy. Yaml files are space sensitive.
You can also manually run the following commands to see this output and validate your system.yaml:
$JFROG_HOME/<JFrog_Product>/app/bin/diagnostics/diagnosticsUtil validate yaml$JFROG_HOME/<JFrog_Product>/var/etc/system.yaml $JFROG_HOME/<JFrog_Product>/var/etc/system.full-template.yaml --uncomment-before-parse
E.g for Artifactory the command will be:
$JFROG_HOME/artifactory/app/bin/diagnostics/diagnosticsUtil validate yaml $JFROG_HOME/artifactory/var/etc/system.yaml $JFROG_HOME/artifactory/var/etc/system.full-template.yaml --uncomment-before-parse
In case that the system.yaml configuration is valid, we will get the following output from the command:
yaml validation succeeded
Please also note: This validation is just an extra check and even invalid entries while failing this check do not prevent the JFrog Product from starting. But it can be a good way of knowing that you have misplaced a key in the yaml file.