Variables

Variables are what turn a .glaze file from a snapshot of one project into a template for all of them. They work the Terraform way: declare the input, give it a type, read it through var.. If you have written a variable block before, nothing here will surprise you. If you have not, the good news is that the whole feature fits on one page.

Declared variables#

variable "district" {
  description = "the district the gig is themed after"
  type        = string
  default     = "watson"
}

variable "fixer" {
  type = string
}

session {
  name = "gig-${var.district}"

  window {
    name = "${var.fixer}-ops"

    pane {
      commands = ["echo ${var.fixer} has the next job"]
    }
  }
}

$ glaze up --var fixer=wakako                      # district gets its default value
$ glaze up --var district=arasaka --var fixer=wakako

A variable block has one label, the name. You read the value as var.<name> and only through that namespace.

Rules:

• A variable without a default is required. An unset required variable is an error, and Glazier does not build a partial session.
• A --var flag or a var file entry with a name that no block declares is an error.
• Two variable blocks with the same name are an error.
• glaze format --validate enforces the same contract. A required variable needs a value from --var, --var-file or a default.

Supplying values#

district = "watson"
fixer    = "wakako"

$ glaze up --var-file watson.hcl --var fixer=rogue   # fixer from the flag, district from the file

Glazier applies values in this order: the default first, then the var file, then each --var flag. The last value for a name wins.

Type conversion#

Glazier converts each supplied value and each default to the declared type before it starts a session. A --var value is text, so the conversion matters.

variable "base_index" {
  type    = number
  default = 1
}

variable "verbose" {
  type    = bool
  default = false
}

session {
  name = "typed-demo"

  options = {
    "base-index" = "${var.base_index}"
  }

  window {
    pane {
      commands = ["server --verbose=${var.verbose}"]
    }
  }
}

--var base_index=two is rejected before the session starts. The message says that “two” is not a number. --var verbose=true lands as --verbose=true. --var verbose=TRUE does not:

$ glaze format --validate --stdout --profile-path typed.glaze --var verbose=TRUE
Error: Invalid variable value

  on typed.glaze line 6, in variable "verbose":
   6: variable "verbose" {

The value supplied for variable "verbose" is not a valid bool: a bool is
required; to convert from string, use lowercase "true".

the glaze profile contains errors

Built-in namespaces#

These namespaces sit alongside var. and need no declaration.

session {
  name               = "gig-${var.district}"
  starting_directory = path.pwd

  window {
    name = upper(path.base)

    pane {
      commands = ["deploy --token ${env.token}"]
    }
  }
}

$ GLAZE_ENV_token=abc123 glaze up --var district=watson

Only variables with the GLAZE_ENV_ prefix reach the profile. The rest of your environment does not, so a profile cannot read $HOME or $AWS_SECRET_ACCESS_KEY unless you pass it on purpose.

A deleted working directory#

On Linux, a deleted working directory makes the current directory unreadable. Glazier then leaves out the path namespace. A profile that uses path.pwd or path.base fails with “Current directory not available” and points at the first use. A profile that does not use them still works. A session without starting_directory also needs the current directory, so set the attribute in that case.

down evaluates only the name#

glaze down evaluates only the session name. A variable that appears only deeper in the profile is not required for teardown. When the name needs a variable that has no value, down reports “Required variable not set” for that variable and no other. Thus teardown stays idempotent for scripts. See down.

Why the prefix on env?#

Because a profile is a file you commit, and the whole environment of your shell is not something a committed file should be able to read by accident. The GLAZE_ENV_ prefix makes every exposure a decision you took at the command line. It is a little more typing. It is also the reason a profile from a stranger cannot interpolate your cloud credentials into a window name.

The longer worked example, one profile that serves many projects, is on its own page: One profile, many projects.