From fc81e22cd7dfab7ad1739544bfaa91f0bfba468c Mon Sep 17 00:00:00 2001 From: Kent Quirk Date: Sat, 24 Jun 2023 16:13:25 -0400 Subject: [PATCH] Fix convert help and docs --- tools/convert/README.md | 46 +++++++++++++++++++++++++++++++---------- tools/convert/main.go | 16 +++++++------- 2 files changed, 43 insertions(+), 19 deletions(-) diff --git a/tools/convert/README.md b/tools/convert/README.md index 090b656913..827b81e7ad 100644 --- a/tools/convert/README.md +++ b/tools/convert/README.md @@ -12,20 +12,43 @@ It also allows all of the comments in the configuration to be rewritten for clar ``` Usage: - convert [OPTIONS] + convert [OPTIONS] COMMAND - This tool converts a Refinery v1 config file (usually in TOML, but JSON and YAML are also - supported) to a Refinery v2 config file in YAML. It reads the v1 config file, and then writes - the v2 config file, copying non-default values from their v1 location to their v2 location - (if they still apply). The new v2 config file is commented in detail to help explain what - each value does in the new configuration. + The main usage of this tool is to converts a Refinery v1 config file (usually in TOML, but + JSON and YAML are also supported) to a Refinery v2 config file in YAML. It reads the v1 + config file, and then writes the v2 config file, copying non-default values from their v1 + location to their v2 location (if they still apply). - For example, if the v1 file specified "MetricsAPIKey" in the "HoneycombMetrics" section, the v2 - file will list that key under the "LegacyMetrics" section under the "APIKey" name. + For config files, the new v2 config file is commented in detail to help explain what each + value does in the new configuration. - By default, it reads config.toml and writes to stdout. It will try to determine the - filetype of the input file based on the extension, but you can override that with - the --type flag. + For example, if the v1 file specified "MetricsAPIKey" in the "HoneycombMetrics" section, the v2 + file will list that key under the "LegacyMetrics" section under the "APIKey" name. + + The tool can also convert rules files to the new rules file format. + + By default, it reads config.toml and writes to stdout. It will try to determine the + filetype of the input file based on the extension, but you can override that with + the --type flag. + + Because many organizations use helm charts to manage their refinery deployments, there + is a subcommand that can read a helm chart, extract both the rules and config from it, + and write them back out to a helm chart, while preserving the non-refinery portions. + + It has other commands to help with the conversion process. Valid commands are: + convert config: convert a config file + convert rules: convert a rules file + convert helm: convert a helm values file + convert validate config: validate a config file against the 2.0 format + convert validate rules: validate a rules file against the 2.0 format + convert doc config: generate markdown documentation for the config file + convert doc rules: generate markdown documentation for the rules file + + Examples: + convert config --input config.toml --output config.yaml + convert rules --input refinery_rules.yaml --output v2rules.yaml + convert validate config --input config.yaml + convert validate rules --input v2rules.yaml Application Options: @@ -35,4 +58,5 @@ Application Options: Help Options: -h, --help Show this help message + ``` diff --git a/tools/convert/main.go b/tools/convert/main.go index 2957bcface..750d698e78 100644 --- a/tools/convert/main.go +++ b/tools/convert/main.go @@ -98,16 +98,16 @@ func main() { and write them back out to a helm chart, while preserving the non-refinery portions. It has other commands to help with the conversion process. Valid commands are: - convert config: convert a config file - convert rules: convert a rules file - convert helm: convert a helm values file - convert validate config: validate a config file against the 2.0 format - convert validate rules: validate a rules file against the 2.0 format - convert doc config: generate markdown documentation for the config file - convert doc rules: generate markdown documentation for the rules file + convert config: convert a config file + convert rules: convert a rules file + convert helm: convert a helm values file + convert validate config: validate a config file against the 2.0 format + convert validate rules: validate a rules file against the 2.0 format + convert doc config: generate markdown documentation for the config file + convert doc rules: generate markdown documentation for the rules file Examples: - convert config --input config.toml --output config.yaml + convert config --input config.toml --output config.yaml convert rules --input refinery_rules.yaml --output v2rules.yaml convert validate config --input config.yaml convert validate rules --input v2rules.yaml