DOCSEARCHbyAlgolia
Submit Docs

govmomi

repository·main·Indexed 25 days ago

https://github.com/vmware/govmomi

A Go-based ecosystem for interacting with VMware vSphere (ESXi and vCenter Server) APIs. It consists of a core library, the govc CLI tool for managing VMware environments, and vcsim, a mock framework for testing. The project also includes govc.el, an Emacs interface for managing VMs, hosts, datastores, and pools.

Tokens
101.2K
Snippets
284
Records
639
Agent score
82%

What's inside govmomi

  1. Overview of govmomi components

    main

    The govmomi repository provides a suite of tools for interacting with VMware vSphere APIs (ESXi and/or vCenter Server):

    • govmomi: A Go library for interacting with vSphere APIs. The govmomi package acts as a convenience wrapper around code generated from the vSphere API description.
    • govc: A vSphere command-line interface (CLI).
    • vcsim: A vSphere API mock framework used for simulating vCenter and ESXi APIs.
    • toolbox: A VM guest tools framework.

  2. Overview of ESX Agent Manager (EAM)

    main
    ESX Agent Manager (EAM) is a long-lived service running on vCenter. It functions as an intermediary that manages the provisioning of agent virtual machines and VIB (vSphere Installation Bundle) modules on behalf of the user.

  3. Overview of the toolbox library

    main

    The toolbox library is a lightweight, extensible Go framework for implementing VMware guest tools functionality. It focuses on implementing VM guest RPC protocols, transport, and dispatch. While these protocols are largely undocumented, open-vm-tools serves as a reference implementation. The library provides default implementations for supported RPCs, which consumers can override or extend.

    Key Characteristics:

    • Target OS: Currently only supports Linux guests (Windows support is considered but untested).
    • vSphere Compatibility: Supported on vSphere 6.0 and 6.5, though it may function with older versions.
    • Extensibility: Provides hooks for authentication, file handling, and process management.

  4. Simulate Agent VMs using Docker

    main

    You can simulate the lifecycle of Agent VMs by using Docker containers instead of full virtual machines. To enable this, configure the AgentConfigInfo.OvfPackageUrl field with a value that meets the following criteria:

    1. It must be a non-empty string.
    2. It must not start with ./, /, or https?:.

    When these conditions are met, the EAM simulator treats the value as a Docker image name. The simulator will then set the RUN.container key to this value, instructing the core vC Simulator to run a container based on that image to represent the simulated VM.

  7. Understand vcsim generated inventory naming conventions

    main

    The names of generated objects follow a pattern: [Prefix][Instance].

    For example, a name like DC0_C1_RP0_VM6 breaks down as follows:

    • DC0: Datacenter instance 0 (-dc flag)
    • C1: ClusterComputeResource instance 1 (-cluster flag)
    • RP0: ResourcePool instance 0 (-pool flag)
    • VM6: VirtualMachine instance 6 (-vm flag)

    For VMs on standalone hosts (using -esx or -standalone-host), the name includes the host prefix instead of the cluster prefix:

    • DC0_H0_VM1: Datacenter 0, Host 0, VirtualMachine 1.

  8. Understand Content Library search performance and logic

    main

    The efficiency of the Content Library finder depends on whether you use absolute paths or wildcards, and the scale of your content library.

    Absolute Path Search Logic

    When searching for an exact path (no wildcards), the finder performs the following steps:

    1. Find library ID for library with name using server-side find API
    2. Get library with library ID
    3. Find item ID for item with name using server-side find API
    4. Get item with item ID

    This requires more round-trips (e.g., 4 round-trips for Public/Photon2) but is much more efficient for systems with a large number of content library objects.

    Wildcard Search Logic

    When using wildcards, the finder performs the following steps:

    1. Get all of the libraries and filter the pattern on the client-side
    2. Get all of the items for the library and filter the pattern on the client-side

    While this requires fewer round-trips (e.g., 2 round-trips for Public*/Photon2*), it involves dumping objects to the client, which is less efficient at scale.

  9. Understand JSON with Discriminators in govmomi

    main
    The vim25/json package is a modified version of Go's standard encoding/json package (specifically based on Go 1.17.13). It has been extended to support JSON discriminators, which allow for polymorphic JSON decoding by using a specific field to determine the underlying type of a JSON object.

  10. Create an ESXi VM with `create-esxi-vm.sh`

    main

    The create-esxi-vm.sh script creates a VM running stateless ESXi, booted via cdrom/iso. By default, it creates two unformatted disks (a vSAN cache disk/Virtual SSD and a vSAN store disk) intended to be autoclaimed by a vSAN cluster. Note that a vSAN cluster requires at least 3 of these VMs.

    Common Flags:

    • -s: Creates the ESXi VM for standalone use.
    • -d <size>: Sets the disk size (overrides default).
    • -m <size>: Sets the memory size.

    Usage Scenarios:

    • Standard vSAN ESXi VM: ./create-esxi-vm.sh -s -d 56 $GOVC_URL my-esxi-vm

    • Workstation (Local Ticket Auth): When the URL does not contain a username, govc uses local ticket authentication. The script still uses the provided password to set the root password in the ESX VM. GOVC_NETWORK=NAT ./create-esxi-vm.sh -d 16 -m 4 -s :password-for-esx60@localhost $USER-esxbox

    • Fusion: Use . as the hostname. ./create-esxi-vm.sh -d 16 -m 4 -s root:password-for-esx60@. $USER-esxbox

    ./create-esxi-vm.sh -s -d 56 $GOVC_URL my-esxi-vm

GOVC_NETWORK=NAT ./create-esxi-vm.sh -d 16 -m 4 -s :password-for-esx60@localhost $USER-esxbox

./create-esxi-vm.sh -d 16 -m 4 -s root:password-for-esx60@. $USER-esxbox

  11. Manage authorization roles with govc role commands

    main

    Manage vSphere authorization roles using role commands. You can create, list, update, or remove roles and their associated privileges.

    • Create: role.create [NAME] [PRIVILEGE...] creates a new role. Use -i to use a managed object reference (moref) instead of an inventory path.
    • List: role.ls [NAME] lists roles. If a name is provided, it lists the privileges for that specific role.
    • Update: role.update [NAME] [PRIVILEGE...] allows you to add (-a), remove (-r), or rename (-name) privileges within a role.
    • Remove: role.remove [NAME] deletes a role. Use -force to remove a role even if it is currently in use.
    • Usage: role.usage [NAME] shows where a role is being used.

  12. Access the devbox VM via SSH

    main

    Once the deployment is complete, you can access the VM using the insecure Vagrant private key.

    1. Add the key to your SSH agent: ssh-add ~/.vagrant.d/insecure_private_key
    2. SSH into the VM using the assigned IP address (e.g., 10.118.66.252).
    % ssh-add ~/.vagrant.d/insecure_private_key
% ssh vagrant@10.118.66.252