UCS Terraform Provider

Overview of solution

The major goal of this project is to be able to Create, Read, Update & Destroy different kind of resources in UCS, from Service Profiles to Boot Policies, Network Policies, Service Profile Templates, etc. For such purpose we have made a Terraform provider. Visit Terraform's official website for more information on what exactly terraform is and how it works.

On a feature level, this will allow the user to:

Use Terraform to seamlessly deploy an arbitrary amount of Cisco machines into UCS at scale.
Specify predefined service profiles from Terraform.

Given a configuration file whose purpose is to create a new Service Profile in UCS, the way it all works is the terraform-provider-ucs talks to UCS, requesting to create a new Service Profile

This terraform provider will be enhanced and iterated upon when we understand further requirement from the DevNet community. One of the first suggested additions is using Cobbler to add the Operating System into the new created UCS Server so please provider feedback if you feel this is interesting to you.

How the Provider setup process works

Make bootstrap pulls down the terraform binaries, config .tf,
The terraform binary file (which is $GOPATH/bin directory) looks to the terraform-provider-ucs file (which you will compile in the setup process documented below) in order to interact with the specified resources UCSM API.
During this process the default make bootstrap task will download some of the dependencies including the actually terraform binaries, will test, clean any distribution file and build the required project files.
It is the make build process that actually build out the terraform-provider-ucs file and this file needs to be in the same folder as the terraform binary when executing the actual terraform commands.

How to compile and install

There are dependencies on the following to environments being setup prior to running the terraform provider creation process:

If you are not familiar with the folder structure for Go projects, check out this document. For Git information https://github.com/

Git

Make sure GIT is setup and working locally as this will be used during the setup process to clone files in different points in this setup process.

Running the Go setup process (Mac OS)

You will need to download Go(lang) onto the machine from where you will run the terraform setup process.

You can download it from here

Use the default setting during the install process for GOlang

Create the required directory structure

mkdir -p ~/Users/yourlocalusernamehere/go/src/github.com/CiscoUcs
mkdir -p ~/Users/yourlocalusernamehere/go/src/github.com/micdoher

Setting up the Environment Variables

export PATH=$PATH:/usr/local/go/bin
export GOPATH=/Users/yourlocalusernamehere/go
export PATH=$PATH:/Users/yourlocalusernamehere/go/bin
export  PATH=$PATH:/Users/yourlocalusernamehere/go

(putting this in the .bash_profile will probably be help!)

Clone the Git binaries

Clone the UCS-Terraform provider repo into /Users/yourlocalusernamehere/go/src/github.com/CiscoUcs/ via the following command: -

cd ~/Users/yourlocalusernamehere/go/src/github.com/CiscoUcs/
git clone https://github.com/CiscoUcs/UCS-Terraform.git

Clone the “go-utils” repo into /Users/yourlocalusernamehere/go/src/github.com/micdoher with the following command: -

cd ~/Users/yourlocalusernamehere/go/src/github.com/micdoher/
git clone https://github.com/micdoher/GoUtils.git

Compiling and dependency setup

After the terraform provider has been cloned, the resulting directory structure should look like the following: -

Now navigate to:

cd /Users/yourlocalusernamehere/go/src/github.com/CiscoUcs/UCS-Terraform

and run:

make bootstrap

An additional file should have been added called config.tf in the same folder.

Now you need to run the following command from the same directory:

make build

The output should return no errors.

Make a copy over a copy of the terraform-provider-ucs file into the same directory where the terraform binary lives (normally this is /Users/yourlocalusernamehere/go/bin)

Running Terraform

Make a copy of the config.tf file into the same directory where the terraform binary lives (normally this is /Users/yourlocalusernamehere/go/bin) and customise this to reflect your UCSM environment.

Customize the config.tf file to reflect your desired UCS state.

UCS provider parameters

ip_address the IP where the UCS manager service is running on.
username username used for authentication.
password password used for authentication.
log_filename default: stderr.
log_level default: 1.

log_level	Level amount
0	TRACE
1	DEBUG
2	INFO
3	WARN
4	ERROR
5	FATAL

Example

provider "ucs" {
  ip_address  = "1.2.3.4"
  username    = "john"
  password    = "supersecret"
  log_level    = 6
  log_filename = "terraform.log"
}

Service Profile

name the name of the Service Profile.
target_org the target organization of the Service Profile.
service_profile_template the Service Profile Template of the Service Profile.

Example

resource "ucs_service_profile" "master-server" {
  name                     = “terraserver1"
  target_org               = “root-org"
  service_profile_template = “terraformprofiletemplate"
  metadata { # This field is pretty much free style. Values must always be strings.
    role             = "master" # This is useful when creating a Mantl cluster
    ansible_ssh_user = "root"
    foo              = "bar"
  }
}

Make sure you have a pre-defined Service Profile Template available in UCSM for which you align the config.tf with

Once customised, run the following commands in the order given below:

terraform get

terraform plan

terraform apply

BTW, Terraform will default to the files in the directory from which it is run with .ft extensions

After the terraform plan you should see the something like following output:

After the terraform apply you should see the something like following output:

After terraform apply is run you will find 2 additional files in the /Users/yourlocalusernamehere/go/bin directory. You should you the xxxx.log file as the primary point of troubleshooting.

If you wish to delete the resources in UCSM you have just created you can run: -

terraform destroy

Additional Info for troubleshooting

Error Messages in Setup

The following error is when the “ucs-terraform-provider, provider file has not been compiled or made available to the terraform binary in /Users/yourlocalusernamehere/go/bin .

Error configuring: 1 error(s) occurred:

* unknown provider "ucs"

The following error means the directory structure is not setup correclty:

terraform-provider-ucs-master UCS-Terraform$ go build -o terraform-provider-ucs
resource_ucs_service_profile.go:8:2: cannot find package "github.com/CiscoUcs/UCS-Terraform/ipman" in any of:
    /usr/local/go/src/github.com/CiscoUcs/UCS-Terraform/ipman (from $GOROOT)
    /Users/yourname/terraform/terraform-provider-ucs-master/src/github.com/CiscoUcs/UCS-Terraform/ipman (from $GOPATH)
provider.go:4:2: cannot find package "github.com/CiscoUcs/UCS-Terraform/ucsclient" in any of:
    /usr/local/go/src/github.com/CiscoUcs/UCS-Terraform/ucsclient (from $GOROOT)
    /Users/yourname/terraform/terraform-provider-ucs-master/src/github.com/CiscoUcs/UCS-Terraform/ucsclient (from $GOPATH)

If you get the following error when running this from a Mac xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

Try Opening a Terminal, and run the following:

xcode-select --install

This will download and install xcode developer tools and fix the problem. The problem is that one needs to explicitly agree to the license agreement.