»Input Variables

Input variables let you customize aspects of Waypoint configuration with values that may change, or that need to be set per Waypoint run. Input variables can also be used to fetch values from remote sources.

You can parameterize your configuration by declaring variables in the waypoint.hcl file, and setting their values using CLI options, environment variables, auto files, and the Waypoint server UI.

Values used during a build, deploy, release, or up operation will output to the CLI.

Hands-on: Try the Input Variables tutorial.

»Declaring an Input Variable

Each input variable referenced in the waypoint.hcl file must be declared using a variable block. Example variable declaration blocks include:

variable "port" {
  type    = number
  default = 8080
  env     = ["PORT"]
}

variable "image_name" {
  type    = string
  default = "latest"
}

variable "docker_labels" {
  type = object({
    environment = string
    log_level   = string
  })
  default = {
      environment = "test"
      log_level   = "debug"
  }
}

variable "port" {
  type    = number
  default = 8080
  env     = ["PORT"]
}

variable "image_name" {
  type    = string
  default = "latest"
}

variable "docker_labels" {
  type = object({
    environment = string
    log_level   = string
  })
  default = {
      environment = "test"
      log_level   = "debug"
  }
}

The label after the variable keyword is a name for the variable, which must be unique among all variables in the same waypoint.hcl file. This name is used to assign a value to the variable and to reference the variable's value when evaluating the configuration.

The name of a variable can be any valid identifier.

»Arguments

Waypoint CLI defines the following optional arguments for variable declarations:

• default - A default value.
• type - This specifies what value types are accepted for the variable.
• description - This specifies the input variable's documentation.
• env - Default value sourced from an environment variable.
• sensitive - If set to true, the variables value will be obfuscated in outputs.

»Default values

The variable declaration can include a default argument. If present, the default value will be used if no value is set when running Waypoint. The default argument requires a literal value and cannot reference functions or other objects in the configuration. The default value can be null.

A default value of null can useful when you want to initialize a project with variables you intend to define just-in-time, such as via a -var flag on the command line. waypoint init will fail to initialize plugins that rely on variables with no defined value. While a null value in a given stage will not be valid when the receiving field needs to evaluate the value it is a fine placeholder for initializing a project.

This also allows for variables that are not used in all stanzas to be indicated as optional values.

For example, given the below waypoint.hcl file, you could run waypoint build without needing to pass in a value for the port variable. If you ran waypoint up or waypoint deploy without specifying a value, you would receive an error.

app "my-app" {
  build {
    use "docker" {}
  }

  deploy {
    use "docker" {
      service_port = var.port
    }
  }
}

variable "port" {
  type    = number
  default = null
}

app "my-app" {
  build {
    use "docker" {}
  }

  deploy {
    use "docker" {
      service_port = var.port
    }
  }
}

variable "port" {
  type    = number
  default = null
}

»Type Constraints

The type argument in a variable block allows you to restrict the type of value that will be accepted as the value for a variable.

While type constraints are optional, we recommend specifying them; they can serve as helpful reminders for users of the module, and they allow Waypoint to return a helpful error message if the wrong type is used.

Type constraints are created from a mixture of type keywords and type constructors. The supported type keywords are:

• string
• number
• bool

The type constructors allow you to specify complex types such as collections:

• list(<TYPE>)
• set(<TYPE>)
• map(<TYPE>)
• object({<ATTR NAME> = <TYPE>, ... })
• tuple([<TYPE>, ...])

If both the type and default arguments are specified, the given default value must be convertible to the specified type.

If no type constraint is set then a type will be inferred from the default value.

If neither type nor default is set, then the value type will be evaluated as follows:

• A value supplied from an environment variable or a CLI flag will be evaluated as a string.
• A value supplied from a wpvars file will be evaluated as one of the three primitive types, string, number, or bool, based on syntax.
• A value supplied from the UI will be evaluated as either a string or HCL type constructor, dependent on if the HCL option is selected.

»Input Variable Documentation

To aid in documentation of what defined variables are expected to be used for, you can briefly describe the purpose of each variable using the optional description argument:

variable "image_tag" {
  type        = string
  description = "The tag assigned to built Docker images."
}

variable "image_tag" {
  type        = string
  description = "The tag assigned to built Docker images."
}

The description should concisely explain the purpose of the variable and what kind of value is expected.

»Sensitive Values

If set to true, the variable value will be obfuscated in outputs. This should not be relied on as a security measure on its own, but can be used as a way to hide literal variable values from logging, CLI output, and the UI. Variable values shared with the user via these methods will generate a SHA256 hashed value using the server cookie as the salt along with the set value. Therefore, the user running an operation can verify whether the expected value was used by verifying the outputted SHA256 hashed value.

Defining a variable as “sensitive” in the waypoint.hcl definition looks like this:

variable "auth_email" {
  sensitive   = true
  type        = string
}

variable "auth_email" {
  sensitive   = true
  type        = string
}

The resulting output value displayed:

   VARIABLE  |                     VALUE                      |   TYPE    | SOURCE
-------------+------------------------------------------------+-----------+----------
  auth_email | 63fc1b8d861dd448c9ae7eaae3102e8a6dd14b838c8bbf | sensitive | default
             | 1c0ed2f4eceb967d0c                             |           |

   VARIABLE  |                     VALUE                      |   TYPE    | SOURCE
-------------+------------------------------------------------+-----------+----------
  auth_email | 63fc1b8d861dd448c9ae7eaae3102e8a6dd14b838c8bbf | sensitive | default
             | 1c0ed2f4eceb967d0c                             |           |

Retrieve the server cookie using the command waypoint server cookie:

$ waypoint server cookie
WPC01FZ1FB3FQ1BYABXVN67FAPXJE

$ waypoint server cookie
WPC01FZ1FB3FQ1BYABXVN67FAPXJE

Then verify by combining the cookie with the value you expected Waypoint to use:

$ echo -n "WPC01FZ1FB3FQ1BYABXVN67FAPXJEmyemail@mycorp.com" | sha256sum
63fc1b8d861dd448c9ae7eaae3102e8a6dd14b838c8bbf1c0ed2f4eceb967d0c

$ echo -n "WPC01FZ1FB3FQ1BYABXVN67FAPXJEmyemail@mycorp.com" | sha256sum
63fc1b8d861dd448c9ae7eaae3102e8a6dd14b838c8bbf1c0ed2f4eceb967d0c

»Using Input Variable Values

Within the waypoint.hcl file that declared a variable, its value can be accessed from within expressions as var.<NAME>, where <NAME> matches the label given in the declaration block:

  deploy {
    use "docker" {
      service_port = var.port
    }
  }

  deploy {
    use "docker" {
      service_port = var.port
    }
  }

The value assigned to a variable can only be accessed within the app stanza. Top-level parameters, such as the project or app names, cannot reference variable values.

»Assigning Values to Custom Input Variables

When variables are declared in your configuration, they can be set in a number of ways. Waypoint loads variables in the following order, with later sources taking precedence over earlier ones:

• In the project settings via the Waypoint server's UI.
• Automatically loaded variable definition files, named with the pattern *.auto.wpvars.
• As environment variables.
• In variable definitions (.wpvars) files specified with the -var-file command line option.
• Individually, with the -var command line option.

The following sections describe these options in more detail.

»Variables on the Command Line

To specify individual variables on the command line, use the -var option when running the waypoint up or specific stage commands (e.g. waypoint build). You can use the -var option multiple times in a single command to set several different variables.

$ waypoint up -var="port=8080"

$ waypoint up -var="port=8080"

$ waypoint up -var='networks=["internal","dev-test"]' -var="port=8080"

$ waypoint up -var='networks=["internal","dev-test"]' -var="port=8080"

$ waypoint up -var='network_map={"internal":8080,"dev-test":9701}'

$ waypoint up -var='network_map={"internal":8080,"dev-test":9701}'

The above examples show appropriate syntax for Unix-style shells, such as on Linux or macOS. If you're on Windows, we recommend using the Windows Command Prompt (cmd.exe). When you pass a variable value to Waypoint from the Windows Command Prompt, use double quotes " around the argument:

$ waypoint up -var "name=value"

$ waypoint up -var "name=value"

If your intended value includes literal double quotes then you'll need to escape those with a backslash:

$ waypoint up -var "name=va\"lue"

$ waypoint up -var "name=va\"lue"

»Variable Definitions (.wpvars) Files

To set lots of variables, it is more convenient to specify their values in a variable definitions file (with a filename ending in either .wpvars or .wpvars.json) and then specify that file on the command line with -var-file:

$ waypoint up -var-file="testing.wpvars"

$ waypoint up -var-file="testing.wpvars"

A variable definitions file uses the same basic syntax as Waypoint language files, but consists only of variable name assignments:

port = "8080"
networks = [
  "internal",
  "dev-test",
]

port = "8080"
networks = [
  "internal",
  "dev-test",
]

Waypoint also automatically loads any auto variable definitions files - files with names ending in .auto.wpvars or .auto.wpvars.json - if they are present.

Files whose names end with .json are parsed instead as JSON objects, with the root object properties corresponding to variable names:

{
  "port": 8080,
  "networks": ["internal", "dev-test"]
}

{
  "port": 8080,
  "networks": ["internal", "dev-test"]
}

»Environment Variables

If a variable specifies a value for the env field, environment variables of those names are searched to provide a value for the variable. The variables are searched in order, and the first non-empty environment variable is used. The special environment variable named WP_VAR_<name> (where <name> is the name of the variable) always works regardless of if env is set or not.

For example, given the following variable:

variable "port" {
  type    = number
  default = 8080
  env     = ["PORT"]
}

variable "port" {
  type    = number
  default = 8080
  env     = ["PORT"]
}

Waypoint will search for a value in WP_VAR_port followed by PORT. If neither are set, the default 8080 is used as specified in the stanza.

This can be useful when running Waypoint in automation, or when running a sequence of Waypoint commands in succession with the same variables. For example, at a bash prompt on a Unix system:

$ export WP_VAR_port=8080 && waypoint up
...

$ export WP_VAR_port=8080 && waypoint up
...

On operating systems where environment variable names are case-sensitive, Waypoint matches the variable name exactly as given in configuration, and so the required environment variable name will usually have a mix of upper and lower case letters as in the above example.

»Variables in the UI

To assign variable values in the UI, navigate to the Project Settings page and then to the Input Variables tab.

Add new variables using the variable name as the key, and the value you wish to assign as the value. All non-HCL values will be evaluated as strings, and values with the HCL box selected will be evaluated as a complex type.

All values will then be converted to the type specified in the corresponding variable definition block in the waypoint.hcl file. If the value cannot be converted to this type (or, if type is unset, the implicit type of the default value), you will receive an error.

»Complex-typed Values

When variable values are provided in a variable definitions file, you can use Waypoint's usual syntax for literal expressions to assign complex-typed values, like lists and maps.

Some special rules apply to the -var command line option and to environment variables. For convenience, Waypoint defaults to interpreting -var and environment variable values as literal strings, which need only shell quoting, and no special quoting for Waypoint. For example, in a Unix-style shell:

$ export WP_VAR_port=8080

$ export WP_VAR_port=8080

However, if a root module variable uses a type constraint to require a complex value (list, set, map, object, or tuple), Waypoint will instead attempt to parse its value using the same syntax used within variable definitions files, which requires careful attention to the string escaping rules in your shell:

$ export WP_VAR_networks='["internal","dev-test"]'

$ export WP_VAR_networks='["internal","dev-test"]'

For readability, and to avoid the need to worry about shell escaping, we recommend always setting complex variable values via variable definitions files.

»Values for Undeclared Variables

If you have defined a variable value, but not its corresponding variable {} definition in the waypoint.hcl file, you will get an error.

To avoid this error, either declare a variable block for the value, or remove the variable value from your Waypoint call.

»Variable Definition Precedence

The above mechanisms for setting variables can be used together in any combination. If the same variable is assigned multiple values, Waypoint uses the last value it finds, overriding any previous values. Note that the same variable cannot be assigned multiple values within a single source. Doing so will result in an error.

Waypoint loads variables in the following order, with later sources taking precedence over earlier ones:

• In the project settings via the Waypoint server's UI.
• Automatically loaded variable definition files, named with the pattern *.auto.wpvars.
• From environment variables prefixed with WP_VAR_.
• In variable definitions files (e.g. dev.wpvars) specified with the -var-file command line option.
• Individually, with the -var command line option.