== Introduction ==
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 ...
https://github.com/vmware/govmomi/tree/master/vcsim
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 github.com/vmware/govmomi/vcsim
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@127.0.0.1:8989/sdk GOVC_SIM_PID=9596Take 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 github.com/vmware/govmomi/govc
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=127.0.0.1:8989 export GOVC_USERNAME=user export GOVC_PASSWORD=pass export GOVC_INSECURE=1Now 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 / /DC0 /DC0/vm /DC0/vm/DC0_H0_VM0 /DC0/vm/DC0_H0_VM1 /DC0/vm/DC0_H0_VM2 /DC0/vm/DC0_H0_VM3 /DC0/vm/DC0_H0_VM4 /DC0/vm/DC0_H0_VM5 /DC0/vm/DC0_H0_VM6You 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
vm.info
command. With it, you can get summary details about a virtualmachine.
$ ~/go/bin/govc vm.info 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.py ===
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 dnf -y install python-pip pip install --user argparse pip install --user pyvmomiNow we're ready to download the script.
wget https://raw.githubusercontent.com/jctanner/ansible-tools/master/vmware/vmware_walk.py chmod +x vmware_walk.pyNow to run the script.
$ ./vmware_walk.py --hostname=127.0.0.1:8989 --username=user --password=pass | head /[ServiceInstanceContent]Content /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters/['vim.Datacenter:datacenter-2']DC0 /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters/['vim.Datacenter:datacenter-2']DC0/['vim.Datastore:/tmp/govcsim-927507344@folder-5']LocalDS_0 /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters/['vim.Datacenter:datacenter-2']DC0/['vim.Datastore:/tmp/govcsim-927507344@folder-5']LocalDS_0/['vim.VirtualMachine:vm-61']DC0_H0_VM0 /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters/['vim.Datacenter:datacenter-2']DC0/['vim.Datastore:/tmp/govcsim-927507344@folder-5']LocalDS_0/['vim.VirtualMachine:vm-66']DC0_H0_VM1 /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters/['vim.Datacenter:datacenter-2']DC0/['vim.Datastore:/tmp/govcsim-927507344@folder-5']LocalDS_0/['vim.VirtualMachine:vm-71']DC0_H0_VM2 /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters/['vim.Datacenter:datacenter-2']DC0/['vim.Datastore:/tmp/govcsim-927507344@folder-5']LocalDS_0/['vim.VirtualMachine:vm-76']DC0_H0_VM3 /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters/['vim.Datacenter:datacenter-2']DC0/['vim.Datastore:/tmp/govcsim-927507344@folder-5']LocalDS_0/['vim.VirtualMachine:vm-81']DC0_H0_VM4 /[ServiceInstanceContent]Content/['vim.Folder:group-d1']Datacenters/['vim.Datacenter:datacenter-2']DC0/['vim.Datastore:/tmp/govcsim-927507344@folder-5']LocalDS_0/['vim.VirtualMachine:vm-86']DC0_H0_VM5Wow, 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-simulatorNow start it up.
$ docker run -i ansible/ansible:vcenter-simulator * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)To understand what just happened, let take a look at the various layers involved.
host - 127.0.0.1 container - x.x.x.x flask - x.x.x.x:5000 vcsim - x.x.x.x:443The container has a unique IP and we'll fetch that with
docker inspect
.
$ docker inspect c0d9cacd10fb | fgrep '"IPAddress"' | head -n1 | tr -d ' ' "IPAddress":"172.17.0.2",In the previous layout example,
172.17.0.2
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 'http://172.17.0.2:5000' ; echo '' vcsim controllerInteresting, but not useful. So let's have it do something useful like spawn vcsim.
$ curl 'http://172.17.0.2:5000/spawn' ; echo '' { "GOVC_URL": "https://user:pass@172.17.0.2:443", "cmd": "/opt/gocode/bin/vcsim -httptest.serve 172.17.0.2:443 -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": "172.17.0.2", "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=172.17.0.2 $ export GOVC_USERNAME=user $ export GOVC_PASSWORD=pass $ export GOVC_INSECURE=1 $ ~/go/bin/govc find | head / /F0 /F0/DC0 /F0/DC0/vm /F0/DC0/vm/F0 /F0/DC0/vm/F0/DC0_H0_VM0 /F0/DC0/vm/F0/DC0_H0_VM1 /F0/DC0/host /F0/DC0/host/F0 /F0/DC0/host/F0/DC0_H0There'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 == * https://github.com/ansible/community/wiki/VMware * https://github.com/ansible/community/wiki/VMware:-govcsim * https://github.com/ansible/ansible/blob/devel/test/utils/docker/vcenter-simulator/flask_control.py [[Category:VMware]]