github.com/vmware/govmomi@v0.37.1/vcsim/README.md (about)

     1  # vcsim - A vCenter and ESXi API based simulator
     2  
     3  This package implements a vSphere Web Services (SOAP) SDK endpoint intended for
     4  testing consumers of the API.  While the mock framework is written in the Go
     5  language, it can be used by any language that can talk to the vSphere API.
     6  
     7  ## Installation
     8  
     9  ### Docker
    10  
    11  The official `vcsim` [Docker images](https://hub.docker.com/r/vmware/vcsim) are built from this [Dockerfile](../Dockerfile.vcsim).
    12  
    13  ### Binaries
    14  You can find prebuilt `vcsim` binaries on the [releases page](https://github.com/vmware/govmomi/releases).
    15  
    16  You can download and install a binary locally like this:
    17  
    18  ```bash
    19  # extract vcsim binary to /usr/local/bin
    20  # note: the "tar" command must run with root permissions
    21  curl -L -o - https://github.com/vmware/govmomi/releases/latest/download/vcsim_$(uname -s)_$(uname -m).tar.gz | tar -C /usr/local/bin -xvzf - vcsim
    22  ```
    23  
    24  ### Source
    25  
    26  #### Install via `go install`
    27  
    28  To build `vcsim` from source, first install the [Go
    29  toolchain](https://golang.org/dl/). You can then install the latest `vcsim` from
    30  Github using:
    31  
    32  ```bash
    33  go install github.com/vmware/govmomi/vcsim@latest
    34  $GOPATH/bin/vcsim -h
    35  ```
    36  
    37  **Note:** `govmomi` and its binaries use [Go
    38  modules](https://golang.org/ref/mod), i.e. explicitly setting `GOPATH` is not
    39  required anymore. To inject build variables (see details
    40  [below](#install-via-goreleaser)) used by `vcsim version`, `GOFLAGS` can be
    41  defined and are honored by `go get`.
    42  
    43  ⚠️ Make sure `$GOPATH/bin` is in your `PATH` to use the version installed from
    44  source.
    45  
    46  #### Install via `goreleaser`
    47  
    48  You can also build `vcsim` following our release process using `goreleaser`
    49  (requires [Go toolchain](https://golang.org/dl/)). This will ensure that build
    50  time variables are correctly injected. Build (linker) flags and injection are
    51  defined in [.goreleaser.yaml](./../.goreleaser.yml) and automatically set as
    52  `GOFLAGS` when building with `goreleaser`.
    53  
    54  Install `goreleaser` as per the installation
    55  [instructions](https://goreleaser.com/install/), then:
    56  
    57  ```bash
    58  git clone https://github.com/vmware/govmomi.git
    59  cd govmomi
    60  
    61  # pick a tag (>=v0.25.0)
    62  RELEASE=v0.25.0
    63  
    64  git checkout ${RELEASE}
    65  
    66  # build for the host OS/ARCH, otherwise omit --single-target
    67  # binaries are placed in respective subdirectories in ./dist/
    68  goreleaser build --clean --single-target
    69  ```
    70  
    71  ## Usage
    72  
    73  The **vcsim** program by default creates a *vCenter* model with a datacenter,
    74  hosts, cluster, resource pools, networks and a datastore.  The naming is similar
    75  to that of the original *vcsim* mode that was included with vCenter.  The number
    76  of resources can be increased or decreased using the various resource type
    77  flags.  Resources can also be created and removed using the API. In fact, vcsim
    78  itself uses the vSphere API generate its inventory.
    79  
    80  ```console
    81  $ vcsim -h # pruned to model type flags used in the Examples section
    82  Usage of vcsim:
    83    -E string
    84          Output vcsim variables to the given fifo or stdout (default "-")
    85    -api-version string
    86          API version (default "6.5")
    87    -app int
    88          Number of virtual apps per compute resource
    89    -autostart
    90          Autostart model created VMs (default true)
    91    -cluster int
    92          Number of clusters (default 1)
    93    -dc int
    94          Number of datacenters (default 1)
    95    -delay int
    96          Method response delay across all methods
    97    -delay-jitter float
    98          Delay jitter coefficient of variation (tip: 0.5 is a good starting value)
    99    -ds int
   100          Number of local datastores (default 1)
   101    -esx
   102          Simulate standalone ESX
   103    -folder int
   104          Number of folders
   105    -host int
   106          Number of hosts per cluster (default 3)
   107    -l string
   108          Listen address for vcsim (default "127.0.0.1:8989")
   109    -load string
   110          Load model from directory
   111    -method-delay string
   112          Delay per method on the form 'method1:delay1,method2:delay2...'
   113    -nsx int
   114          Number of NSX backed opaque networks
   115    -password string
   116          Login password for vcsim (any password allowed by default)
   117    -pg int
   118          Number of port groups (default 1)
   119    -pg-nsx int
   120          Number of NSX backed port groups
   121    -pod int
   122          Number of storage pods per datacenter
   123    -pool int
   124          Number of resource pools per compute resource
   125    -standalone-host int
   126          Number of standalone hosts (default 1)
   127    -stdinexit
   128          Press any key to exit
   129    -tls
   130          Enable TLS (default true)
   131    -tlscert string
   132          Path to TLS certificate file
   133    -tlskey string
   134          Path to TLS key file
   135    -trace
   136          Trace SOAP to -trace-file
   137    -trace-file string
   138          Trace output file (defaults to stderr)
   139    -tunnel int
   140          SDK tunnel port (default -1)
   141    -username string
   142          Login username for vcsim (any username allowed by default)
   143    -vm int
   144          Number of virtual machines per resource pool (default 2)
   145  ```
   146  
   147  [model]:https://godoc.org/github.com/vmware/govmomi/simulator#Model
   148  
   149  ### Version Information
   150  
   151  To print detailed (build) information for vcsim run: `vcsim version`.
   152  
   153  ## Examples
   154  
   155  The following examples illustrate how **vcsim** flags can be used to change the
   156  generated inventory.  Each example assumes **GOVC_URL** is set to vcsim's default
   157  [listen address](#listen-address):
   158  
   159  ```bash
   160  export GOVC_URL=https://user:pass@127.0.0.1:8989
   161  ```
   162  
   163  ### Default vCenter inventory
   164  
   165  ```console
   166  $ $GOPATH/bin/vcsim
   167  
   168  $ govc find -l
   169  Folder                       /
   170  Datacenter                   /DC0
   171  Folder                       /DC0/vm
   172  VirtualMachine               /DC0/vm/DC0_H0_VM0
   173  VirtualMachine               /DC0/vm/DC0_H0_VM1
   174  VirtualMachine               /DC0/vm/DC0_C0_RP0_VM0
   175  VirtualMachine               /DC0/vm/DC0_C0_RP0_VM1
   176  Folder                       /DC0/host
   177  ComputeResource              /DC0/host/DC0_H0
   178  HostSystem                   /DC0/host/DC0_H0/DC0_H0
   179  ResourcePool                 /DC0/host/DC0_H0/Resources
   180  ClusterComputeResource       /DC0/host/DC0_C0
   181  HostSystem                   /DC0/host/DC0_C0/DC0_C0_H0
   182  HostSystem                   /DC0/host/DC0_C0/DC0_C0_H1
   183  HostSystem                   /DC0/host/DC0_C0/DC0_C0_H2
   184  ResourcePool                 /DC0/host/DC0_C0/Resources
   185  Folder                       /DC0/datastore
   186  Datastore                    /DC0/datastore/LocalDS_0
   187  Folder                       /DC0/network
   188  Network                      /DC0/network/VM Network
   189  DistributedVirtualSwitch     /DC0/network/DVS0
   190  DistributedVirtualPortgroup  /DC0/network/DVS0-DVUplinks-9
   191  DistributedVirtualPortgroup  /DC0/network/DC0_DVPG0
   192  ```
   193  
   194  ### Default standalone ESX inventory
   195  
   196  With the `-esx` flag, vcsim behaves as a standalone ESX host without any vCenter
   197  specific features.
   198  
   199  ```console
   200  $ $GOPATH/vcsim -esx
   201  
   202  $ govc find
   203  /
   204  /ha-datacenter
   205  /ha-datacenter/vm
   206  /ha-datacenter/vm/ha-host_VM0
   207  /ha-datacenter/vm/ha-host_VM1
   208  /ha-datacenter/host
   209  /ha-datacenter/host/localhost.localdomain
   210  /ha-datacenter/host/localhost.localdomain/localhost.localdomain
   211  /ha-datacenter/host/localhost.localdomain/Resources
   212  /ha-datacenter/datastore
   213  /ha-datacenter/datastore/LocalDS_0
   214  /ha-datacenter/network
   215  /ha-datacenter/network/VM Network
   216  ```
   217  
   218  ### Customizing inventory
   219  
   220  Model flags can be specified to increase or decrease the generated inventory.
   221  
   222  ```console
   223  $ vcsim -dc 2 -folder 1 -ds 4 -pod 1 -nsx 2 -pool 2 -app 1
   224  
   225  $ govc find -l
   226  Folder                       /
   227  Datacenter                   /DC0
   228  Folder                       /DC0/vm
   229  VirtualMachine               /DC0/vm/DC0_H0_VM0
   230  VirtualMachine               /DC0/vm/DC0_H0_VM1
   231  VirtualMachine               /DC0/vm/DC0_C0_RP0_VM0
   232  VirtualMachine               /DC0/vm/DC0_C0_RP0_VM1
   233  VirtualMachine               /DC0/vm/DC0_C0_APP0_VM0
   234  VirtualMachine               /DC0/vm/DC0_C0_APP0_VM1
   235  Folder                       /DC0/host
   236  ComputeResource              /DC0/host/DC0_H0
   237  HostSystem                   /DC0/host/DC0_H0/DC0_H0
   238  ResourcePool                 /DC0/host/DC0_H0/Resources
   239  ClusterComputeResource       /DC0/host/DC0_C0
   240  HostSystem                   /DC0/host/DC0_C0/DC0_C0_H0
   241  HostSystem                   /DC0/host/DC0_C0/DC0_C0_H1
   242  HostSystem                   /DC0/host/DC0_C0/DC0_C0_H2
   243  ResourcePool                 /DC0/host/DC0_C0/Resources
   244  ResourcePool                 /DC0/host/DC0_C0/Resources/DC0_C0_RP1
   245  ResourcePool                 /DC0/host/DC0_C0/Resources/DC0_C0_RP2
   246  VirtualApp                   /DC0/host/DC0_C0/Resources/DC0_C0_APP0
   247  Folder                       /DC0/datastore
   248  StoragePod                   /DC0/datastore/DC0_POD0
   249  Datastore                    /DC0/datastore/LocalDS_0
   250  Datastore                    /DC0/datastore/LocalDS_1
   251  Datastore                    /DC0/datastore/LocalDS_2
   252  Datastore                    /DC0/datastore/LocalDS_3
   253  Folder                       /DC0/network
   254  Network                      /DC0/network/VM Network
   255  DistributedVirtualSwitch     /DC0/network/DVS0
   256  DistributedVirtualPortgroup  /DC0/network/DVS0-DVUplinks-10
   257  DistributedVirtualPortgroup  /DC0/network/DC0_DVPG0
   258  OpaqueNetwork                /DC0/network/DC0_NSX0
   259  OpaqueNetwork                /DC0/network/DC0_NSX1
   260  Folder                       /F0
   261  Datacenter                   /F0/DC1
   262  Folder                       /F0/DC1/vm
   263  Folder                       /F0/DC1/vm/F0
   264  VirtualMachine               /F0/DC1/vm/F0/DC1_H0_VM0
   265  VirtualMachine               /F0/DC1/vm/F0/DC1_H0_VM1
   266  VirtualMachine               /F0/DC1/vm/F0/DC1_C0_RP0_VM0
   267  VirtualMachine               /F0/DC1/vm/F0/DC1_C0_RP0_VM1
   268  VirtualMachine               /F0/DC1/vm/F0/DC1_C0_APP0_VM0
   269  VirtualMachine               /F0/DC1/vm/F0/DC1_C0_APP0_VM1
   270  Folder                       /F0/DC1/host
   271  Folder                       /F0/DC1/host/F0
   272  ComputeResource              /F0/DC1/host/F0/DC1_H0
   273  HostSystem                   /F0/DC1/host/F0/DC1_H0/DC1_H0
   274  ResourcePool                 /F0/DC1/host/F0/DC1_H0/Resources
   275  ClusterComputeResource       /F0/DC1/host/F0/DC1_C0
   276  HostSystem                   /F0/DC1/host/F0/DC1_C0/DC1_C0_H0
   277  HostSystem                   /F0/DC1/host/F0/DC1_C0/DC1_C0_H1
   278  HostSystem                   /F0/DC1/host/F0/DC1_C0/DC1_C0_H2
   279  ResourcePool                 /F0/DC1/host/F0/DC1_C0/Resources
   280  ResourcePool                 /F0/DC1/host/F0/DC1_C0/Resources/DC1_C0_RP1
   281  ResourcePool                 /F0/DC1/host/F0/DC1_C0/Resources/DC1_C0_RP2
   282  VirtualApp                   /F0/DC1/host/F0/DC1_C0/Resources/DC1_C0_APP0
   283  Folder                       /F0/DC1/datastore
   284  StoragePod                   /F0/DC1/datastore/DC1_POD0
   285  Folder                       /F0/DC1/datastore/F0
   286  Datastore                    /F0/DC1/datastore/F0/LocalDS_0
   287  Datastore                    /F0/DC1/datastore/F0/LocalDS_1
   288  Datastore                    /F0/DC1/datastore/F0/LocalDS_2
   289  Datastore                    /F0/DC1/datastore/F0/LocalDS_3
   290  Folder                       /F0/DC1/network
   291  Network                      /F0/DC1/network/VM Network
   292  Folder                       /F0/DC1/network/F0
   293  DistributedVirtualSwitch     /F0/DC1/network/F0/DVS0
   294  DistributedVirtualPortgroup  /F0/DC1/network/F0/DVS0-DVUplinks-69
   295  DistributedVirtualPortgroup  /F0/DC1/network/F0/DC1_DVPG0
   296  OpaqueNetwork                /F0/DC1/network/F0/DC1_NSX0
   297  OpaqueNetwork                /F0/DC1/network/F0/DC1_NSX1
   298  ```
   299  
   300  Create yourself a Datastore cluster:
   301  
   302  ```console
   303  $ govc object.mv /F0/DC0/datastore/F0/LocalDS_[123] /DC1/datastore/DC0_POD0
   304  
   305  $ govc find -l /DC0/datastore
   306  Folder      /DC0/datastore
   307  StoragePod  /DC0/datastore/DC0_POD0
   308  Datastore   /DC0/datastore/LocalDS_0
   309  Datastore   /DC0/datastore/DC0_POD0/LocalDS_1
   310  Datastore   /DC0/datastore/DC0_POD0/LocalDS_2
   311  Datastore   /DC0/datastore/DC0_POD0/LocalDS_3
   312  ```
   313  
   314  ### Starting with empty inventory
   315  
   316  The model flags when set to 0 can be used to turn off generation of any type.
   317  With **Datacenter** generation turned off, the inventory will be empty:
   318  
   319  ```console
   320  $ $GOPATH/vcsim -dc 0
   321  $ govc find
   322  /
   323  ```
   324  
   325  You can create your own inventory using the API or govc:
   326  
   327  ```console
   328  $ govc datacenter.create godc
   329  
   330  $ govc cluster.create gocluster
   331  
   332  $ govc cluster.add -hostname gohost1 -username user -password pass -noverify
   333  
   334  $ govc datastore.create -type local -name gostore -path /tmp gocluster/*
   335  
   336  $ govc vm.create -ds gostore -cluster gocluster govm1
   337  
   338  $ govc find -l
   339  Folder                  /
   340  Datacenter              /godc
   341  Folder                  /godc/vm
   342  VirtualMachine          /godc/vm/govm1
   343  Folder                  /godc/host
   344  ClusterComputeResource  /godc/host/gocluster
   345  HostSystem              /godc/host/gocluster/gohost1
   346  ResourcePool            /godc/host/gocluster/Resources
   347  Folder                  /godc/datastore
   348  Datastore               /godc/datastore/gostore
   349  Folder                  /godc/network
   350  Network                 /godc/network/VM Network
   351  ```
   352  
   353  ## Generated inventory names
   354  
   355  The generated names include a prefix per-type and integer suffix per-instance.
   356  See the [simulator.Model][model] documentation for a complete list of type prefixes.
   357  For example, the name **DC0_C1_RP0_VM6** is composed of:
   358  
   359  | Prefix | Instance | Type                   | Flag     |
   360  |--------|----------|------------------------|----------|
   361  | DC     | 0        | Datacenter             | -dc      |
   362  | C      | 1        | ClusterComputeResource | -cluster |
   363  | RP     | 0        | ResourcePool           | -pool    |
   364  | VM     | 6        | VirtualMachine         | -vm      |
   365  
   366  VMs with Clusters include the ResourcePool in their name, while VMs in standalone
   367  hosts include the host name instead.
   368  For example, the name **DC0_H0_VM1** is composed of:
   369  
   370  | Prefix | Instance | Type           | Flag             |
   371  |--------|----------|----------------|------------------|
   372  | DC     | 0        | Datacenter     | -dc              |
   373  | H      | 0        | HostSystem     | -standalone-host |
   374  | VM     | 1        | VirtualMachine | -vm              |
   375  
   376  ## Supported methods
   377  
   378  The simulator supports a subset of API methods.  However, the generated govmomi
   379  code includes all types and methods defined in the vmodl, which can be used to
   380  implement any method documented in the [VMware vSphere API Reference][apiref].
   381  
   382  To see the list of supported methods:
   383  
   384  ```bash
   385  curl -sk https://user:pass@127.0.0.1:8989/about
   386  ```
   387  
   388  [apiref]:https://code.vmware.com/apis/196/vsphere
   389  
   390  ## Listen address
   391  
   392  The default vcsim listen address is `127.0.0.1:8989`.  Use the `-l` flag to
   393  listen on another address:
   394  
   395  ```bash
   396  vcsim -l 10.118.69.224:8989 # specific address
   397  
   398  vcsim -l :8989 # any address
   399  ```
   400  
   401  When given a port value of `0`, an unused port will be chosen.  You can then
   402  source the GOVC_URL from another process, for example:
   403  
   404  ```bash
   405  govc_sim_env=$TMPDIR/vcsim-$(uuidgen)
   406  
   407  mkfifo $govc_sim_env
   408  
   409  vcsim -l 127.0.0.1:0 -E $govc_sim_env &
   410  
   411  eval "$(cat $govc_sim_env)"
   412  
   413  # ... run tests ...
   414  
   415  kill $GOVC_SIM_PID
   416  rm -f $govc_sim_env
   417  ```
   418  
   419  Tests written in Go can also use the [simulator package](https://godoc.org/github.com/vmware/govmomi/simulator)
   420  directly, rather than the vcsim binary.
   421  
   422  ## Feature Details
   423  
   424  For more details on vcsim features, see the project [wiki](https://github.com/vmware/govmomi/wiki/vcsim-features).
   425  
   426  ## Projects using vcsim
   427  
   428  * [VMware VIC Engine](https://github.com/vmware/vic)
   429  
   430  * [Kubernetes](https://github.com/kubernetes/kubernetes/tree/master/pkg/cloudprovider/providers/vsphere)
   431  
   432  * [Ansible](https://github.com/ansible/vcenter-test-container)
   433  
   434  * [Telegraf](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/vsphere)
   435  
   436  ## Blog posts
   437  
   438  * [Beginning vCenter Server simulation with vcsim](https://opensourceforu.com/2017/10/vcenter-server-simulation-govcsim/) by Abhijeet Kasurde
   439  
   440  * [vCenter & ESXi API based simulator](https://www.virtuallyghetto.com/2017/04/govcsim-neat-incubation-project-vcenter-server-esxi-api-based-simulator.html) by William Lam
   441  
   442  * [vCenter Simulator Docker Container](https://www.brianbunke.com/blog/2018/12/31/vcenter-simulator-ci/) by Brian Bunke
   443  
   444  * [Using govc with vcsim in Kubernetes](https://www.mgasch.com/2021/05/vcsim-k8s/) by Michael Gasch
   445  
   446  ## Related projects
   447  
   448  * [LocalStack](https://github.com/localstack/localstack/blob/master/README.md#why-localstack)
   449  
   450  ## License
   451  
   452  vcsim is available under the [Apache 2 license](../LICENSE).
   453  
   454  ## Name
   455  
   456  Pronounced "v-c-sim", short for "vCenter Simulator"