Configuration

A single nac.yaml at the root of the repository configures all commands. Its location can be changed with --config or NAC_CONFIG. Every field is optional, and a missing nac.yaml is treated like an empty one.

Reference

Field	Default	Description
`working_dir`	`.`	Directory in which `terraform`/`tofu` runs
`data.paths`	`[data/]`	Data model files or directories used by `validate` and `test` when no rendering applies
`data.defaults`	`defaults.yaml` if it exists in `working_dir`	Defaults file added to the data of `test`
`render.target`		Terraform target rendering the data model before validation, e.g. `module.nxos.local_sensitive_file.model`
`render.output`		Path of the rendered data model, e.g. `model.yaml`. Required if `render.target` is set.
`validate.schema`		Schema passed to `nac-validate -s`. If not set, `nac-validate` uses its own default.
`validate.rules`		Rule directories passed to `nac-validate -r`. If not set, `nac-validate` uses its own default.
`test.templates`	`tests/templates` if it exists in `working_dir`	Templates passed to `nac-test -t`. If not set, `nac-test` uses templates provided by the module or a bundle.
`test.filters`	`tests/filters` if it exists in `working_dir`	Filters passed to `nac-test -f`
`test.output`	`tests/results`	Output directory passed to `nac-test -o`
`tools.terraform.engine`	`tofu` if on the `PATH`, else `terraform`	`terraform` or `tofu`
`tools.terraform.version`		Terraform or OpenTofu version installed and used via `tenv`
`tools.nac_validate`	latest compatible with the tested version	Version or version specifier of `nac-validate`, e.g. `1.2.0` or `>=0.9,<1.0`
`tools.nac_test`	latest compatible with the tested version	Version or version specifier of `nac-test`, e.g. `2.0.0` or `>=2.0,<3.0`
`env.required`	`[]`	Environment variables checked by `nac setup`. Their values are never printed.

The data used by the commands follows from the configuration:

validate uses render.output if render.target is set, else data.paths.
test uses render.output if render is configured, else data.paths, followed by data.defaults if configured.

Examples

An ACI repository without rendering. test adds defaults.yaml automatically if it exists at the root of the repository:

env:
  required: [ACI_URL, ACI_USERNAME, ACI_PASSWORD]

An NX-OS repository, where the data model is rendered to model.yaml by the Terraform module before it is validated and tested:

tools:
  terraform:
    engine: tofu

render:
  target: module.nxos.local_sensitive_file.model
  output: model.yaml

env:
  required: [NXOS_USERNAME, NXOS_PASSWORD]

The same NX-OS repository with every field set explicitly:

working_dir: .

data:
  paths: [data/]
  defaults: null

render:
  target: module.nxos.local_sensitive_file.model
  output: model.yaml

validate:
  schema: .schema.yaml
  rules: [.rules]

test:
  templates: tests/templates
  filters: tests/filters
  output: tests/results

tools:
  terraform:
    engine: tofu
    version: "1.9.5"
  nac_validate: ">=0.9,<1.0"
  nac_test: ">=2.0,<3.0"

env:
  required: [NXOS_USERNAME, NXOS_PASSWORD]

Tool Versions

Terraform/OpenTofu: without tools.terraform.version, the binary is looked up on the PATH: tofu first, terraform otherwise, or the one set in tools.terraform.engine. If neither is found, nac setup offers to download and cache a verified OpenTofu binary, without requiring a package manager or tenv. Setting tools.terraform.version uses tenv to install and use that version.

nac-validate/nac-test: a local installation on the PATH is used if it satisfies tools.nac_validate or tools.nac_test (any local version if not set). Otherwise, the tool is run via uvx, e.g. uvx --from nac-validate==<version> nac-validate. If no version is set, uvx uses the latest release, or the latest release compatible with the tested version of the module. nac setup reports whether each tool was resolved to a local installation or uvx. uv is only required if a tool is run via uvx. If it is missing in that case, nac fails with a message naming the tool and the version to install locally instead.

Tested Versions

A Network as Code Terraform module can include a nac/manifest.yaml, next to its schema, rules and test templates, listing the nac-validate and nac-test versions it was tested with:

schema: 1
tools:
  nac-validate: "2.0.0"
  nac-test: "2.0.0"

Terraform, OpenTofu and provider versions are not part of the manifest, as they are already constrained by the versions.tf of the module.

After nac init has downloaded the module, nac finds the manifest via .terraform/modules/modules.json. If several modules include one, the one closest to the root module is used, so a local wrapper module works as well. The manifest is only a hint and is never enforced. Without a manifest, for example before the first nac init, nothing changes.

Defaults: if tools.nac_validate or tools.nac_test is not set, the latest release compatible with the tested version is used instead of the latest release overall. A local installation is used if it is in that range, otherwise uvx downloads it.
Warnings: an explicitly configured version always takes precedence. If it is outside the compatible range, nac validate, nac test and nac setup print a warning, and a short note after the output if the command fails. Exit codes are never changed. Version ranges resolved by uvx, such as >=1.0, are not checked, as the resulting version isn’t known up front.

Compatible means the tested version or newer, up to the next major version, or the next minor version for 0.x versions. A tested version 2.0.0 allows >=2.0.0,<3, a tested version 0.13.1 allows >=0.13.1,<0.14.