repository·master·Indexed 26 days ago
https://github.com/goss-org/gossA fast, lightweight, YAML-based tool for validating server configurations. It allows users to define system states as tests that can be executed, retried, or served as health endpoints. The project includes wrappers such as dcgoss for docker-compose containers, dgoss for general container validation, and kgoss for running server validations within Kubernetes pods.
The ghcr.io/goss-org/goss image is a simple Alpine-based image with Goss preinstalled. You can use it as a base image for your own projects to facilitate easy health checking within containers.
FROM ghcr.io/goss-org/goss:latestGossfiles support Go's text/template engine, allowing for dynamic tests using environment variables, custom variables, and functions.
Available Variables:
{{.Env}}: Environment variables.{{.Vars}}: Values defined via the --vars flag.Custom Functions:
mkSlice "ARG1" "ARG2": Returns a slice of arguments.getEnv "var" ["default"]: Returns env var or a default value.readFile "fileName": Reads file content as a string (errors if file is missing).regexMatch "regex": Tests input against a regex.toLower / toUpper: Case conversion.findStringSubmatch regex string: Returns a map of named subexpressions from a regex match.Warning: Files containing {{}} template controls are incompatible with goss add/autoadd commands.
file:
{{- range mkSlice "/etc/passwd" "/etc/group"}}
{{.}}:
exists: true
mode: "0644"
owner: root
group: root
filetype: file
{{end}}VERSION to retrieving the full EVR (Epoch, Version, Release) string.You can run Goss as a background service to provide a health check endpoint for your system or containers.
Standard rspecish response:
goss serve &
curl localhost:8080/healthzJSON format:
goss serve --format json &
curl localhost:8080/healthzRSpecish response via content negotiation:
goss serve --format json &
curl -H "Accept: application/vnd.goss-rspecish" localhost:8080/healthzThe file.contains attribute has been renamed to file.contents. Update your YAML configurations to use the new key to avoid validation errors.
# Old configuration
file:
/tmp/foo:
exists: true
contains: []
# New configuration
file:
/tmp/foo:
exists: true
contents: []To validate Goss binaries for macOS (darwin) and Windows, you can run specific integration test targets via make. These tests run the validate command against spec files located in integration-tests that match the target OS.
make test-int-validate-darwin-amd64make test-int-validate-windows-amd64make test-int-validate-darwin-amd64
make test-int-validate-windows-amd64Use dcgoss edit <docker_run_params> to launch a container, install goss inside it, and enter an interactive shell. This is the recommended way to write tests using goss add or goss autoadd commands.
Workflow:
dcgoss edit <service_name>.dcgoss will automatically copy any created or modified goss.yaml or goss_wait.yaml files from the container back to your current host directory.Example:
dcgoss edit dbdcgoss edit dbYou can create Goss tests using three methods:
goss autoadd <resource to test> to automatically generate test entries.goss add <resource to test> to generate a YAML template for a specific resource.When using goss add, you can manually edit the resulting YAML file to customize parameters. For example, to test if a package is uninstalled, change installed: true to installed: false.
Use dgoss run <docker_run_params> to validate a container. It expects a ./goss.yaml file in the current directory.
If a ./goss_wait.yaml file exists, dgoss will first check that the conditions in that file are met before executing the main tests in ./goss.yaml. This is useful for waiting for ports to open.
dgoss run performs the following:
/goss/docker_output.log inside the container (allowing you to test against log output).goss with $GOSS_WAIT_OPTS if ./goss_wait.yaml is present.goss with $GOSS_OPTS using ./goss.yaml.You can automate the installation using a GitHub personal access token and jq. This script installs kgoss to a destination directory and fetches the specific goss binary version from GitHub releases.
Prerequisites:
jq must be installed.Note: If goss is not in your path after installation, you must export the GOSS_PATH variable pointing to the binary.
token=<personal_access_token>
username=$(whoami)
dest_dir=${HOME}/bin
host=raw.githubusercontent.com
repo=goss-org/goss
## install kgoss
curl -sSL -u "${username}:${token}" -H 'Accept: application/vnd.github.v3.raw' -o "${dest_dir}/kgoss" \
https://${host}/api/v3/repos/${repo}/contents/extras/kgoss/kgoss
chmod a+rx "${dest_dir}/kgoss"
## install goss
if [[ ! $(which jq) ]]; then echo "jq is required, get from https://stedolan.github.io/jq"; fi
version=v0.4.8
arch=amd64
host=github.com
dl_url=$(curl -sSL -u "${username}:${token}" https://${host}/api/v3/repos/${repo}/releases \
| jq -r ".[] | select (.name == \"${version}\") | .assets[] | select (.name == \"goss-linux-${arch}\") | .url")
curl -sSL -u "${username}:${token}" -H 'Accept: application/octet-stream' -o "${dest_dir}/goss" $dl_url
chmod a+rx "${dest_dir}/goss"
# If `goss` is not in your path, export a GOSS_PATH variable:
export GOSS_PATH=${dest_dir}/gossTo enable IDE features like inline documentation, auto-completion, and static analysis for your goss.yaml files, you can use the official JSON schema.
Schema URL: https://goss.readthedocs.io/en/stable/schema.yaml (Draft 7)
Example configuration for JetBrains IntelliJ IDEA:
schema url=https://goss.readthedocs.io/en/stable/schema.yamlschema version=Json schema version 7file path pattern=*/goss.yamlOnce you have a goss.yaml file, you can execute the tests using the validate command.
Run once:
goss validateRun with variables (templates):
goss --vars vars.yaml validateRetry until success or timeout:
Use --retry-timeout to keep running tests until the system reaches the desired state, and --sleep to define the interval between retries.
goss validate --retry-timeout 30s --sleep 1sgoss validate
# or
goss validate --retry-timeout 30s --sleep 1s