From 2a6fa1812d666e13e58b1a33889885fb86f0611c Mon Sep 17 00:00:00 2001 From: Megan Wolf Date: Fri, 20 Sep 2024 08:35:49 -0400 Subject: [PATCH] docs: updated config/template docs --- docs/getting-started/README.md | 6 +- docs/getting-started/configuration.md | 139 ++++++++++++++++++++++++++ docs/reference/configuration.md | 82 --------------- 3 files changed, 144 insertions(+), 83 deletions(-) create mode 100644 docs/getting-started/configuration.md delete mode 100644 docs/reference/configuration.md diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 009bb49a..c4658cc5 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -63,4 +63,8 @@ See the following tutorials for some introductory lessons on how to use Lula. If Lula Validation manifests are the underlying mechanisms that dictates the evaluation of a system against a control as resulting in `satisfied` or `not satisfied`. A Lula Validation is linked to a control within a component definition via the OSCAL-specific property, [links](../oscal/oscal-validation-links.md). -Developing Lula Validations can sometimes be more art than science, but generally they should aim to be clear, concise, and robust to system changes. See our guide for [developing Lula Validations](./develop-a-validation.md) and the [references](../reference/README.md) for additional information. \ No newline at end of file +Developing Lula Validations can sometimes be more art than science, but generally they should aim to be clear, concise, and robust to system changes. See our guide for [developing Lula Validations](./develop-a-validation.md) and the [references](../reference/README.md) for additional information. + +### Configuration + +Lula supports the addition of a configuration file for specifying CLI flags and templating values. See our [configuration](./configuration.md) guide for more information. \ No newline at end of file diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md new file mode 100644 index 00000000..3df15a2d --- /dev/null +++ b/docs/getting-started/configuration.md @@ -0,0 +1,139 @@ +# Configuration + +Lula allows the use and specification of a config file in the following ways: +- Checking current working directory for a `lula-config.yaml` file +- Specification with environment variable `LULA_CONFIG=` + +Environment Variables can be used to specify configuration values through use of `LULA_` -> Example: `LULA_TARGET=il5` + +## Identification + +If identified, Lula will log which configuration file is used to stdout: +```bash +Using config file /home/dev/work/lula/lula-config.yaml +``` + +## Precedence + +The precedence for configuring settings, such as `target`, follows this hierarchy: + +### **Command Line Flag > Environment Variable > Configuration File** + +1. **Command Line Flag:** + When a setting like `target` is specified using a command line flag, this value takes the highest precedence, overriding any environment variable or configuration file settings. + +2. **Environment Variable:** + If the setting is not provided via a command line flag, an environment variable (e.g., `export LULA_TARGET=il5`) will take precedence over the configuration file. + +3. **Configuration File:** + In the absence of both a command line flag and environment variable, the value specified in the configuration file will be used. This will override system defaults. + +## Support + +Modification of command variables can be set in the configuration file: + +lula-config.yaml +```yaml +log_level: debug +target: il4 +summary: true +``` + +### Templating Configuration Fields + +Templating values are set in the configuration file via the use of `constants` and `variables` fields. + +#### Constants + +A sample `constants` section of a `lula-config.yaml` file is as follows: + +```yaml +constants: + type: software + title: lula + + resources: + name: test-pod-label + namespace: validation-test + imagelist: + - nginx + - nginx2 +``` + +Constants will respect the structure of a map[string]interface{} and can be referenced as follows: + +```yaml +# validaiton.yaml +metadata: + name: sample {{ .const.type }} validation for {{ .const.title }} +domain: + type: kubernetes + kubernetes-spec: + resources: + - name: myPod + resource-rule: + name: {{ .const.resources.name }} + version: v1 + resource: pods + namespaces: [{{ .const.resources.namespace }}] +provider: + type: opa + opa-spec: + rego: | + package validate + import rego.v1 + + validate if { + input.myPod.metadata.name == {{ .const.resources.name }} + input.myPod.containers[_].name in { {{ .const.resources.imagelist | concatToRegoList }} } + } +``` + +And will be rendered as: +```yaml +metadata: + name: sample software validation for lula +domain: + type: kubernetes + kubernetes-spec: + resources: + - name: myPod + resource-rule: + name: myPod + version: v1 + resource: pods + namespaces: [validation-test] +provider: + type: opa + opa-spec: + rego: | + package validate + import rego.v1 + + validate if { + input.myPod.metadata.name == "myPod" + input.myPod.containers[_].image in { "nginx", "nginx2" } + } +``` + +The constant's keys should be in the format `.const.` and should not contain any '-' or '.' characters, as this will not respect the go text/template format. + +#### Variables + +A sample `variables` section of a `lula-config.yaml` file is as follows: + +```yaml +variables: + - key: some_lula_secret + sensitive: true + - key: some_env_var + default: this-should-be-overridden +``` + +The `variables` section is a list of `key`, `default`, and `sensitive` fields, where `sensitive` and `default` are optional. The `key` and `default` fields are strings, and the `sensitive` field is a boolean. + +A default value can be specified in the case where an environment variable may or may not be set, however an environment variable will always take precedence over a default value. + +The environment variable should follow the pattern of `LULA_VAR_` (not case sensitive), where `` is the key specified in the `variables` section. + +When using `sensitive` variables, the default behavior is to mask the value in the output of the template. \ No newline at end of file diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md deleted file mode 100644 index ea9fdbdf..00000000 --- a/docs/reference/configuration.md +++ /dev/null @@ -1,82 +0,0 @@ -# Configuration - -Lula allows the use and specification of a config file in the following ways: -- Checking current working directory for a `lula-config.yaml` file -- Specification with environment variable `LULA_CONFIG=` - -Environment Variables can be used to specify configuration values through use of `LULA_` -> Example: `LULA_TARGET=il5` - -## Identification - -If identified, Lula will log which configuration file is used to stdout: -```bash -Using config file /home/dev/work/lula/lula-config.yaml -``` - -## Precedence - -The precedence for configuring settings, such as `target`, follows this hierarchy: - -### **Command Line Flag > Environment Variable > Configuration File** - -1. **Command Line Flag:** - When a setting like `target` is specified using a command line flag, this value takes the highest precedence, overriding any environment variable or configuration file settings. - -2. **Environment Variable:** - If the setting is not provided via a command line flag, an environment variable (e.g., `export LULA_TARGET=il5`) will take precedence over the configuration file. - -3. **Configuration File:** - In the absence of both a command line flag and environment variable, the value specified in the configuration file will be used. This will override system defaults. - -## Support - -Modification of command variables can be set in the configuration file: - -lula-config.yaml -```yaml -log_level: debug -target: il4 -summary: true -``` - -### Templating Configuration Fields - -TODO - description of templating configuration fields - -```yaml -# constants = place to define non-changing values that can be of any type -# I think stuff here probably shouldn't be set by env vars - it's hard to be deterministic because of the character set differences, also type differences could lead to weird side effects -# Another note about this - we could probably easily pull in values of child components if this was referenced from a system-level - so this kind of behaves a bit like help values.yaml -constants: - # map[string]interface{} - elements referenced via template as {{ .const.key }} - type: software - title: lula - # Sample: Istio-specific values - istio: - namespace: istio-system # overriden by --set const.istio.namespace=my-istio-namespace - resources: - jsoncm: configmaps # (NOT) overriden by LULA_VAR_RESOURCES_JSONCM - # Problem with this is that json-cm and json_cm are different yaml keys, but would possibly reconcile to the same thing... so you're getting some side effects here that aren't great. - yamlcm: configmaps - secret: secrets - pod: pods - boolean: false # (NOT) overriden by LULA_VAR_RESOURCES_BOOLEAN - # ok how does this work when they're different types? an env var will always be a string... - exemptions: - - one - - two - - three - -# variables = place to define changing values of string type, and optionally sensitive values -# NOTE - if a variable is defined here, but does not have a default, you will need to make sure it's set either via --set or LULA_VAR_* for the template to execute without error (actually it doesn't error, just prints debug statements) -variables: - - key: some_lula_secret # set by LULA_VAR_SOME_LULA_SECRET / overriden by --set var.some_lula_secret=my-secret - default: blahblah # optional - sensitive: true # {{ var.some_lula_secret | mask }} - - key: some_env_var - default: this-should-be-overridden - -# Lula config values, still accessible via LULA_*, where * is the key -log_level: info -target: il5 -``` \ No newline at end of file