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 ---