Terraform Provider for Catalyst Center

terraform-provider-catalystcenter is a Terraform Provider for Catalyst Center

Requirements

• Terraform 0.13.x
• Go 1.20 (to build the provider plugin)

Introduction

The terraform-provider-catalystcenter provides a Terraform provider for managing and automating your Catalyst Center environment. It consists of a set of resources and data-sources for performing tasks related to Catalyst Center.

This collection is tested and supports Catalyst Center 2.3.5.3.

Other versions of this collection are compatible with earlier releases of Catalyst Center.

Compatibility matrix

Supported Versions

If you are using an older version of the SDK Terraform provider, we recommend updating to the latest version.

Using the provider

There are two ways to get and use the provider.

1. Downloading and installing it from registry.terraform.io.
2. Building it from the source.

From build (For test)

Clone this repository to: $GOPATH/src/github.com/cisco-en-programmability/terraform-provider-catalystcenter

$ mkdir -p $GOPATH/src/github.com/cisco-en-programmability/
$ cd $GOPATH/src/github.com/cisco-en-programmability/
$ git clone https://github.com/cisco-en-programmability/terraform-provider-catalystcenter.git

Enter the provider directory and build the provider.

Important: Check the architecture of your operating system in the file. MakeFile

$ cd $GOPATH/src/github.com/cisco-en-programmability/terraform-provider-catalystcenter
$ make developtest

If the Makefile values (HOSTNAME, NAMESPACE, NAME, VERSION) were not changed, then use the code below without changes. Otherwise change the values accordingly.

To use this provider, copy and paste this code into your Terraform configuration. Then, run terraform init.

terraform {
  required_providers {
    catalystcenter = {
      source = "cisco-en-programmability/catalystcenter"
      version = "1.2.0-beta"
    }
  }
}

# Configure provider with your Catalyst Center SDK credentials
provider "catalystcenter" {
  # Catalyst Center user name
  username = "admin"
  # it can be set using the environment variable CATALYST_BASE_URL

  # Catalyst Center password
  password = "admin123"
  # it can be set using the environment variable CATALYST_USERNAME

  # Catalyst Center base URL, FQDN or IP
  base_url = "https://172.168.196.2"
  # it can be set using the environment variable CATALYST_PASSWORD

  # Boolean to enable debugging
  debug = "false"
  # it can be set using the environment variable CATALYST_DEBUG

  # Boolean to enable or disable SSL certificate verification
  ssl_verify = "false"
  # it can be set using the environment variable CATALYST_SSL_VERIFY
}

There are several examples of the use of the provider within the folder samples

Example for_each

locals {
 interfaces = {
   "1" = { description = "desc1", interface_uuid = "c6820b57-ecde-4b6d-98db-06ba10486809" },
   "2" = { description = "desc2", interface_uuid = "c6820b57-ecde-4b6d-98db-06ba10486801" },
   "3" = { description = "desc3", interface_uuid = "c6820b57-ecde-4b6d-98db-06ba10486802" }
 }
}

resource "catalystcenter_interface_update" "example" {
  provider = catalystcenter
  for_each = local.interfaces
  parameters {
    description    = each.value.description
    interface_uuid = each.value.interface_uuid
    vlan_id        = each.key
  }
}

Developing the Provider

If you wish to work on the provider, you'll first need Go installed on your machine (version 1.15+ is required). You'll also need to correctly setup a GOPATH, as well as adding $GOPATH/bin to your $PATH.

To compile the provider, run make build. This will build the provider and put the provider binary in the $GOPATH/bin directory.

$ make build
...
$ $GOPATH/bin/terraform-provider-catalystcenter
...

In order to test the provider, you can simply run make test.

$ make test

In order to run the full suite of Acceptance tests, run make testacc.

Note: Acceptance tests create real resources.

$ make testacc

Documentation

In the docs directory you can find the documentation source for this 1.0.19-beta version.

You can find the documentation online for the previously released versions at Terraform Registry - Catalyst Center provider.

Automatic Version Management for Resources and DataSources

In this Terraform provider, version management is handled dynamically for all resources and datasources. The version of a resource or datasource is automatically selected based on the available versions in the environment, allowing users to either use a default version or specify a particular version when needed. Below is an explanation of how this automatic version selection works for both resources and datasources.

General Version Selection Behavior

For all resources and datasources, the behavior follows these general rules:

1. If multiple versions of a resource or datasource exist (e.g., resource_v1, resource_v2):

   • By default, the oldest available version will be selected. That is, if both resource_v1 and resource_v2 are available, the provider will automatically select v1 unless explicitly specified otherwise.
   • If a user wants to use the latest version (e.g., v2), they need to specify it explicitly in the configuration.

2. If only one version of a resource or datasource exists (e.g., only resource_v1):

   • The resource or datasource will automatically be used in that version, without needing to specify the version suffix in the configuration.

3. If only the latest version is available (e.g., only resource_v2 and not resource_v1):

   • The resource or datasource will automatically refer to the latest available version, i.e., resource_v2.

Example- Usage with Resources

Case 1: Both resource_v1 and resource_v2 are available

If both resource_v1 and resource_v2 are available in your environment, the provider will select resource_v1 by default. If you want to use resource_v2, you can specify it explicitly:

# Using version 1 (default)
resource "resource" "default" {
  # This resource will refer to `resource_v1` by default
}

# Explicitly using version 2
resource "resource_v2" "default" {
  # This resource will refer to `resource_v2`
}

Case 2: Only resource_v1 exists

If only resource_v1 is available in your environment, there is no need to specify the version, as the provider will automatically use that version:

resource "resource" "default" {

# This resource will refer to `resource_v1` since it's the only version available
}

Case 3: Only resource_v2 exists

If only resource_v2 is available in your environment, the provider will automatically refer to that version, since resource_v1 is not available:

resource "resource" "default" {

# This resource will refer to `resource_v2` since `resource_v1` is not available
}

Example- Usage with DataSources

The same version selection logic applies to datasources. Below is how version management works for datasources:

Case 1: Both datasource_v1 and datasource_v2 are available

# Using version 1 (default)
data "datasource" "default" {

# This datasource will refer to `datasource_v1` by default
}

# Explicitly using version 2
data "datasource_v2" "default" {

# This datasource will refer to `datasource_v2`
}

Case 2: Only datasource_v1 exists

data "datasource" "default" {

# This datasource will refer to `datasource_v1` since it's the only version available
}

Case 3: Only datasource_v2 exists

data "datasource" "default" {

# This datasource will refer to `datasource_v2` since `datasource_v1` is not available
}

Contribution

Ongoing development efforts and contributions to this provider are tracked as issues in this repository.

We welcome community contributions to this project. If you find problems, need an enhancement or need a new data-source or resource, open an issue or create a PR against the Terraform Provider for Catalyst Center repository.

Change Log

All notable changes to this project will be documented in the CHANGELOG file.

The development team may make additional changes as the library evolves with the Catalyst Center.

Note: Consider reviewing the Changelog to review the new features of the 1.0.19-beta version.

License

This library is distributed under the license found in the LICENSE file.