From 4a710c5951c7e218c3e06794d771c9cdb61cc023 Mon Sep 17 00:00:00 2001
From: Tushar Aggarwal <taggarwal@vmware.com>
Date: Fri, 7 Aug 2020 15:44:33 -0700
Subject: [PATCH] Add GOSS docs

---
 docs/book/src/SUMMARY.md        |  1 +
 docs/book/src/capi/goss/goss.md | 66 +++++++++++++++++++++++++++++++++
 docs/book/src/glossary.md       | 10 ++++-
 3 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 docs/book/src/capi/goss/goss.md

diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
index 2fc61e6fd5..af2dbd156f 100644
--- a/docs/book/src/SUMMARY.md
+++ b/docs/book/src/SUMMARY.md
@@ -8,4 +8,5 @@
   - [DigitalOcean](./capi/providers/digitalocean.md)
   - [OpenStack](./capi/providers/openstack.md)
   - [vSphere](./capi/providers/vsphere.md)
+  - [Testing the Images](./capi/goss/goss.md)
 - [Glossary](./glossary.md)
diff --git a/docs/book/src/capi/goss/goss.md b/docs/book/src/capi/goss/goss.md
new file mode 100644
index 0000000000..04ff8d2263
--- /dev/null
+++ b/docs/book/src/capi/goss/goss.md
@@ -0,0 +1,66 @@
+# Testing CAPI Images
+
+## GOSS
+
+[Goss](https://github.com/aelsabbahy/goss) is a YAML based serverspec alternative
+tool for validating a server’s configuration. It is used in conjunction with 
+[packer-provisioner-goss](https://github.com/YaleUniversity/packer-provisioner-goss/releases)
+to test if the images have all requisite components to work with cluster API.
+
+### Support Matrix 
+*For stock server-specs shipped with repo
+
+| OS | Builder | 
+|----|---------|
+| Amazon Linux | aws
+| PhotonOS | ova
+| Ubuntu | aws , ova, azure
+| CentOS | aws, ova 
+
+
+### Prerequisites for Running GOSS
+GOSS runs as a part of image building through a packer provisioner.
+Supported arguments are passed through file: `packer/config/goss-args.json`
+```json
+{
+  "goss_arch": "amd64",
+  "goss_entry_file": "goss/goss.yaml",
+  "goss_format": "json",
+  "goss_inspect_mode": "true",
+  "goss_tests_dir": "packer/goss",
+  "goss_url": "",
+  "goss_format_options": "pretty",
+  "goss_vars_file": "packer/goss/goss-vars.yaml",
+  "goss_version": "0.3.13"
+}
+```
+##### Supported values for some of the arguments can be found [here](https://github.com/aelsabbahy/goss).
+> Enabling the `goss_inspect_mode` lets you build image even if goss tests fail.
+
+#### Manually setup GOSS
+- Start a VM from capi image
+- Copy complete goss dir `packer/goss` to remote machine
+- Download and setup GOSS (use version from goss-args) on the remote machine. [Instructions](https://github.com/aelsabbahy/goss#latest) 
+- Custom goss version can be installed if testing custom server-specs supported by higher version of GOSS.
+- All the variables used in GOSS are declared in `packer/goss/goss-vars.yaml`
+- Add more custom serverspec to corresponding GOSS files. Like, `goss-command.yaml` or `goss-kernel-params.yaml`
+    ```yaml
+      some_cli --version:
+        exit-status: 0
+        stdout: [{{ .Vars.some_cli_version }}]
+        stderr: []
+        timeout: 0
+    ```
+- Add more custom variables to corresponding GOSS file `goss-vars.yaml`.
+    ```yaml
+    some_cli_version: "1.4.5+k8s-1"
+    ```
+- Fill the variable values in `goss-vars.yaml` or specify in `--vars-inline` while executing GOSS in below steps
+- Render the goss template to fix any problems with parsing variable and serverspec yamls
+  ```bash
+    sudo goss -g goss/goss.yaml --vars /tmp/goss/goss-vars.yaml --vars-inline '{"ARCH":"amd64","OS":"Ubuntu","PROVIDER":"aws", some_cli_version":"1.3.4"}' render
+  ```     
+- Run the GOSS tests  
+  ```bash
+    sudo goss -g goss/goss.yaml --vars /tmp/goss/goss-vars.yaml --vars-inline '{"ARCH":"amd64","OS":"Ubuntu","PROVIDER":"aws", some_cli_version":"1.3.4"}' validate --retry-timeout 0s --sleep 1s -f json -o pretty
+  ```
diff --git a/docs/book/src/glossary.md b/docs/book/src/glossary.md
index b3f63d390e..61e1426521 100644
--- a/docs/book/src/glossary.md
+++ b/docs/book/src/glossary.md
@@ -1,6 +1,6 @@
 # Table of Contents
 
-[A](#a) | [C](#c) | [E](#e) | [K](#k) | [O](#o) | [V](#v)
+[A](#a) | [C](#c) | [E](#e) | [G](#g) | [K](#k) | [O](#o) | [V](#v)
 
 # A
 ---
@@ -38,6 +38,7 @@ The Cluster API is a Kubernetes project to bring declarative, Kubernetes-style A
 
 [Cluster API Prover Azure](https://github.com/kubernetes-sigs/cluster-api-provider-azure)
 
+
 # E
 ---
 
@@ -45,6 +46,13 @@ The Cluster API is a Kubernetes project to bring declarative, Kubernetes-style A
 
 ESXi (formerly ESX) is an enterprise-class, type-1 hypervisor developed by VMware. ESXi provides strong separation between VMs and itself, providing strong security boundaries between the guest and host operating systems. ESXi can be used as a standalone entity, without vCenter but this is extremely uncommon and feature limited as without a higher level manager (vCenter). ESXi cannot provide its most valuable features, like High Availability, vMotion, workload balancing and vSAN (a software defined storage stack).
 
+# G
+---
+
+## GOSS
+
+[Goss](https://github.com/aelsabbahy/goss) is a YAML based serverspec alternative tool for validating a server’s configuration.  It is used in conjunction with [packer-provisioner-goss](https://github.com/YaleUniversity/packer-provisioner-goss/releases) to test if the images have all requisite components to work with cluster API.
+
 # K
 ---