Connect vSphere tools

What you build

You turn on the vSphere endpoints of the controller, point govc at them and list the inventory with a tool that was written for the vSphere API. The same steps apply to other tools: they need the same address, user name and password.

Before you start

• A running controller and a user name with a password. The vSphere sign-in takes a user name and a password and has no step for a verification code, so use a user that does not need one.
• Root access on the controller to edit its configuration.
• govc, the command-line tool of the Go vSphere library, on your machine.

1. Turn on the endpoints

The endpoints are off by default. In /etc/kyvernon/controller.toml add the section:

[facades]
enabled = true
session_timeout = "30m"

session_timeout is the idle time after which a tool session ends; 30 minutes is the default. Check the file and restart the controller:

sudo kyvernon-controller --config /etc/kyvernon/controller.toml check-config
sudo systemctl restart kyvernon-controller.service

The SOAP endpoint is now at https://<controller>:8443/sdk. The REST endpoints are at /api and /rest on the same address, next to the native API under /v1.

When clients reach the controller through a reverse proxy, two more keys of the same section matter: public_host names the host and port that the endpoints put in the addresses they return, and trust_certificate_file names the certificate they publish for clients that pin it.

2. Set the environment of govc

export GOVC_URL=https://controller.example.com:8443/sdk
export GOVC_USERNAME=<user>
export GOVC_PASSWORD=<password>
export GOVC_INSECURE=1

GOVC_INSECURE=1 skips the check of the TLS certificate. Use it only while the controller has its bootstrap certificate, and only on a network you control. Remove it when the controller has a certificate that your machine trusts.

3. Check the connection

govc about
govc ls

govc about prints the product name and the API version that the endpoint reports. govc ls lists the top of the inventory, which starts with your datacenters.

4. List the inventory

govc datastore.info
govc host.info
govc vm.info <name>
govc datastore.ls

Each command prints the objects that Kyvernon holds, with the names you see in the web console. The tools see the inventory with the permissions of the user that signed in: an object the user may not read is not listed.

5. Change something

govc vm.power -on <name>
govc vm.info <name>

The power-on is an ordinary task. Open the tasks pane of the web console, or run kyvernon tasks list --target <id>, and the task appears with the user that started it.

Result

A tool written for the vSphere API reads and changes the inventory of the controller. Which tools and which operations were verified, and which methods of the vSphere API the endpoint serves, is listed in the generated reference.

Next steps

• Supported methods lists the served methods of the vSphere API by managed object.
• Verified tools lists the tools and operations that were run against the endpoints.
• First CLI session installs the Kyvernon command-line client.