If your data center team is still provisioning ACI tenants through point-and-click in 2026, the tooling isn’t the problem — the tooling has been mature for years. Terraform’s ACI provider shipped in 2019. Cisco’s Nexus-as-Code removed the HCL learning curve in 2022. Brownfield import means zero excuses for existing fabrics.

This guide walks through the full path: raw Terraform HCL → Nexus-as-Code YAML → CI/CD pipeline with peer-reviewed network changes. Whether you’re managing 5 tenants or 500, the workflow is the same.

Why Terraform for ACI?

Manual APIC GUI provisioning takes 15–30 minutes per tenant with VRF, bridge domain, and EPG creation. A terraform apply does the same in under 60 seconds. But speed is the least interesting benefit — the real value is drift detection, peer review, and rollback capability.

The critical distinction vs. a Python script: idempotency. A script that creates a tenant will fail or create a duplicate if you run it twice. Terraform checks current state first — if the tenant exists and matches your code, it does nothing. If someone manually changed the VRF through the GUI, terraform plan shows exactly what drifted.

Raw Terraform: Your First ACI Tenant

The CiscoDevNet/aci provider (v2.x) supports 90+ resources. Every HCL resource maps 1:1 to an ACI managed object — aci_tenant → fvTenant, aci_vrf → fvCtx, aci_bridge_domain → fvBD.

# providers.tf
terraform {
  required_providers {
    aci = {
      source  = "CiscoDevNet/aci"
      version = "~> 2.15"
    }
  }
}

provider "aci" {
  username = var.apic_username
  password = var.apic_password
  url      = var.apic_url
  insecure = false
}

# main.tf
resource "aci_tenant" "prod" {
  name        = "PROD-Web"
  description = "Production web services tenant"
}

resource "aci_vrf" "prod_vrf" {
  tenant_dn              = aci_tenant.prod.id
  name                   = "PROD-VRF"
  ip_data_plane_learning = "enabled"
}

resource "aci_bridge_domain" "web_bd" {
  tenant_dn          = aci_tenant.prod.id
  name               = "WEB-BD"
  relation_fv_rs_ctx = aci_vrf.prod_vrf.id
  arp_flood          = "no"
  unicast_route      = "yes"
}

terraform init → plan → apply. Entire operation: under 10 seconds against a lab APIC.

Auth: Don’t Hardcode Credentials

export ACI_USERNAME=admin
export ACI_PASSWORD=$(vault kv get -field=password secret/apic)
export ACI_URL=https://apic1.lab.local

The provider reads ACI_USERNAME, ACI_PASSWORD, and ACI_URL automatically. For production, integrate with HashiCorp Vault or your org’s secrets manager.

Nexus-as-Code: YAML Instead of HCL

Nexus-as-Code (NAC) is a Cisco-maintained Terraform module with 150+ sub-modules that translates plain YAML into Terraform ACI resources. Instead of writing individual HCL blocks for every object, you define your fabric in YAML and NAC handles the translation.

The same tenant from above in NAC YAML:

# data/tenants.yaml
apic:
  tenants:
    - name: PROD-Web
      description: "Production web services tenant"
      vrfs:
        - name: PROD-VRF
          ip_data_plane_learning: enabled
      bridge_domains:
        - name: WEB-BD
          vrf: PROD-VRF
          arp_flood: false
          unicast_route: true
          subnets:
            - ip: 10.1.100.1/24
              public: true
              shared: false
      application_profiles:
        - name: Web-App
          endpoint_groups:
            - name: Web-EPG
              bridge_domain: WEB-BD
              physical_domains:
                - PHY-DOM

And the entire main.tf:

module "aci" {
  source  = "netascode/nac-aci/aci"
  version = "0.9.3"

  yaml_directories = ["data"]
}

That’s it. NAC parses the YAML, creates the resources, handles dependency ordering, and manages relationship bindings. For a network engineer who knows ACI but isn’t a developer, this is the difference between a 2-week HCL learning curve and a 2-hour one.

How NAC Works Under the Hood

1. Your YAML files define desired ACI state in data/
2. main.tf loads YAML via yaml_directories
3. NAC root module parses and routes objects to sub-modules
4. Sub-modules contain aci_rest_managed resources → APIC REST API calls
5. Terraform state records what was deployed for drift detection

You never touch raw API calls — only YAML files.

Brownfield Import: The Step Everyone Skips

This is the single most critical step for existing ACI deployments — and the one most commonly skipped.

Without importing existing objects, terraform apply either creates duplicates (APIC rejects with 400) or creates conflicting configs. Both outcomes are bad.

Bulk Import with nac-import

# Clone and run
nac-import --url https://apic1.lab.local --username admin

# Review generated YAML
ls data/

# Verify — plan should show zero changes
terraform init && terraform plan

# Commit — your fabric is now under version control
git add . && git commit -m "Import existing ACI fabric"

Selective Import

If you only want specific tenants under Terraform control:

terraform import aci_tenant.prod uni/tn-PROD-Web
terraform import aci_vrf.prod_vrf uni/tn-PROD-Web/ctx-PROD-VRF
terraform plan  # Should show no changes for imported resources

Remote State: Don’t Keep It on Your Laptop

The state file is Terraform’s record of every managed object. Without it, Terraform can’t detect drift or plan changes. State locking prevents two engineers from running apply simultaneously.

terraform {
  backend "s3" {
    bucket         = "aci-terraform-state"
    key            = "prod/aci/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

Separate state per environment and per fabric. A destroy on dev can’t touch production.

CI/CD Pipeline: Peer-Reviewed Network Changes

The ultimate win — treating network changes like software deployments:

# .github/workflows/aci-deploy.yml
name: ACI Terraform Pipeline
on:
  pull_request:
    paths: ['aci/**']
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init -backend=false
      - run: terraform validate
      - run: terraform fmt -check -recursive

  plan:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform plan -out=tfplan -no-color

  apply:
    needs: plan
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production  # Manual approval gate
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform apply -auto-approve

The environment: production gate requires a designated approver to click “Approve” in GitHub before apply runs. Automated, auditable, enforced.

Common Pitfalls

Pin Your Provider Version

required_providers {
  aci = {
    source  = "CiscoDevNet/aci"
    version = "~> 2.15"
  }
}

The ~> operator allows patch updates (2.15.x) but blocks minor bumps (2.16.0). Provider updates have historically changed attribute names — a floating version can break your plan unexpectedly.

FAQ

Do I need programming experience?
No. HCL is declarative, not a programming language. With NAC, you only write YAML. Git fundamentals matter more than coding.

Terraform vs. Ansible for ACI?
Terraform manages full lifecycle declaratively (create, update, destroy with state tracking). Ansible is imperative and task-oriented. Common pattern: Terraform for day-0/day-1 provisioning, Ansible for day-2 operations.

How do I handle existing ACI configs?
Use nac-import for bulk import or terraform import for selective management. Never write HCL for objects that already exist without importing them first.

Originally published at FirstPassLab. For more deep-dive networking guides, check out firstpasslab.com.

AI Disclosure: This article was adapted from human-researched content with AI assistance for formatting and Dev.to optimization.