Road to IaC: ACI to Terraform Importer

ACI2TF

A tool to get ACI objects from APIC data and create an import blocks file that Terraform can use

About the project

IaC and automation is good and has plenty of benefits. Using it from day zero is much easier then from day X. Rarely anybody wants to code its infrastructure again just to move into IaC. Getting all the objects/resources into terraform is very time consuming and sometime impossible. The info is there within the APIC but the problem is that is needs to be retrieved and put into the correct format. To be able to do it two sets of code(IaC) needs to be written. Terraform needs to import the objects and have the resource definitions for those objects too. This tool solves the first major step on the road the import part.

Background info

Cisco ACI API

The ACI object model represents the complete configuration and runtime state of every single software and hardware component in the entire infrastructure. The object model is made available through standard REST API interfaces, making it easy to access and manipulate the configuration and runtime state of the system. LINK.

Terraform Import

"Terraform can import existing infrastructure resources. This functionality lets you bring existing resources under Terraform management. Terraform v1.5.0 and later supports import blocks. Unlike the terraform import command, you can use import blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. Learn more about import blocks." LINK

Experimental: While we do not expect to make backwards-incompatible changes to syntax, the -generate-config-out flag and how Terraform processes imports during the plan stage and generates configuration may change in future releases.

The ACI Terraform Importer Script

The tool's main function is to create import blocks for the Cisco ACI (Stanalone or Multi-Pod) (Tenant and Fabric) resources that can be imported to terraform.

The Tenant objects are everything from the Tenant tab of the APIC GUI while the Fabric objects represents everything that are not on the Tenant tab (obviously) (Fabric policies, Access policies, System Settings, Virtual networking, etc... )

Getting Started

Pre-requisites:

• Basic terraform knowledge
• Understand your ACI objects
• Access to the fabric APIC

Clone and install requirements.

git clone https://github.com/routingalchemy/ACI2TF_Import 
cd ACI2TF_Import
pip install -r requirements.txt 

The 2 python files in the directory are:

• aci2tf_app.py - main app
• aci2tf_resources.py - additional data which holds information about the supported ACI objects and the terraform resource names in various formats that the app uses

(back to top)

Usage

• Since v0.5 the code runs from CLI.

usage: aci2tf_app.py [-h] [-u username] [-p password] [-a https://apic_ip_or_fqdn] [-i [tenant/fabric]] [-t [common]]

Script to aid ACI objects to import into Terraform

options:
  -h, --help            show this help message and exit
  -u "username", --user "username"
                        Username
  -p "password", --passwd "password"
                        Password
  -a "apic_ip_or_fqdn", --apic "apic_ip_or_fqdn"
                        APIC URL
  -i [tenant/fabric], --import [tenant]
                        Import type: tenant/fabric
  -t [common], --tenant [common]
                        Tenant to import. If not defined than common will be imported
  -b "True/False", --backup "True/False"
                        Backup the working data tht is pulled form ACI
  -d [True], --default_exclude [True]
                        Exclude "default" named object form the import statements (set to True by default)

1. Provide Username, Password and APIC IP as required arguments python3 aci2tf_app.py -u admin -p password -a 192.168.192.168 -i tenant OR fabric
2. With -i fabric there is no more option, but with -i tenant a tenant name should be specified -t Tenant-o-NAME If tenant name is not specified than than the common tenanat will be imported.
3. (Optionally) if you want a backup from the APIC data that is used during the script run, set argument -b True (a lot of data but can be handy later for writing or checking the resource blocks later)
4. (Optionally) by default the default object from ACI are exluded not can be imported with arguments -d False. Not mandatory, but if you are using them in your config than it is quite important. (default objects are placed into a separate import_default.tf.bak by default :) )
5. Run the script
6. Check import blocks for required amendments(name labels)

(back to top)

Road to IaC (a possible way to do it)

1. Create the import blocks with the tool (it generates import.tf)

2. Check the resource names that was generated by the script and amend if not suits your needs (See Output and Caveat Sections for clarification)

3. From here there are 2 possibilities:

   • Run a terraform plan -generate-config-out=generated.tf (terraform 1.5 or higher is required for this feature(see section XYZ)) with the import block .tf file. This will generate your terraform resources (Experimental feature currently but based on my tests it works quite well)
   • Write your own resources based on your ACI configuration (a backup form the config that was used for the import block creation can help in that (see section Usage point 3))

4. Run a terraform plan and see how good is your terraform code. (Harmless as you don't apply any changes)

   • It is possible that there will be errors durng the run(s). The script/import is flawless, it just helps to do the harder part of the work. A little engineering might be needed to fix some resources.

Example import output:

Plan: 519 to import, 0 to add, 44 to change, 0 to destroy.

In this example:

• based on the import blocks and the code, terraform plan is to import 519 object. Looks promising. No need to do anything with these.
• the second most important bit is that 0 to destroy. It is a good sign. (Don't apply anything if there are any destroys in the code!!!)
• 44 to change is terraform wants to add the annotation = "orchestrator:terraform" to the resource. (But, always check the plan for changes!)
• 0 to add it might be possible that during import terraform wants to add 1-2 resources. Usually it is harmless but as always check the detailed plan for changes!

5. If happy with the plan than apply the code and welcome to the world of IaC

!Always backup your APIC config before trying to import everything into Terraform!

(back to top)

Examples

Import Fabric objects: python3 aci2tf_app.py -u admin -p password -a 192.168.192.168 -i fabric

Import common tenant objects: python3 aci2tf_app.py -u admin -p password -a 192.168.192.168 -i tenant

Import User "CORP" tenant objects:python3 aci2tf_app.py -u admin -p password -a 192.168.192.168 -i tenant -t CORP

Import Fabric objects with work data bakcup: python3 aci2tf_app.py -u admin -p password -a 192.168.192.168 -i fabric -b True

(back to top)

Caveats

• Multi-Site and NDO managed objects are not supported at the moment.
• Although the terraform ACI provider supports it, the cloud objects are currently not implemented for import yet.
• Terraform resource names are sometime very long It needs a manual amendment to the desired format.
• Some objects are imported in Tenant and Fabric section too. (WIP)

(back to top)

Roadmap

• Only inport objects from APIC that are not NDO/MSO managed (NDO/MSO managed object should be imported from NDO/MSO)
• NDO object import
• Offline import (from an APIC output file)
• Cloud object import
• Resource block generation (WIP)
• Updater for the the aci2tf_rresources.py file
• Filter option for default objects.
• More granular import options
• Impove terraform resource naming (based on DNs)
• CLI based run

(back to top)

Notes

• The project files are formatted with Black
• Terraform has to be at least version 1.5 (for import block support)
• The tool supports objects/resources based on terraform's ACI provider Version 2.14.0
• Code has been tested on ACI 6.x only

(back to top)