Terraform Provider for Cisco CML2

This repository implements a Terraform provider for Cisco Modeling Labs version 2.9 and later. It's current state is "beta". Changes can be expected, for example:

• configuration (provider, resources, data-sources)
• provider behavior
• features (additional resources, ...)

Note

The provider needs CML 2.9 or newer. This is due to some additional API capabilities which were introduced with 2.9 and due to changes introduced with the new gocmlclient >=0.2.0. Older versions are blocked by the gocmlclient. If you need support for older versions then it is recommended to use version 0.8.5 or earlier.

The current implementation provides:

• Resources and a data sources (internal/provider/),
  • resource cml2_annotation to create, update and destroy lab annotations
  • resource cml2_lab to create, update and destroy labs
  • resource cml2_node to create, update and destroy nodes in a lab
  • resource cml2_link to create, update and destroy links between nodes in a lab
  • resource cml2_lifecycle to control the state of a lab (like STARTED, STOPPED), including staged starting and configuration injection
  • resource cml2_group to create, update and destroy groups
  • resource cml2_user to create, update and destroy users
  • data source cml2_lab to retrieve state of an existing lab
  • data source cml2_node to retrieve state of an existing node in a lab
  • data source cml2_images to retrieve the available node images from the controller
  • data source cml2_groups to retrieve user groups from the controller
  • data source cml2_extconn to retrieve external connector information from the controller
  • data source cml2_system to retrieve system state (ready state, version, ...) from the controller
  • data source cml2_users to retrieve users from the controller
• Examples (examples/) and generated documentation (docs/),
• Miscellaneous meta files.

Requirements

• Terraform >= 1.0
• Go >= 1.25.x
• CML2 >= 2.9.0

Building The Provider

1. Clone the repository
2. Enter the repository directory
3. Build the provider using the Go install command:

go install

Local Development Install (Use Your Local Build)

For beta-testing or local iteration, you can install a locally built provider binary so Terraform uses it instead of downloading from the public registry.

See docs/development/local-provider.md.

Using the provider

Please refer to the examples directory and look at the built-in documentation provided via the registry.

Note

It's recommended to use the UI token (from the User menu, top right "Copy JWT") instead of the user-name and password as that will provide better performance. Using the token avoids repeated client authentication via the API which takes quite a bit of time.

Token Cache (username/password)

When using username/password (instead of a pre-generated JWT), you can enable token caching so repeated Terraform runs do not re-authenticate as often.

Provider configuration is evaluated before resources are created, so HCL cannot reliably create a temporary file resource and feed its path into the provider. Recommended workflow is a wrapper script:

TOKEN_FILE="$(mktemp -t cml2-token.XXXXXX)"
trap 'rm -f "$TOKEN_FILE"' EXIT

export TF_VAR_token_cache=true
export TF_VAR_token_cache_file="$TOKEN_FILE"

terraform apply

Request Headers

If your CML API is fronted by a reverse proxy that expects additional request headers, you can inject static headers into every outbound request, including the initial authentication request.

provider "cml2" {
  address  = var.address
  username = var.username
  password = var.password

  request_headers = {
    Proxy-Authorization = "Bearer ${var.proxy_token}"
  }
}

This is useful when nginx or another proxy performs authentication before forwarding traffic to the CML backend.

HCL

For some basic examples look in the examples directory

Developing the Provider

If you wish to work on the provider, you'll first need Go installed on your machine (see Requirements above).

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

To generate or update documentation, run go generate.

In order to run the full suite of acceptance tests, run make testacc. For this to work, the provider needs to be configured via environment variables. Here's an example:

# for testing purposes, suggest to use direnv

TF_VAR_username="admin"
TF_VAR_password="secret"
TF_VAR_address="https://cml-controller.cml.lab"
# alternatively, this is faster:
# TF_VAR_token="your-token-here"

export TF_VAR_username TF_VAR_password TF_VAR_address

Those variables are referenced for acceptance testing in internal/provider/testing.

make testacc

Acceptance testing with GitHub actions must properly set secrets which are used in the test workflow:

• the NGROK_URL where where the CML API is reachable
• the USERNAME and PASSWORD or alternatively, the CML API TOKEN

This can use Ngrok or other tunneling tools if the CML API isn't directly reachable from the internet.