Infrastructure as Code (IaC) is a scorching matter nowadays, and the IaC software of alternative is Terraform by HashiCorp. Terraform is a cloud provisioning product that gives infrastructure for any software. You may confer with a protracted listing of suppliers for any goal platform.
Terraform’s listing of suppliers now contains Cisco Modeling Labs (CML) 2, so we will use Terraform to regulate digital community infrastructure working on CML2. Preserve studying to learn to get began with Terraform and CML, from the preliminary configuration by means of its superior options.
How does Terraform work?
Terraform makes use of code to explain the specified state of the required infrastructure and observe this state over the infrastructure’s lifetime. This code is written in HashiCorp Configuration Language (HCL). If it adjustments, Terraform figures out all of the variations (state adjustments) to replace the infrastructure and assist attain the brand new state. Finally, when the infrastructure isn’t wanted anymore, Terraform can destroy it.
A Terraform supplier presents assets (issues which have state) and information sources (read-only information with out state).
In CML2 phrases, examples embrace:
- Sources: Labs, nodes, hyperlinks
- Knowledge sources: Labs, nodes, and hyperlinks, in addition to out there nodes and picture definitions, out there bridges for exterior connectors, and person lists and teams, and many others.
NOTE: Presently, just a few information sources are carried out.
Getting began with Terraform and CML
To get began with Terraform and CML, you’ll want the next:
Outline and initialize a workspace
First, we’ll create a brand new listing and alter it as follows:
$ mkdir tftest $ cd tftest
All of the configuration and state required by Terraform stays on this listing.
The code snippets introduced want to enter a Terraform configuration file, sometimes a file known as primary.tf. Nonetheless, configuration blocks can be unfold throughout a number of information, as Terraform will mix all information with the .tf extension within the present working listing.
The next code block tells Terraform that we need to use the CML2 supplier. It would obtain and set up the newest out there model from the registry at initialization. We add this to a brand new file known as primary.tf:
terraform { required_providers { cml2 = { supply = "registry.terraform.io/ciscodevnet/cml2" } } }
With the supplier outlined, we will now initialize the setting. It will obtain the supplier binary from the Hashicorp registry and set up it on the native laptop. It would additionally create varied information and a listing that holds extra Terraform configuration and state.
$ terraform init Initializing the backend... Initializing supplier plugins... - Discovering newest model of ciscodevnet/cml2... - Putting in ciscodevnet/cml2 v0.4.1... - Put in ciscodevnet/cml2 v0.4.1 (self-signed, key ID A97E6292972408AB) Accomplice and neighborhood suppliers are signed by their builders. If you would like to know extra about supplier signing, you may examine it right here: https://www.terraform.io/docs/cli/plugins/signing.html Terraform has created a lock file .terraform.lock.hcl to file the supplier choices it made above. Embody this file in your model management repository in order that Terraform can assure to make the identical choices by default whenever you run "terraform init" sooner or later. Terraform has been efficiently initialized! It's possible you'll now start working with Terraform. Strive working "terraform plan" to see any adjustments which might be required in your infrastructure. All Terraform instructions ought to now work. In the event you ever set or change modules or backend configuration for Terraform, rerun this command to reinitialize your working listing. In the event you overlook, different instructions will detect it and remind you to take action if vital. $
Configure the supplier
The CML2 terraform supplier wants credentials to entry CML2. These credentials are configured as proven within the following instance. After all, handle, username and password have to match the precise setting:
supplier "cml2" { handle = "https://cml-controller.cml.lab" username = "admin" password = "supersecret" # skip_verify = true }
The skip_verify is commented out within the instance. You would possibly need to uncomment it to work with the default certificates that’s shipped with the product, which is signed by the Cisco CML CA. Contemplate putting in a trusted certificates chain on the controller.
Whereas the above works OK, it’s not advisable to configure clear-text credentials in information which may find yourself in supply code administration (SCM). A greater method is to make use of setting variables, ideally together with some tooling like direnv. As a prerequisite, the variables should be outlined throughout the configuration:
variable "handle" { description = "CML controller handle" kind = string default = "https://cml-controller.cml.lab" } variable "username" { description = "cml2 username" kind = string default = "admin" } variable "password" { description = "cml2 password" kind = string delicate = true }
NOTE: Including the “delicate” attribute ensures that this worth will not be printed in any output.
We now can create a direnv configuration to insert values from the setting into our supplier configuration by making a .envrc file. It’s also possible to obtain this by manually “sourcing” this file utilizing supply .envrc. The good thing about direnv is that this routinely occurs when turning into the listing.
TF_VAR_address="https://cml-controller.cml.lab" TF_VAR_username="admin" TF_VAR_password="secret" export TF_VAR_username TF_VAR_password TF_VAR_address
This decouples the Terraform configuration information from the credentials/dynamic values in order that they will simply be added to SCM, like Git, with out exposing delicate values, reminiscent of passwords or addresses.
Outline the CML2 lab infrastructure
With the fundamental configuration finished, we will now describe our CML2 lab infrastructure. We now have two choices:
- Import-mode
- Outline-mode
Import-mode
This imports an current CML2 lab YAML topology file as a Terraform lifecycle useful resource. That is the “one-stop” resolution, defining all nodes, hyperlinks and interfaces in a single go. As well as, you should utilize Terraform templating to exchange properties of the imported lab (see beneath).
Import-mode instance
Right here’s a easy import-mode instance:
useful resource "cml2_lifecycle" "this" { topology = file("topology.yaml") }
The file topology.yaml will likely be imported into CML2 after which began. We now have to “plan” the change:
$ terraform plan Terraform used the chosen suppliers to generate the next execution plan. Useful resource actions are indicated with the next symbols: + create Terraform will carry out the next actions: # cml2_lifecycle.this will likely be created + useful resource "cml2_lifecycle" "this" { + booted = (identified after apply) + id = (identified after apply) + lab_id = (identified after apply) + nodes = { } -> (identified after apply) + state = (identified after apply) + topology = (delicate worth) } Plan: 1 so as to add, 0 to alter, 0 to destroy. $
Then apply it (-auto-approve is a short-cut and needs to be dealt with with care):
$ terraform apply -auto-approve
Terraform used the chosen suppliers to generate the next execution plan. Useful resource actions are indicated with the next symbols: + create
Terraform will carry out the next actions: # cml2_lifecycle.this will likely be created + useful resource "cml2_lifecycle" "this" { + booted = (identified after apply) + id = (identified after apply) + lab_id = (identified after apply) + nodes = { } -> (identified after apply) + state = (identified after apply) + topology = (delicate worth) } Plan: 1 so as to add, 0 to alter, 0 to destroy. cml2_lifecycle.this: Creating... cml2_lifecycle.this: Nonetheless creating... [10s elapsed] cml2_lifecycle.this: Nonetheless creating... [20s elapsed] cml2_lifecycle.this: Creation full after 25s [id=b75992ec-d345-4638-a6fd-2c0b640a3c22] Apply full! Sources: 1 added, 0 modified, 0 destroyed. $
We are able to now take a look at the state:
$ terraform present # cml2_lifecycle.this: useful resource "cml2_lifecycle" "this" { booted = true id = "b75992ec-d345-4638-a6fd-2c0b640a3c22" nodes = { # (3 unchanged parts hidden) } state = "STARTED" topology = (delicate worth) } $ terraform console > keys(cml2_lifecycle.this.nodes) tolist([ "0504773c-5396-44ff-b545-ccb734e11691", "22271a81-1d3a-4403-97de-686ebf0f36bc", "2bccca61-d4ee-459a-81bd-96b32bdaeaed", ]) > cml2_lifecycle.this.nodes["0504773c-5396-44ff-b545-ccb734e11691"].interfaces[0].ip4[0] "192.168.122.227" > exit $
Easy import instance with a template
This instance is much like the one above, however this time we import the topology utilizing templatefile(), which permits templating of the topology. Assuming that the CML2 topology YAML file begins with
lab: description: "description" notes: "notes" timestamp: 1606137179.2951126 title: ${toponame} model: 0.0.4 nodes: - id: n0 [...]
then utilizing this HCL
useful resource "cml2_lifecycle" "this" { topology = templatefile("topology.yaml", { toponame = "yolo lab" }) }
will change the title: ${toponame} from the YAML with the content material of the string “yolo lab” at import time. Observe that as an alternative of a string literal, it’s completely effective to make use of a variable like var.toponame or different HCL options!
Outline-mode utilization
Outline-mode begins with the definition of a lab useful resource after which provides node and hyperlink assets. On this mode, assets will solely be created. If we need to management the runtime state (e.g., begin/cease/wipe the lab), then we have to hyperlink these parts to a lifecycle useful resource.
Right here’s an instance:
useful resource "cml2_lab" "this" { } useful resource "cml2_node" "ext" { lab_id = cml2_lab.this.id nodedefinition = "external_connector" label = "Web" configuration = "bridge0" } useful resource "cml2_node" "r1" { lab_id = cml2_lab.this.id label = "R1" nodedefinition = "alpine" } useful resource "cml2_link" "l1" { lab_id = cml2_lab.this.id node_a = cml2_node.ext.id node_b = cml2_node.r1.id }
It will create the lab, the nodes, and the hyperlink between them. With out additional configuration, nothing will likely be began. If these assets needs to be began, then you definately’ll want a CML2 lifecycle useful resource:
useful resource "cml2_lifecycle" "prime" { lab_id = cml2_lab.this.id parts = [ cml2_node.ext.id, cml2_node.r2.id, cml2_link.l1.id, ] }
Right here’s what this appears to be like like after making use of the mixed plan.
NOTE: For brevity, some attributes are omitted and have been changed by […]:
$ terraform apply -auto-approve Terraform used the chosen suppliers to generate the next execution plan. Useful resource actions are indicated with the next symbols: + create Terraform will carry out the next actions: # cml2_lab.this will likely be created + useful resource "cml2_lab" "this" { + created = (identified after apply) + description = (identified after apply) + teams = [ ] -> (identified after apply) + id = (identified after apply) [...] + title = (identified after apply) } # cml2_lifecycle.prime will likely be created + useful resource "cml2_lifecycle" "prime" { + booted = (identified after apply) + parts = [ + (known after apply), + (known after apply), + (known after apply), ] + id = (identified after apply) + lab_id = (identified after apply) + nodes = { } -> (identified after apply) + state = (identified after apply) } # cml2_link.l1 will likely be created + useful resource "cml2_link" "l1" { + id = (identified after apply) + interface_a = (identified after apply) + interface_b = (identified after apply) + lab_id = (identified after apply) + label = (identified after apply) + link_capture_key = (identified after apply) + node_a = (identified after apply) + node_a_slot = (identified after apply) + node_b = (identified after apply) + node_b_slot = (identified after apply) + state = (identified after apply) } # cml2_node.ext will likely be created + useful resource "cml2_node" "ext" { + configuration = (identified after apply) + cpu_limit = (identified after apply) + cpus = (identified after apply) [...] + x = (identified after apply) + y = (identified after apply) } # cml2_node.r1 will likely be created + useful resource "cml2_node" "r1" { + configuration = (identified after apply) + cpu_limit = (identified after apply) + cpus = (identified after apply) [...] + x = (identified after apply) + y = (identified after apply) } Plan: 5 so as to add, 0 to alter, 0 to destroy. cml2_lab.this: Creating... cml2_lab.this: Creation full after 0s [id=306f3ebf-c819-4b89-a99d-138a58ca7195] cml2_node.ext: Creating... cml2_node.r2: Creating... cml2_node.ext: Creation full after 1s [id=32f187bf-4f53-462a-8e36-43cd9b6e17a4] cml2_node.r2: Creation full after 1s [id=5d59a0d3-70a1-45a1-9b2a-4cecd9a4e696] cml2_link.l1: Creating... cml2_link.l1: Creation full after 0s [id=a083c777-abab-47d2-95c3-09d897e01d2e] cml2_lifecycle.prime: Creating... cml2_lifecycle.prime: Nonetheless creating... [10s elapsed] cml2_lifecycle.prime: Nonetheless creating... [20s elapsed] cml2_lifecycle.prime: Creation full after 22s [id=306f3ebf-c819-4b89-a99d-138a58ca7195] Apply full! Sources: 5 added, 0 modified, 0 destroyed. $
The parts lifecycle attribute is required to tie the person nodes and hyperlinks into the lifecycle useful resource. This ensures the proper sequence of operations based mostly on the dependencies between the assets.
NOTE: It’s not potential to make use of each import and parts on the identical time. As well as, when importing a topology utilizing the topology attribute, a lab_id can’t be set.
Superior utilization
The lifecycle useful resource has a couple of extra configuration parameters that management superior options. Right here’s an inventory of these parameters and what they do:
- configs is a map of strings. The keys are node labels, and the values are node configurations. When these are current, the supplier will test for all node labels to see whether or not they’re matching and, if they’re, change the node’s configuration with the offered configuration. This lets you “inject” configurations right into a topology file. The bottom topology file might don’t have any configurations, by which case the precise configurations could be offered through an instance file(“node1-config”) or a literal configuration string, as proven right here:
configs = { "node-1": file("node1-config") "node-2": "hostname node2" }
- staging defines the node begin sequence when the lab is began. Node tags are used to attain this. Right here’s an instance:
staging = { phases = ["infra", "core", "site-1"] start_remaining = true }
The given instance ensures that nodes with the tag “infra” are began first. The supplier waits till all nodes with this tag are marked as “booted.” Then, all nodes with the tag “core” are began, and so forth. If, after the top of the stage listing, there are nonetheless stopped nodes, then the start_remaining flag determines whether or not they need to stay stopped or needs to be began as properly (the default is true, e.g., they’ll all be began).
- state defines the runtime state of the lab. By default that is STARTED, which suggests the lab will likely be began. Choices are STARTED, STOPPED, and DEFINED_ON_CORE
– STARTED is the default
– STOPPED could be set if the lab is at present began, in any other case it can produce a failure
– DEFINED_ON_CORE is wiping the lab if the present state is both STARTED or STOPPED
- timeouts can be utilized to set completely different timeouts for operations. This may be vital for large labs that take a very long time to start out. The defaults are set to 2h .
- wait is a boolean flag, which defines whether or not the supplier ought to anticipate convergence (for instance, when the lab begins, and that is set to false, then the supplier will begin the lab however won’t wait till all nodes throughout the lab are “prepared”).
- id is a read-only computed attribute. A UUIDv4 will likely be auto-generated at create time and assigned to this ID.
CRUD operations
Of the 4 primary operations of useful resource administration, create, learn, replace, and delete (CRUD), the earlier sections primarily described the create and skim side. However Terraform may take care of replace and delete.
Plans could be modified, new assets could be added, and current assets could be eliminated or modified. That is all the time a results of enhancing/altering your Terraform configuration information after which having Terraform work out the required state adjustments through the terraform plan adopted by a terraform apply as soon as you might be happy with these adjustments.
Updating assets
It’s potential to replace assets, however not each mixture is seamless. Right here are some things to think about:
- Only some node attributes could be modified seamlessly; examples are coordinates (x/y), label, and configuration
- Some plan adjustments will re-create assets. For instance, working nodes will likely be destroyed and restarted is that if the node definition is modified
Deleting assets
Lastly, a terraform destroy will delete all created assets from the controller.
Knowledge Sources
Versus assets, information sources don’t maintain any state. They’re used to learn information from the controller. This information can then be used to reference parts in different information sources or assets. A very good instance, though not but carried out, could be an inventory of accessible node- and image-definitions. By studying these into a knowledge supply, the HCL defining the infrastructure might take out there definitions into consideration.
There are, nevertheless, a couple of information sources carried out:
- Node: Reads a node by offering a lab and a node ID
- Lab: Reads a lab by offering both a lab ID or a lab title
Output
All information in assets and information sources can be utilized to drive output from Terraform. A helpful instance within the context of CML2 is the retrieval of IP addresses from working nodes. Right here’s the best way to do it, assuming that the lifecycle useful resource known as this and in addition assuming that R1 is ready to purchase an IP handle through an exterior connector:
cml2_lifecycle.this.nodes["0504773c-5396-44ff-b545- ccb734e11691"].interfaces[0].ip4[0]
Observe, nevertheless, that output can also be calculated when assets won’t exist, so the above will give an error as a result of node not being discovered or the interface listing being empty. To protect in opposition to this, you should utilize HCL:
output "r1_ip_address" { worth = ( cml2_lifecycle.prime.nodes[cml2_node.r1.id].interfaces[0].ip4 == null ? "undefined" : ( size(cml2_lifecycle.prime.nodes[cml2_node.r1.id].interfaces[0].ip4) > 0 ? cml2_lifecycle.prime.nodes[cml2_node.r1.id].interfaces[0].ip4[0] : "no ip" ) ) }
Output:
r1_ip_address = "192.168.255.115"
Conclusion
The CML2 supplier suits properly into the general Terraform eco-system. With the pliability HCL gives and by combining it with different Terraform suppliers, it’s by no means been simpler to automate digital community infrastructure inside CML2. What is going to you do with these new capabilities? We’re curious to listen to about it! Let’s proceed the dialog on the Cisco Studying Community’s Cisco Modeling Labs Group.
Single customers can buy Cisco Modeling Labs – Private and Cisco Modeling Labs – Private Plus licenses from the Cisco Studying Community Retailer. For groups, discover CML – Enterprise and CML – Increased Schooling licensing and get in touch with us to learn the way Cisco Modeling Labs can energy your NetDevOps transformation.
Be a part of the Cisco Studying Community immediately free of charge.
Observe Cisco Studying & Certifications
Twitter | Fb | LinkedIn | Instagram
Use #CiscoCert to affix the dialog.
References
- https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli
- https://github.com/CiscoDevNet/terraform-provider-cml2
- https://registry.terraform.io/suppliers/CiscoDevNet/cml2
- https://developer.hashicorp.com/terraform/language
- https://direnv.web/
- Picture by Dall-E (https://labs.openai.com/)
Share: