First Steps

This section provides an easy-to-understand example of deploying Unified Branches using Branch as Code.

The repository used in this example can be found at: https://github.com/netascode/nac-branch

This example assumes you have installed the following prerequisites.

Terraform 1.8.0 or later.
Git
Your preferred text editor / Integrated Development Environment (IDE) (such as VisualStudio Code)

The configuration templates provided are based on the following Cisco references:

Automation utilizes following resources:

1. Fork the Repository

Fork this repository into your organization’s workspace.
Avoid cloning directly from the upstream if you plan to customize.

# Replace <your-github-org> with your GitHub username or org
git clone https://github.com/<your-github-org>/nac-branch.git
cd nac-branch
git remote add upstream https://github.com/netascode/nac-branch.git
git fetch upstream

2. Export Required Environment Variables

Export all required environment variables before running Terraform:

# Small branch device serial numbers
export small_appliance_01_serial=YOUR_APPLIANCE_SERIAL
export small_ap_01_serial=YOUR_AP1_SERIAL
export small_ap_02_serial=YOUR_AP2_SERIAL
export small_switch_01_serial=YOUR_SWITCH1_SERIAL
export small_switch_02_serial=YOUR_SWITCH2_SERIAL

# Medium branch devices
export medium_appliance_01_serial=YOUR_MEDIUM_APPLIANCE_01_SERIAL
export medium_appliance_02_serial=YOUR_MEDIUM_APPLIANCE_02_SERIAL
export medium_switch_01_serial=YOUR_MEDIUM_SWITCH_01_SERIAL
export medium_switch_02_serial=YOUR_MEDIUM_SWITCH_02_SERIAL
export medium_ap_01_serial=YOUR_MEDIUM_AP_01_SERIAL
export medium_ap_02_serial=YOUR_MEDIUM_AP_02_SERIAL

# Large branch devices
export large_appliance_01_serial=YOUR_LARGE_APPLIANCE_01_SERIAL
export large_appliance_02_serial=YOUR_LARGE_APPLIANCE_02_SERIAL
export large_switch1_serial=YOUR_LARGE_SWITCH_01_SERIAL
export large_switch2_serial=YOUR_LARGE_SWITCH_02_SERIAL
export large_ap1_serial=YOUR_LARGE_AP_01_SERIAL
export large_ap2_serial=YOUR_LARGE_AP_02_SERIAL

# Organization identification
export org_name="Your Meraki Org Name"
export domain="YourDomainIdentifier"

# Admin credentials
export org_admin="admin-username"
export org_admin_email="admin@example.com"

# SNMPv3 credentials
export v3_auth_pass="CHANGE_ME_AUTH"
export v3_priv_pass="CHANGE_ME_PRIV"
export snmp_username="snmpUser"
export snmp_passphrase="CHANGE_ME_SNMP"

# Local device access credentials
export local_status_page_username="statusUser"
export local_status_page_password="CHANGE_ME_STATUS"
export local_page_username="localUser"
export local_page_password="CHANGE_ME_LOCAL"

# RADIUS secrets
export radius_accounting_server1_secret="CHANGE_ME_RADIUS_ACCT"
export radius_accounting_server2_secret="CHANGE_ME_RADIUS_ACCT2"
export radius_server1_secret="CHANGE_ME_RADIUS_AUTH"
export radius_server2_secret="CHANGE_ME_RADIUS_AUTH2"

# Webhook/token settings
export splunk_hec_token="CHANGE_ME_SPLUNK_HEC_TOKEN"

# 3rd party VPN / SSE secrets
export peer1_secret="CHANGE_ME_PEER_SECRET"
export umbrella_secret="CHANGE_ME_UMBRELLA_SECRET"

# Meraki API key (least privilege recommended)
export MERAKI_API_KEY="REPLACE_WITH_API_KEY"

💡 Tip: Use a .env file and source it (source ./set_env_vars.sh).
Ensure .env is excluded via .gitignore. You may also integrate a secrets manager.

3. 🧩 Configure Your Branch Variables

Navigate to the data/ folder and update:

pods_variables.nac.yaml – define branch/pod variables (serials, VLANs, etc.)

A sample configuration is provided for reference. To create multiple branches, simply copy the sample configuration as many times as needed and update the variables accordingly.

4. 🧠 Initialize and Generate Merged Configuration

The main.tf at the repository root defines the NAC module and renders the merged YAML configuration in a single step. No separate workspaces/ directory is needed.

terraform init -input=false
terraform apply -target=module.meraki.module.model -auto-approve -input=false

✅ Output: merged_configuration.nac.yaml generated in the repository root.

5. 🔍 [Optional] Validate Configuration (`nac-validate`)

Validate the merged YAML before deployment to catch syntax or semantic issues early. As part of the toolkit, we can use nac-validate CLI tool to perform syntactic and semantic validation of YAML files.

Install (requires Python 3.10+):

pip install nac-validate

Run validation:

nac-validate merged_configuration.nac.yaml

💡 VS Code users: install the YAML Language Support by Red Hat extension for real-time validation.

👉 Learn more about Configuration Validation.

6. 🗺️ Plan Terraform Deployment

Generate the Terraform plan to preview intended changes:

rm -rf .terraform/modules
terraform get -update
terraform init -input=false
terraform plan -out=plan.tfplan -input=false

⚠️ The included configuration uses Terraform Cloud as backend by default. Update the cloud block in main.tf to match your organization and workspace, or switch to a local backend if preferred.

7. 🚀 Apply Configuration

Apply the configuration to push changes to the Meraki Dashboard:

terraform apply -input=false -auto-approve plan.tfplan

Navigate the Dashboard. After successful apply, you should see the Configured Branches now deployed.

8. ✅ [Optional] Post-Deployment Tests (`nac-test`)

Run post-change tests to confirm that the Meraki Dashboard matches the intended configuration. For this we make use of nac-test CLI tool.

pip install nac-test

Run:

nac-test -d merged_configuration.nac.yaml -t ./tests/templates -o ./tests/results -f ./tests/filters

Passing nac-test confirms configuration integrity and reproducibility.
👉 Learn more about Configuration Testing.

9: Cleaning up

Run terraform destroy to remove the configuration:

terraform destroy

Followed by yes to approve.

Navigate to Dashboard and make sure that configuration of Unified Branches have been removed.