Ansible VMware Filament

From tannerjc wiki
Jump to: navigation, search


This document is geared towards Ansible developers and users who are debugging or testing VMware.

level 1

golang basics

Most of the tools we are going to use in this section are written in golang, so you will need the golang package installed on your test machine.

dnf -y install golang

Go has a builtin package manager which is called via "go get". With more recent versions of golang, the packages will install into $HOME/go.

vcsim basics

What is "vcsim" you ask? Well if you've ever worked with vmware, you know it takes a lot of hardware, time and money to set up vcenter. It's neither economical or efficient to setup vcenter for simple testing or debugging. vcsim is a mock of the vcenter SOAP API. It's not 100% complete, but it's getting closer every day thanks to upstream submissions which you can look at here ...

It's incredibly lightweight and versatile because it's been designed as a test harness for VMware's golang based client library govmomi. Since it's mocking the SOAP api, it's also useful to ANY other client such as the Ansible VMware modules written with python and pyvmomi.

We'll begin the vcsim journey by using the go get command to install vcsim.

go get -u

Since the go package installdir $HOME/go is not part of a user's path by default, we're going to launch vcsim from it's absolute path: $HOME/go/bin/vcsim

$ ~/go/bin/vcsim -dc 1 -ds 1 -cluster 1 -host 3 -vm 20 -trace
export GOVC_URL=https://user:pass@ GOVC_SIM_PID=9596

Take a closer look at the arguments that were passed to vcsim. We've told it to make 1 datacenter, 1 cluster, 3 hosts per cluster, 20 vms per resourcepool and to show all the XML data that is sent and received (-trace). If you have a different topology you are trying to emulate, take a look at the vcsim -h output and adjust the arguments accordingly.

That's all there is to know about vcsim. It does not have a GUI, but it's a mostly function version of the vmware soap API that Ansible users are going to be familiar with.

govc basics

Govc is an invaluable cli tool to operate against a vcenter API. It connects to and utilizes the same vcenter SOAP api that all of the ansible modules and inventory scripts utilize. We'll use it in this section to query our newly running vcsim instance.

First, install govc in the same way you installed vcsim.

go get -u

Before govc can connect to a vcenter, it needs to know where the vcenter is and what credentials to use. Take a look back at your console where vcsim was started. You should notice something like export GOVC_URL=.... We aren't going to use that exactly as output, but instead are going to chop it out into separate exports.

export GOVC_URL=
export GOVC_USERNAME=user
export GOVC_PASSWORD=pass

Now we want to use govc to inspect our simulator's content. The subcommand you'll use for this is find.

$ ~/go/bin/govc find | head

You should see 58 lines of output and 40 of them should have something like "_VM" in the path. Those are the virtual machines. Half of them are bound to the cluster "C0". If you hadn't figured it out already, vcsim names things in a numerical way based on the type of object it is. "D" is a datacenter, "C" is a cluster, "R" is a resource pool.

One more subcommand we should learn about govc is the command. With it, you can get summary details about a virtualmachine.

$ ~/go/bin/govc DC0_H0_VM0
Name:           DC0_H0_VM0
  Path:         /DC0/vm/DC0_H0_VM0
  UUID:         436e916d-9c46-45fa-9937-3709840f8e5e
  Guest name:   otherGuest
  Memory:       32MB
  CPU:          1 vCPU(s)
  Power state:  poweredOn
  Boot time:    2017-11-07 17:29:11.466793518 -0500 EST
  IP address:
  Host:         DC0_H0

level 2

introduction to

vmware_walk is not an industry term or a project that you would have heard about anywhere other than in a select few ansible issues. It's a tool that "walks" through the vcenter SOAP api and lists whatever it finds. We can use this data to understand the topology of any vcenter environment (and there are lots of different topologies out there!).

To use the script, you'll first need to install the prerequisite pyvmomi python package that the Ansible modules also use and <argparse>.

dnf -y install python-pip
pip install --user argparse
pip install --user pyvmomi

Now we're ready to download the script.

chmod +x

Now to run the script.

$ ./ --hostname= --username=user --password=pass | head

Wow, that's a lot of junk right? Wrong! =P

What you are seeing is an identical list of paths to what govc gave you, but with more context. The data inside [] is the object type and "managed object ID" or "moid" for short. Everything after the [] and before the next / is the value of ".name" for that object. Each line is a hierarchy, where every segment links back to the previous. So LocalDS_0 for example is a datastore linked to the datacenter DC0.

Why is any of that useful? Well because the hierarchy of objects in the API is a crucial piece of how you find things (such as VM template) and how you know what other objects to using during operations (such as the correct esxi host for cloning vms).

level 3

the ansible/ansible:vcenter-simulator container

Installing govc and vcsim and starting it up is a lot of fun right? Not really. That's why we make use of a prebuilt docker container in the Ansible integration tests to help out on all that "fun".

First, pull the image

$ docker pull ansible/ansible:vcenter-simulator
vcenter-simulator: Pulling from ansible/ansible
00ddb097f3f5: Already exists
ff5e2b4fde44: Pull complete
a2823438b701: Pull complete
1ea7e27628ac: Pull complete
8bf2de6e4e6c: Pull complete
d6f37a9e7bc6: Pull complete
b666ba033b3f: Pull complete
9712cb7ebb1f: Pull complete
0a3e9d6160ff: Pull complete
a93775324cbe: Pull complete
Digest: sha256:7b7cd213219dc09ae528a8e226804e662c2fae0c1d7d7e2ee3aa9e9c08d4059a
Status: Downloaded newer image for ansible/ansible:vcenter-simulator

Now start it up.

$ docker run -i ansible/ansible:vcenter-simulator
 * Running on (Press CTRL+C to quit)

To understand what just happened, let take a look at the various layers involved.

host -
    container - x.x.x.x
        flask - x.x.x.x:5000
        vcsim - x.x.x.x:443

The container has a unique IP and we'll fetch that with docker inspect.

$ docker inspect c0d9cacd10fb | fgrep '"IPAddress"' | head -n1 | tr -d ' '

In the previous layout example, is the value for x.x.x.x.

The container's primary entry point is a flask webserver listening on port 5000. You can connect to this service with any http client such as curl or python at the http://x.x.x.x:5000 url.

For demonstration purposes, let's try having it tell us what it is ...

$ curl '' ; echo ''
vcsim controller

Interesting, but not useful. So let's have it do something useful like spawn vcsim.

$ curl '' ; echo ''
  "GOVC_URL": "https://user:pass@",
  "cmd": "/opt/gocode/bin/vcsim -httptest.serve -app=0 -cluster=0 -dc=1 -ds=1 -folder=1 -host=3 -pg=1 -pod=1 -pool=1 -vm=2 > vcsim.log 2>&1",
  "host": "",
  "password": "pass",
  "pid": 8,
  "port": 443,
  "username": "user"

If you paid attention the vcsim section of this doc, you would recognize that GOVC_URL variable. Let's see if we can use that data for govc.

$ export GOVC_URL=
$ export GOVC_USERNAME=user
$ export GOVC_PASSWORD=pass
$ export GOVC_INSECURE=1
$ ~/go/bin/govc find | head

There's more bells and whistles to the container, but you'll have to look at the source url in Ansible_VMware_Filament#futher reading or ask someone to walk you through it.

further reading