Parameter Types and Validation

Converge Parameter Validation: a functional specification

Owner: Sam Hatfield (@sehqlr)

Date/Version: 2016-09-13

Demo & First Release

Overview

The param configuration allows users to declare values that are:

• immutable, as in, they will not be altered during converge operations
• easily referenced in other parts of your converge configuration, using the param keyword
• validated with types and rules, to make sure bad inputs are not introduced into the system

A parameter's type defines the basic kind or encoding of inputs. This matches up with type systems in programming languages in general.

A parameter's rules are additional constraints that define good inputs. Each type has a set of rules associated with it, and are provided as template functions. These functions include the param's value, so they take one less argument.

Param types

The type of a parameter constrains what kind of data can be put into a param. For example, if you want a param to define how many virtual machines you need, you need that param to be an integer, not a float or your cat's name.

string

This is the default type for parameters.

Functions available in rules and predicates:

Name	Description	Rule Example
length	Counts number of chars in the string, returns an int	ne 4 length
empty	this is a shorthand for eq length 0	not empty
oneOf	checks for value's membership in a list, which is given as a single string, separated by spaces	oneOf \apple blackberry cherry``
notIn	this is a shorthand for not oneOf	notIn \lions tigers bears``

int

This is the first type added to parameters. Like string, this type can be inferred from the default value.

Functions available in rules and predicates:

Name	Description	Rule Example
min	is the same as param.Value >= arg	min 45
max	is the same as param.Value <= arg	max 8
isEven	is the same as param.Value % 2 == 0	isEven
isOdd	this is shorthand for not isEven	isOdd

Param syntax

A "rule" is a more specific constraint for a parameter. They are represented as a partial text/template expression.

As of right now, all rules are defined with a must keyword, and all rules must evaluate to true for the parameter to validate.

param "<name>" {
    # all of these fields are optional
    default = <value>
    type = <string|int>
   must = [
    "rule",
    "otherRule",
   ]
}

# Example
param "goldilock's password" {
    type = int
    must = [
        "gt length 8",
        "lt length 12",
        "notOneOf `password porridge justright`",
    ]
}

The param block may have any or none of these fields:

Name	Input	Description	If this is omitted...
default	a literal value or a template expression	the value of the param, if not overridden by other config	the user must provide a value elsewhere
type	string or int	what kind of values can be assigned to this param	it's inferred from default, or falls back on string
must	any array of predicates	If any fail, stop processing current command	only the type validator is processed

For HCL examples, check out samples/paramValidation.hcl in the main repo.