First Steps

This section provides a simple, easy-to-understand example of creating a network hierarchy and IP pools for new or existing deployments. It helps familiarize users with Catalyst Center as Code to manage Catalyst Center.

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

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)

Getting Started

Start by cloning the repository to your local system:

git clone https://github.com/netascode/nac-catalystcenter-simple-example.git

Open the folder in your preferred editor / IDE.

The working area should look like this (the editor shown here is vsCode):

The main.tf file contains the required providers, provider settings and points to the location of all *.yaml file definitions.

module "catalyst_center" {
  source  = "netascode/nac-catalystcenter/catalystcenter"
  version = "0.1.1"

  yaml_directories = ["data/"]
}

Sites definitions

An example site’s definition is provided in data/sites.nac.yaml. This is where the data (variable definition) is abstracted from the logic (infrastructure declaration).

Before diving into this file, it is worth understanding the *.yaml files and their structure in the data folder a bit better. As different teams might be responsible for different parts of the infrastructure, these definitions need to be flexible. Some organizations might want to use a single *.yaml file for their entire network hierarchy, while others prefer a *.yaml file per area. The names of the yaml files are completely arbitrary. These two examples are explained below:

Example 1: Group multiple areas in the same *.yaml file

multiple_areas.nac.yaml

catalyst_center:
  sites:
    areas:
      - name: Canada
        parent_name: Global
      - name: Poland
        parent_name: Global

Example 2: Split the configuration for areas into multiple *.yaml files

emear_areas.nac.yaml

---
catalyst_center:
  sites:
    areas:
      - name: Poland
        parent_name: Global

amer_areas.nac.yaml

---
catalyst_center:
  sites:
    areas:
      - name: Canada
        parent_name: Global

Now that you are familiar with the structure, it is time to get into the example.

Step 1: Sites Validation

This is where the exciting bit starts. Navigate to data/sites.yaml and take note of the structure. This example contains five areas, four buildings and six floors.

sites.nac.yaml

---
catalyst_center:
  sites:
    areas:
      - name: United States
        parent_name: Global
      - name: Golden Hills Campus
        parent_name: Global/United States
      - name: Lakefront Tower
        parent_name: Global/United States
      - name: Oceanfront Mansion
        parent_name: Global/United States
      - name: Desert Oasis Branch
        parent_name: Global/United States
    buildings:
      - name: Sunset Tower
        latitude: 34.099
        longitude: -118.366
        address: 8358 Sunset Blvd, Los Angeles, CA 90069
        country: United States
        parent_name: Global/United States/Golden Hills Campus
        ip_pools_reservations:
          - ST_CORP
          - ST_TECH
          - ST_GUEST
          - ST_BYOD
      - name: Windy City Plaza
        latitude: 41.878
        longitude: -87.630
        address: 233 S Wacker Dr, Chicago, IL 60606
        country: United States
        parent_name: Global/United States/Lakefront Tower
        ip_pools_reservations:
          - WCP_CORP
          - WCP_TECH
          - WCP_GUEST
          - WCP_BYOD
      - name: Art Deco Mansion
        latitude: 25.782
        longitude: -80.133
        address: 123 Ocean Drive, Miami Beach, FL 33139
        country: United States
        parent_name: Global/United States/Oceanfront Mansion
        ip_pools_reservations:
          - ADM_CORP
          - ADM_TECH
          - ADM_GUEST
          - ADM_BYOD
      - name: Desert Oasis Tower
        latitude: 33.448
        longitude: -112.074
        address: 1235 Cactus Ave, Phoenix, AZ 85001
        country: United States
        parent_name: Global/United States/Desert Oasis Branch
        ip_pools_reservations:
          - DOT_CORP
          - DOT_TECH
          - DOT_GUEST
          - DOT_BYOD
    floors:
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Golden Hills Campus/Sunset Tower
      - name: FLOOR_2
        floor_number: 2
        parent_name: Global/United States/Golden Hills Campus/Sunset Tower
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Lakefront Tower/Windy City Plaza
      - name: FLOOR_2
        floor_number: 2
        parent_name: Global/United States/Lakefront Tower/Windy City Plaza
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Oceanfront Mansion/Art Deco Mansion
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Desert Oasis Branch/Desert Oasis Tower

Areas

Each area consists of name and parent_name attributes. To explore additional attributes available for areas, please refer to the Data Model Documentation.

Buildings

Each building has the following attributes:

name - building name
latitude - building latitude
longitude - building longitude
address - building address
country - country name
parent_name - parent name of that building (site name hierarchy)
ip_pools_reservations - contains a list of IP pools defined in data/ip_pools.nac.yaml

To explore additional attributes available for buildings, please refer to the Data Model Documentation.

Floors

Each floor has name, parent_name and floor_number attributes. To explore additional attributes available for floors, please refer to the Data Model Documentation.

Step 2: IP Pools Validation

Navigate to data/ip_pools.nac.yaml and take note of the structure. This example contains four IP Pools and sixteen reserved IP Subpools.

ip_pools.nac.yaml

---
catalyst_center:
  network_settings:
    ip_pools:
      - name: US_CORP
        ip_address_space: IPv4
        ip_pool_cidr: 10.201.0.0/16
        dhcp_servers:
          - 10.201.0.1
        dns_servers:
          - 10.201.0.1
        ip_pools_reservations:
          - name: DOT_CORP
            prefix_length: 24
            subnet: 10.201.1.0
          - name: ST_CORP
            prefix_length: 24
            subnet: 10.201.2.0
          - name: WCP_CORP
            prefix_length: 24
            subnet: 10.201.3.0
          - name: ADM_CORP
            prefix_length: 24
            subnet: 10.201.4.0
      - name: US_TECH
        ip_address_space: IPv4
        ip_pool_cidr: 10.202.0.0/16
        dhcp_servers:
          - 10.202.0.1
        dns_servers:
          - 10.202.0.1
        ip_pools_reservations:
          - name: DOT_TECH
            prefix_length: 24
            subnet: 10.202.1.0
          - name: ST_TECH
            prefix_length: 24
            subnet: 10.202.2.0
          - name: WCP_TECH
            prefix_length: 24
            subnet: 10.202.3.0
          - name: ADM_TECH
            prefix_length: 24
            subnet: 10.202.4.0
      - name: US_GUEST
        ip_address_space: IPv4
        ip_pool_cidr: 10.203.0.0/16
        dhcp_servers:
          - 10.203.0.1
        dns_servers:
          - 10.203.0.1
        ip_pools_reservations:
          - name: DOT_GUEST
            prefix_length: 24
            subnet: 10.203.1.0
          - name: ST_GUEST
            prefix_length: 24
            subnet: 10.203.2.0
          - name: WCP_GUEST
            prefix_length: 24
            subnet: 10.203.3.0
          - name: ADM_GUEST
            prefix_length: 24
            subnet: 10.203.4.0
      - name: US_BYOD
        ip_address_space: IPv4
        ip_pool_cidr: 10.204.0.0/16
        dhcp_servers:
          - 10.204.0.1
        dns_servers:
          - 10.204.0.1
        ip_pools_reservations:
          - name: DOT_BYOD
            prefix_length: 24
            subnet: 10.204.1.0
          - name: ST_BYOD
            prefix_length: 24
            subnet: 10.204.2.0
          - name: WCP_BYOD
            prefix_length: 24
            subnet: 10.204.3.0
          - name: ADM_BYOD
            prefix_length: 24
            subnet: 10.204.4.0

Step 3: Sites and IP Pools Deployment

To deploy sites and IP pools to Catalyst Center, follow these steps:

1. Edit the main.tf file: Update the provider block with the correct credentials and URL for Catalyst Center. For more information see: Terraform Provider Documentation.

provider "catalystcenter" {
  username = "username"
  password = "password"
  url      = "https://catalyst-center.url"
}

2. Save the main.tf file: Use (Ctrl + S) to save your changes.

The next step is to Initialize Terraform. This process, executed with the terraform init command, prepares your working directory for other Terraform commands by:

Configuring the Backend: Sets up where your Terraform state file will be stored, which can be local or remote.
Downloading Provider Plugins: Retrieves the necessary provider plugins specified in your configuration to interact with various infrastructure APIs.
Installing Modules: Downloads any modules specified in your configuration.
Preparing the Directory: Sets up the directory structure and files needed for managing the Terraform state and configurations.
Version Compatibility Check: Ensures the provider plugins match the specified version constraints for compatibility.

To initialize Terraform, first, open a terminal.

Once the terminal is open, run the following command to initialize Terraform:

terraform init

Upon success you should receive the following output:

➜  nac-catalystcenter-simple-example git:(main) ✗ terraform init
Initializing the backend...
Initializing modules...
Downloading registry.terraform.io/netascode/nac-catalystcenter/catalystcenter 0.1.1 for catalyst_center...
- catalyst_center in .terraform/modules/catalyst_center
Initializing provider plugins...
- terraform.io/builtin/terraform is built in to Terraform
- Finding hashicorp/local versions matching ">= 2.3.0"...
- Finding hashicorp/time versions matching ">= 0.12.1"...
- Finding ciscodevnet/catalystcenter versions matching ">= 0.3.0, 0.3.0"...
- Finding netascode/utils versions matching ">= 1.0.0"...
- Installing hashicorp/local v2.5.3...
- Installed hashicorp/local v2.5.3 (signed by HashiCorp)
- Installing hashicorp/time v0.13.1...
- Installed hashicorp/time v0.13.1 (signed by HashiCorp)
- Installing ciscodevnet/catalystcenter v0.3.0...
- Installed ciscodevnet/catalystcenter v0.3.0 (signed by a HashiCorp partner, key ID 974C06066198C482)
- Installing netascode/utils v1.0.2...
- Installed netascode/utils v1.0.2 (self-signed, key ID 48630DA58CAFD6C0)
Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:
https://www.terraform.io/docs/cli/plugins/signing.html
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Run terraform apply (this applies the changes defined by your Terraform configuration to create, update or destroy resources):

terraform apply

Followed by yes to approve.

Upon success you should receive the following output:

Apply complete! Resources: 36 added, 0 changed, 0 destroyed.

Navigate to your Catalyst Center web GUI and verify that site hierarchy and IP Pools have been deployed successfully.

Go to Design > Network Hierarchy

Go to Design > Network Settings > IP Address Pools

Step 4: Adding additional resources

Now that the sites and IP Pools are deployed, it becomes easy to add additional resources to Sites. Add a new Floor definition to Art Deco Mansion building (Global/United States/Oceanfront Mansion/Art Deco Mansion) by adding the following lines to the floors section in sites.nac.yaml:

      - name: FLOOR_2
        floor_number: 2
        height: 4
        parent_name: Global/United States/Oceanfront Mansion/Art Deco Mansion

The sites.nac.yaml file with the new floor should look like this:

sites.nac.yaml

---
catalyst_center:
  sites:
    areas:
      - name: United States
        parent_name: Global
      - name: Golden Hills Campus
        parent_name: Global/United States
      - name: Lakefront Tower
        parent_name: Global/United States
      - name: Oceanfront Mansion
        parent_name: Global/United States
      - name: Desert Oasis Branch
        parent_name: Global/United States
    buildings:
      - name: Sunset Tower
        latitude: 34.099
        longitude: -118.366
        address: 8358 Sunset Blvd, Los Angeles, CA 90069
        country: United States
        parent_name: Global/United States/Golden Hills Campus
        ip_pools_reservations:
          - ST_CORP
          - ST_TECH
          - ST_GUEST
          - ST_BYOD
      - name: Windy City Plaza
        latitude: 41.878
        longitude: -87.630
        address: 233 S Wacker Dr, Chicago, IL 60606
        country: United States
        parent_name: Global/United States/Lakefront Tower
        ip_pools_reservations:
          - WCP_CORP
          - WCP_TECH
          - WCP_GUEST
          - WCP_BYOD
      - name: Art Deco Mansion
        latitude: 25.782
        longitude: -80.133
        address: 123 Ocean Drive, Miami Beach, FL 33139
        country: United States
        parent_name: Global/United States/Oceanfront Mansion
        ip_pools_reservations:
          - ADM_CORP
          - ADM_TECH
          - ADM_GUEST
          - ADM_BYOD
      - name: Desert Oasis Tower
        latitude: 33.448
        longitude: -112.074
        address: 1235 Cactus Ave, Phoenix, AZ 85001
        country: United States
        parent_name: Global/United States/Desert Oasis Branch
        ip_pools_reservations:
          - DOT_CORP
          - DOT_TECH
          - DOT_GUEST
          - DOT_BYOD
    floors:
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Golden Hills Campus/Sunset Tower
      - name: FLOOR_2
        floor_number: 2
        parent_name: Global/United States/Golden Hills Campus/Sunset Tower
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Lakefront Tower/Windy City Plaza
      - name: FLOOR_2
        floor_number: 2
        parent_name: Global/United States/Lakefront Tower/Windy City Plaza
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Oceanfront Mansion/Art Deco Mansion
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Desert Oasis Branch/Desert Oasis Tower
      - name: FLOOR_2
        floor_number: 2
        height: 4
        parent_name: Global/United States/Oceanfront Mansion/Art Deco Mansion

Save the file (Ctrl + S) and run terraform apply

terraform apply

Followed by yes to approve.

Terraform will compare the state file with the new plan and calculate any resources that need to be added, changed or destroyed. In this case, one new resource will be created. Terraform will create a new floor under Art Deco Mansion building while the existing resources will not be impacted, meaning if you re-execute the existing configuration stays as it is.

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Navigate to Catalyst Center (Design > Network Hierarchy) and verify that the new floor FLOOR_2 under Art Deco Mansion was added.

Step 5: Removing resources

In this step you will remove floor FLOOR_2 from Art Deco Mansion, which was created in step 4.

Remove the floor FLOOR_2 section from sites.nac.yaml

      - name: FLOOR_2
        floor_number: 2
        height: 4
        parent_name: Global/United States/Oceanfront Mansion/Art Deco Mansion

The sites.nac.yaml file should once again look like this:

---
catalyst_center:
  sites:
    areas:
      - name: United States
        parent_name: Global
      - name: Golden Hills Campus
        parent_name: Global/United States
      - name: Lakefront Tower
        parent_name: Global/United States
      - name: Oceanfront Mansion
        parent_name: Global/United States
      - name: Desert Oasis Branch
        parent_name: Global/United States
    buildings:
      - name: Sunset Tower
        latitude: 34.099
        longitude: -118.366
        address: 8358 Sunset Blvd, Los Angeles, CA 90069
        country: United States
        parent_name: Global/United States/Golden Hills Campus
        ip_pools_reservations:
          - ST_CORP
          - ST_TECH
          - ST_GUEST
          - ST_BYOD
      - name: Windy City Plaza
        latitude: 41.878
        longitude: -87.630
        address: 233 S Wacker Dr, Chicago, IL 60606
        country: United States
        parent_name: Global/United States/Lakefront Tower
        ip_pools_reservations:
          - WCP_CORP
          - WCP_TECH
          - WCP_GUEST
          - WCP_BYOD
      - name: Art Deco Mansion
        latitude: 25.782
        longitude: -80.133
        address: 123 Ocean Drive, Miami Beach, FL 33139
        country: United States
        parent_name: Global/United States/Oceanfront Mansion
        ip_pools_reservations:
          - ADM_CORP
          - ADM_TECH
          - ADM_GUEST
          - ADM_BYOD
      - name: Desert Oasis Tower
        latitude: 33.448
        longitude: -112.074
        address: 1235 Cactus Ave, Phoenix, AZ 85001
        country: United States
        parent_name: Global/United States/Desert Oasis Branch
        ip_pools_reservations:
          - DOT_CORP
          - DOT_TECH
          - DOT_GUEST
          - DOT_BYOD
    floors:
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Golden Hills Campus/Sunset Tower
      - name: FLOOR_2
        floor_number: 2
        parent_name: Global/United States/Golden Hills Campus/Sunset Tower
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Lakefront Tower/Windy City Plaza
      - name: FLOOR_2
        floor_number: 2
        parent_name: Global/United States/Lakefront Tower/Windy City Plaza
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Oceanfront Mansion/Art Deco Mansion
      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Desert Oasis Branch/Desert Oasis Tower

Save the file (Ctrl + S) and run terraform apply:

terraform apply

Followed by yes to approve.

Terraform will compare the state file with the new plan and calculate any resources that need to be added, changed or destroyed. In this case, one resource will be destroyed.

Apply complete! Resources: 0 added, 0 changed, 1 destroyed.

Navigate to the Catalyst Center and verify that the floor FLOOR_2 has been removed from the building Art Deco Mansion

Step 6: Making changes

You have now added and removed resources, but what if you want to deploy additional configuration settings? For example, how would you change floor length on a Floor? Which attributes can you use, and what values are expected? This is where the Datamodel Docs come in. Following the structure of the six different configuration areas, this section contains a list of all the resources that are currently supported. Under each resource you can find a list of attributes, their type, any constraints, whether they are required and whether they have a default value. It also includes a concise example of how that resource can be configured.

If you go to Sites > Floor, you’ll notice that the length attribute is an integer, as described here. This attribute is optional for this resource and does not have a default value. To modify this setting for a floor, you must explicitly specify this attribute.

Update the sites.nac.yaml file by adding the line length: 20 under floor FLOOR_1 in the building Art Deco Mansion.

length: 20

The section for FLOOR_1 should look like this:

      - name: FLOOR_1
        floor_number: 1
        parent_name: Global/United States/Oceanfront Mansion/Art Deco Mansion
        length: 20

Save the file (Ctrl + S) and run terraform apply:

terraform apply

Followed by yes to approve.

Terraform will compare the existing state file with the new plan and calculate any resources that need to be added, changed or destroyed. In this case, one resource will be changed. The resource will be updated in-place.

Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

This will update the existing Floor with the new setting for length. Navigate to the Catalyst Center and verify that the floor FLOOR_1 under Art Deco Mansion building was updated with the new length configuration.

Go to Design > Network Hierarchy > Global > United States > Oceanfront Mansion > Art Deco Mansion > FLOOR_1. Click on ... and select View Details

Step 7: Working with default values

The previous step explained how to modify a setting on a single resource. If you have specific configuration you wish to apply to each instance of that resource you can leverage a defaults.yaml file. The main.tf plan passes the content of defaults.yaml to the module. This allows a user to modify any default settings to reflect their requirements.

Create defaults.yaml file inside data/ folder with following content:

---
defaults:
  catalyst_center:
    sites:
      floors:
        length: 20

The defaults.yaml file follows the same structure as the other yaml files in the inventory.

Save the file (Ctrl + S) and run terraform apply:

terraform apply

Followed by yes to approve.

The output will show that the terraform apply action will update floors with new length.

Run terraform apply followed by yes to approve.

Step 8: Changing configuration in the GUI

Imagine that someone unaware of the automation efforts makes a change directly in the GUI to one of the objects created by Terraform.

Change floor height to 4ft on FLOOR_1 in Desert Oasis Tower building via the GUI.

Go to Design > Network Hierarchy > Global > United States > Desert Oasis Branch > Desert Oasis Tower > FLOOR_1. Click on ... and select Edit Floor

Because the Terraform state now differs from the running configuration a simple terraform apply will prompt you to update floor. Terraform can detect configuration drift and reconcile it.

Step 9: Cleaning up

The final step is to clean up the configuration.

Run terraform destroy to remove the configuration:

terraform destroy

Followed by yes to approve.

Apply complete! Resources: 0 added, 0 changed, 36 destroyed.

Navigate to Catalyst Center and ensure that IP Pools and Site Hierarchy have been removed.