# GOVC 安裝及基礎測試

###### tags: `govc` `vmware` `api`
[toc]

**govc** 是一個基於 **govmomi（vSphere SDK for Go）** 構建的 **vSphere CLI**。
> 發音為 **"go-v-c"**，是 **"Go(lang) vCenter CLI"** 的縮寫。

## 什麼是 govc

根據 **Wiliiam Lam** 的 Blog：為了要讓 vSphere 環境能夠輕易地與 **Kubernetes** 進行整合，需要為 **vSphere API** 編一個 Go 函式庫，因此 **govmomi** 誕生了！這就跟 **Python 的 pyvmomi** 類似，**govmomi** 就是 Go 的 vSphere SDK
。 govmomi 項目是由 VMware 領導的開源項目，可以在 [[Github 儲存庫]](https://github.com/vmware/govmomi)上找到相關資料。

**govc** 目的成為使用者親和界面 GUI 的替代方案，非常**適合自動化任務**。 還可作為 govmomi API 的測試工具，並提供有關如何使用 API 的工作範例。

**govmomi** 是一個用於與 VMware vSphere API（ESXi 和 vCenter）互動的 **Golang 函式庫**。 它是使用 **VMware vSphere SDK** 所構建的。 它是使用 **Go 語言**編寫的，並針對 Linux、OSX 和 Windows 進行了預先編譯(pre-compiled)。 **GOVC vSphere CLI 對於從命令行執行各種 vCenter/vSphere 操作非常有用**。

## 安裝 govc

**govc** 在 [github](https://github.com/vmware/govmomi/tree/master/govc) 官方說明頁面中提供 **Docker** [[Docker Hub]](https://hub.docker.com/r/vmware/govc) 及 **預先編譯執行檔** 兩種方式可以安裝及使用。

**govc** 目前最新版本為 **0.26.0(2021-06-03)**，在[釋出版本網頁](https://github.com/vmware/govmomi/releases)中提供多個平台預先編譯的程式下載使用，也提供原始碼可自行編譯使用。

### Docker 映像檔

直接將映像檔下載即可。當然，環境中必須要有 Container/Docker。

  docker pull vmware/vcsim:v0.26.0
  docker pull vmware/vcsim:34586b66
  docker pull vmware/vcsim:latest
  docker pull vmware/govc:v0.26.0
  docker pull vmware/govc:34586b66
  docker pull vmware/govc:latest

### 預先編譯

將官方提供預先編譯好的執行檔下載後，解壓至 **`/usr/local/bin`** 目錄即可。

  # extract govc binary to /usr/local/bin
  # note: the "tar" command must run with root permissions
  curl -L -o - "https://github.com/vmware/govmomi/releases/latest/download/govc_$(uname -s)_$(uname -m).tar.gz" | tar -C /usr/local/bin -xvzf - govc

> **getGoVC.sh**

  #!/bin/bash

  govcUrl='https://github.com/vmware/govmomi/releases/latest/download'
  govcFile="govc_$(uname -s)_$(uname -m)"

  which govc &>/dev/null
  if [ $? -ne 0 ]; then
    echo "> Download govc from gitgub"
    wget ${govcUrl}/${govcFile}.tar.gz
    echo "> Install govc to /usr/local/bin"
    sudo tar -C /usr/local/bin -zxvf ${govcFile}.tar.gz govc
  else
    echo "govc already exists..."
  fi

### 套件管理
這裡採用更簡便的方式來取得 **govc** 的使用，因為使用的作業系統為 **Fedora Linux**，就從套件管理員找找是否有提供相關套件來進行安裝。**缺點就是版本不會最新！**

使用 `dnf search govmomi` 查詢 `govmomi` 相關套件，發現以下兩個套件。

- **golang-github-vmware-govmomi.x86_64** : Go library for the VMware vSphere API
- **golang-github-vmware-govmomi-devel.noarch** : Go library for the VMware vSphere API

直接安裝 **golang-github-vmware-govmomi** 套件。

  sudo dnf install -y golang-github-vmware-govmomi

OK！安裝成功，輸入 `govc version` 確認目前使用版本。目前套件庫提供的版本為 **0.24.0**

## 使用 govc

要使用 govc 連線 vCenter Server 取得相關資訊，跟使用 Web Client 一樣，需要提供連線的資訊。

### 配置 vCenter 環境
使用 `govc` 前需要配置連接的 vCenter/vSphere 環境，至少定義以下基本環境變數。變數可以加入 **~/.bashrc** 或相關的設定檔中。

  export GOVC_URL="https://vcenter_server | esxi_host"
  export GOVC_USERNAME="your_username"
  export GOVC_PASSWORD="your_password"
  export GOVC_INSECURE="true"

> 可以將以上環境變數儲存成檔案，每次執行 `govc` 時，直接執行 **source <環境變數檔案>** 即可。

其中 **`GOVC_URL`** 可以是下列格式：

  GOVC_URL='https://[GOVC_USERNAME]:[GOVC_PASSWORD]@[vcenter_server | esxi_host]/sdk'

> 或是在每次執行命令時帶入 **`-k=true -u=https://'[e-mail]':'VMware1!VMware1!'@192.168.1.1/sdk`**

如果一切都很順利，輸入 **`govc about`** 應可顯示所連接的 vSphere API 基本資訊。


可以輸入 **`govc about -json`** 產生 **JSON** 格式，以便之後使用 **`jq`** 進行處理。


### 基本操作

- 直接輸入 **`govc` 不帶任何參數**或輸入**不存在的命令**時，會顯示所有命令清單。命令會根據功能分為不同的命名空間。

- 加上 **`-h`** 或 **`--help`** 可以顯示命令使用及範例。

    govc ls -h


- 加上 **`-json`** 結果顯示為 JSON 格式。

    govc library.ls -json


可以搭配 **`jq`** 使用，取出其中參數使用。

    govc vm.info -json ${vmName} | jq '.VirtualMachines[] | .Self'


> 使用以下命令也可以顯示相同結果
> ```bash
> govc object.collect -s vm/Richard/docker_workVM/${vmName} summary.vm
>
> > VirtualMachine:vm-4190
> ```

- 使用 **`xargs`** 將前一個指令的結果傳至下一個指令作為輸入來源。

    govc object.collect -s vm/Richard/docker_workVM/${vmName} summary.runtime.host
    > HostSystem:host-1605
    
    govc ls -L HostSystem:host-1605
    > /Datacenter/host/Cluster/10.7.150.5

以上命令與下面命令結果相同。

    govc object.collect -s vm/Richard/docker_workVM/${vmName} summary.runtime.host | xargs govc ls -L

- 將 govc 結果存成變數作為後續使用

    dc=$(govc ls /)
    echo ${dc}
    > /Datacenter

其實以上大概就是 **`govc`** 基本操作方式，其他部份就請參考 [[**govc help**]](https://github.com/vmware/govmomi/blob/master/govc/USAGE.md)，自己嘗試使用看看吧。

### 操作範例
**基本資訊**
- 顯示連線 vCenter Server 資訊

    govc about


- 顯示目前連線的環境變數

    govc env


- 顯示詳細目錄清單

    govc ls


- 顯示目前資料中心概要資訊

    govc datacenter.info


> 可顯示資料中心的物件代碼

    govc datacenter.info -json | jq '.Datacenters[].Self.Value'
    
    > "datacenter-21"

**網路**
- 顯示網路資訊

    govc ls ${dc}/network


> 可顯示所指定網路的物件代碼。若要取得全部，調整為 **`${dc}/network/*`**

    govc ls -json ${dc}/network/VC-HA | jq '.elements[].Object.Self.Value'
    
    > "network-227"

**主機叢集**
- 顯示主機叢集名稱

    govc ls $dc/host
    
    > /Datacenter/host/Cluster

> 可顯示主機叢集的物件代碼

    govc ls -json $dc/host | jq '.elements[].Object.Self.Value'
  
    > "domain-c26"

- 顯示主機叢集資源使用狀態（**-S**: 容量僅計算共享儲存區）

    cluster=$(govc ls ${dc}/host)
    govc cluster.usage -S ${cluster}


- 顯示主機叢集中 ESXi 主機的 CPU/MEM 使用資訊

    govc ls $dc/host | xargs govc host.info 


> 可顯示所指定叢集中 ESXi 主機的物件代碼。若要取得全部，調整為 **`${dc}/host/<Cluster-Name>/*`**

    govc host.info -json /Datacenter/host/Cluster/10.7.150.5 | jq '.HostSystems[].Self.Value'
    
    > "host-1605"  

**儲存區**
- 顯示儲存區清單

    govc ls -l ${dc}/datastore


- 顯示指定儲存區類型及使用資訊

    ds='VNXe_Datastore_Sales2'
    govc datastore.info ${dc}/datastore/${ds}


> 可顯示指定儲存區的物件代碼

    govc datastore.info -json ${dc}/datastore/${ds} | jq '.Datastores[].Self.Value'
    
    > "datastore-2982"

- 在指定的儲存區中建立資料夾

    govc datastore.mkdir -ds=${ds} -p kali-images

- 複製檔案至儲存區指定資料夾

    iso='/mnt/ovaPath/kali-linux-2020.3-installer-amd64.iso'
    govc datastore.upload -ds=${ds} ${iso} kali-images/${iso}

- 顯示儲存區指定資料夾下的檔案資訊

    govc datastore.ls -l -ds=${ds} kali-images/mnt/ovaPath/
    
    > 3.7GB  Tue Jul 6 02:26:42 2021  kali-linux-2020.3-installer-amd64.iso

- 搬移儲存區中的檔案

    file='kali-linux-2020.3-installer-amd64.iso'
    govc datastore.mv -ds=${ds} kali-images/mnt/ovaPath/${file} kali-images/${file}

> 注意，目的端必須要完全指定為**檔案名稱**，不可為資料夾，會告警指定目的端已經存在！

- 刪除儲存區檔案或資料夾

    govc datastore.rm -ds=${ds} kali-images/mnt

> 若目的位置為資料夾，則會將其指定資料夾以下的**所有資料刪除**！

    govc datastore.rm -ds=${ds} kali-images
    
    govc datastore.ls -ds=${ds} kali-images
    
    > govc: file [VNXe_Datastore_Sales2] ./kali-images was not found

**虛擬機器**
- 查詢名稱開頭為 "Richard" 的虛擬機器，並顯示基本資訊

    govc vm.info Richard*


- 顯示單一虛擬機器的基本資訊

    vm='Richard-cb-workvm02'
    govc vm.info ${vm}


- 顯示單一虛擬機器基本資訊及使用資源摘要

    govc vm.info -r ${vm}


- 顯示所有虛擬機器名稱

    govc vm.info '*' | grep 'Name' | awk '{print $2}'

- 創建虛擬機器

    vmName='Ricahrd-Windows-Box'
    host='10.7.150.5'
    net='LAB-10.7.150.0'

    govc vm.create -m 8192 -c 2 -g windows8Server64Guest \
         -disk.controller lsilogic-sas \
         -net.adapter vmxnet3 \
         -ds ${ds} \
         -host ${host} \
         -net=${net} \
         -on=false "${vmName}"

> 從 Web Client 確認狀態

- 虛擬機器電源

    govc vm.power -on [-M] ${vm1} [vm2] [vm3] ...

> - 電源關閉預設會使用 VMTools，如果虛擬機器沒有正確安裝，執行命令會出錯，可以增加 `-force` 忽略錯誤強制執行
> - 電源開啟選項，有兩種方式: `VirtualMachine.powerOn(預設)` 和 `Datacenter.powerOnVm`。請參考 [[KB 1035224]](https://kb.vmware.com/s/article/1035224) 說明
> - 電源控制選項可以參考程式源碼
> 

- 使用虛擬機器 IP 位址進行查詢

    vmIp='10.7.150.82'
    govc vm.info -vm.ip ${vmIp}

> 若虛擬機器並未正確安裝 VMTools，有可能無法透過此方式完成查詢

- 查詢虛擬機器的 IP 位址

    govc vm.ip ${vmName}

> 若虛擬機器並未正確安裝 VMTools，有可能無法透過此方式取得 IP 資訊

- 刪除虛擬機器

    govc vm.destroy ${vmName}

- 移轉:變更計算資源(vMotion)

    host1='10.7.150.2'
    govc vm.migrate -host ${host1} ${kaliVm}
    
    > [06-07-21 22:30:20] migrating VirtualMachine:vm-2865... OK


> 移轉時若出現以下錯誤，請檢查兩台 ESXi 主機上的網路組態是否一致
> migrating VirtualMachine:vm-2865... (7%)govc: Currently connected network interface 'Network adapter 1' cannot use network 'OA-10.7.1.0', because the destination network on the destination host is configured for **different offload** or **security policies** than the source network on the source host.

- 移轉：變更儲存區(Storage vMotion)

    govc vm.migrate -ds ${other_ds} ${kaliVm}
    
    > [06-07-21 22:44:50] migrating VirtualMachine:vm-2865... (66%)


- 移轉：同時變更計算資源和儲存區

    govc vm.migrate -host ${host3} -ds ${ds} ${kaliVm}
    
    > [06-07-21 23:35:36] migrating VirtualMachine:vm-2865... (71%)


- 開啟 Remote Console

    kaliVm='Richard-cb-oa-kali'
    govc vm.console ${kaliVm}
    
    > vmrc://clone:cst-VCT-524ad1fe-03f8-6f06-60c1-ed68a7d4773b--tp-7D-88-7F-64-46-09-EF-E0-BF-98-36-FF-C2-67-B0-20-53-48-B6-59@10.7.150.1/?moid=vm-2865

擷取虛擬機器桌面畫面並存成 `screen.png` 圖檔

    govc vm.console -capture screen.png ${kaliVm}


擷取虛擬機器桌面畫面直接顯示於螢幕

    govc vm.console -capture - ${kaliVm} | display

使用 Linux VMRC 程式開啟虛擬機器 Remote Console

    xdg-open $(govc vm.console ${kaliVm})

- 變更網路

    workVm='Richard-cb-workvm02'
    oaNet='OA-10.7.1.0'
  
    govc vm.info -r ${workVm} | grep Network
    > Network:              LAB-10.7.150.0
  
    govc vm.network.change -vm ${workVm} -net ${oaNet} ethernet-0
    
    govc vm.info -r ${workVm} | grep Network
    > Network:              OA-10.7.1.0

> 顯示虛擬機器設備資訊

    govc device.ls -vm ${workVm}


- 建立快照

    govc snapshot.create -vm ${workVm} -d 'Created by GOVC' "snapshot-govc-test"


> - -m=true: 預設啟用**拍攝虛擬機器記憶體快照**。若要**取消**，使用 **`-m=false`**
> - -q=false: 預設關閉**靜止客體檔案系統**。若要**啟用**，使用 **`-q=true`**
>> 

- 顯示快照資訊

    govc snapshot.tree -vm ${workVm} -D -d -s -i


- 移除快照

    govc snapshot.remove -vm ${workVm} snapshot-govc-test03

結果:

    govc snapshot.remove -vm ${workVm} -r snapshot-4198

結果:

> 使用 **`'*'`** 來刪除**所有快照**
> ```bash
> govc snapshot.remove -vm ${workVm} '*'
> ```

- 還原快照
建立 10 筆快照進行測試

    for i in $(seq 1 10); do
      govc snapshot.create -vm ${workVm} -m=false -d 'Created by GOVC' "snapshot-govc-test${i}"
    done

目前快照狀態

還原快照至 **`snapshot-4205 snapshot-govc-test5`**

    govc snapshot.revert -vm ${workVm} snapshot-4205


**授權**
- 顯示目前授權資訊

    govc license.ls

>

    govc license.ls -json | jq .[].EditionKey


- 顯示已指派授權資訊

    govc license.assigned.ls


- 刪除授權

    govc license.remove ${licenseKey}

- 顯示授權提供功能

    govc license.decode -json ${licenseKey} | jq '.[].Properties[].Value.Properties[] | select(.Key=="feature") | .Value.Value' 2> /dev/null 


**ESXi 主機**

...... 後續(遙遙無期)再補
- vm.clone
- ~~vm.instantclone~~ [[參考]](https://hackmd.io/@farmer87/instantclone-3)
- import.ova
- export.ovf

### 參考範例

- 在 [[govmomi/govc github]](https://github.com/vmware/govmomi/tree/master/govc#examples) 網頁提供了以下經典使用範例，可以參考提供的程式**進一步學習 govc**。

- [Upload ssh public key to a VM](https://github.com/vmware/govmomi/blob/master/govc/examples/lib/ssh.sh)
- [Create a CoreOS VM](https://github.com/vmware/govmomi/blob/master/toolbox/toolbox-test.sh)
- [Create a Debian VM](https://github.com/kubernetes/kubernetes/tree/master/cluster/vsphere)
- [Create a Windows VM](https://github.com/dougm/govc-windows-box/blob/master/provision-esx.sh)
- [Create an ESX VM](https://github.com/vmware/govmomi/blob/master/scripts/vcsa/create-esxi-vm.sh)
- [Create a vCenter VM](https://github.com/vmware/govmomi/blob/master/scripts/vcsa/create-vcsa-vm.sh)
- [Create a Cluster](https://github.com/vmware/govmomi/blob/master/scripts/vcsa/create-cluster.sh)

- [Managing VMware vSphere Infrastructure using GOVC](https://github.com/collabnix/govc/blob/master/README.md)
- [Configure a vCenter cluster with vSAN datastore, DVS and DVPGs](https://github.com/collabnix/govc/blob/master/scripts/create-cluster.sh)
- [Create a Datacenter and connect the underlying ESXi host to vCenter VM](https://github.com/collabnix/govc/blob/master/scripts/create-standalone.sh)
- [Create a VM and boot stateless ESXi via cdrom/iso](https://github.com/collabnix/govc/blob/master/scripts/create-esxi-vm.sh)
- [Create VCSA VM](https://github.com/collabnix/govc/blob/master/scripts/create-vcsa-vm.sh)
## 參考連結
1. [github::govmomi/govc](https://github.com/vmware/govmomi/tree/master/govc)
2. [release::govmomi/govc](https://github.com/vmware/govmomi/releases)
3. [govc readme](https://github.com/vmware/govmomi/blob/master/govc/README.md)
4. [govc usage](https://github.com/vmware/govmomi/blob/master/govc/USAGE.md)

## 其他分享
### [使用 GOVC 開啟/關閉 ESXi 主機服務](https://hackmd.io/@farmer87/govc_services)
### [使用 GOVC 更新 ESXi 主機 root 密碼](https://hackmd.io/@farmer87/govc_account_update)
### [使用即時克隆 (Instant Clone) 複製虛擬機 - Part 3 (GOVC)](https://hackmd.io/@farmer87/instantclone-3)
### [使用 GOVC 安裝 Fedora CoreOS 於 vSphere 環境](https://hackmd.io/@farmer87/govc-coreos)
### [使用 Docker 方式來操作 GOVC](https://hackmd.io/@farmer87/podman_govc)