Config Commands

The stategraph config commands edit the stategraph.json file in your module directory: they attach files to addresses and mark tfvars as ephemeral. They run locally and do not contact the server.

Why attach files

When your HCL reads files with file(), templatefile(), fileset(), filebase64(), or data.local_file, Stategraph must know which files belong to a change. stategraph config files records them as globs in stategraph.json, per workspace and address glob. When an attached file changes, the next plan includes the matching resources.

Commands

stategraph config files attach

The address, --dest, and --expr together identify an attachment:

• The same three values again add the new globs to the existing ones.
• A new --dest or --expr records a separate attachment at the same address. It does not move the files already attached.

stategraph config files attach --workspace <workspace> --address <address-glob> [--dest <dest>] [--expr <expr>] [--recursive] <file-glob>...

Options

--dest supports ${path.module} (the module directory of the matched block) and ${path.root} (the bundle root), each with an optional relative subdirectory, for example '${path.module}/config'.

Use --expr when a block has more than one file call, for example --expr 'fileset(path.module, "**/*.yaml")'. --address selects only the block. The next plan or import matches the expression:

• Matching is structural. Formatting and whitespace do not matter, but the function and its arguments must be the same.
• If no block that the address matches contains the expression, the plan or import fails.

With --recursive:

• A directory gives its contents. Its own name is dropped, and each file keeps its path relative to that directory, under --dest.
• A file gives itself, at its basename.
• A path that does not exist, an argument with a glob metacharacter, or two paths that give the same destination file is an error.

Arguments

Example

stategraph config files attach --workspace default --address 'module.app.*' './templates/*.tpl'

Attached 1 glob(s) at module.app.* for workspace default

The resulting entry in stategraph.json:

{
  "workspaces": {
    "default": {
      "attached_files": [
        {
          "address_glob": "module.app.*",
          "globs": [ "./templates/*.tpl" ],
          "dest": null,
          "recursive": false,
          "expr": null
        }
      ]
    }
  }
}

To attach a directory tree under the module directory, use --recursive and --dest:

stategraph config files attach --workspace default --address 'module.app.*' --dest '${path.module}/config' --recursive ./config

Attached 1 path(s) at module.app.* for workspace default

Commit stategraph.json, so that the mappings travel with the module.

stategraph config files remove

An address can hold several attachments, and the command applies to all of them:

• It removes each named glob wherever it occurs at the address. An attachment left with no globs is removed.
• With no globs, it removes every attachment at the address.
• To remove only one of several attachments, edit stategraph.json.

stategraph config files remove --workspace <workspace> --address <address-glob> [<file-glob>...]

Options

Arguments

Examples

# Remove one glob
stategraph config files remove --workspace default --address 'module.app.*' './templates/*.tpl'

# Remove every attachment at the address
stategraph config files remove --workspace default --address 'module.app.*'

stategraph config tfvar ephemeral

An ephemeral tfvar changes at each run but changes nothing, for example a per-run authentication token. Stategraph passes it to the run, but:

• never uses it to create the subgraph,
• never stores it in the database,
• masks its value in the SQL interface.

The globs apply to every workspace.

stategraph config tfvar ephemeral add

stategraph config tfvar ephemeral add <glob>...

The globs use the --force grammar: * matches any sequence of characters, every other character is literal, and a glob must match the whole name.

stategraph config tfvar ephemeral add 'auth_token' '*_session_token'

stategraph config tfvar ephemeral list

Accepts --format (table, json, or simple).

stategraph config tfvar ephemeral list

stategraph config tfvar ephemeral remove

stategraph config tfvar ephemeral remove <glob>...

Each glob is compared with the configured globs as a literal string, not as a pattern. Spell it exactly as config tfvar ephemeral list prints it: removing '*_token' does not remove a configured 'auth_token'. If one of the globs is not configured, the command removes nothing and exits non-zero.

stategraph config tfvar ephemeral remove '*_session_token'

Next steps

• Import Commands: stategraph import tf --attach-files sets the same mappings at import time, and --attach-dest sets the destination directory as --dest does.
• Terraform Commands: attached files in plans.
• HCL Commands: list addresses for globs.