Goss YAML-based server validation and testing tool. This skill should be used when writing goss.yaml gossfiles, validating server configuration (packages, services, files, ports, processes, users, groups, DNS, HTTP endpoints, mounts, kernel parameters, network interfaces), using goss CLI commands (validate, serve, add, autoadd, render), testing Docker containers with dgoss, testing Kubernetes pods with kgoss, testing docker-compose stacks with dcgoss, writing goss templates with Go text/template and Sprig functions, using goss matchers (regex, numeric, semver, gjson), configuring goss serve health endpoints, modularizing gossfiles with includes, or troubleshooting goss validation failures.
YAML-based server testing/validation tool. Single Go binary, no dependencies. Generates tests from current system state via goss add/goss autoadd.
# Binary install
curl -L https://github.com/goss-org/goss/releases/latest/download/goss-linux-amd64 -o /usr/local/bin/goss
chmod +rx /usr/local/bin/goss
# dgoss (Docker wrapper)
curl -L https://raw.githubusercontent.com/goss-org/goss/master/extras/dgoss/dgoss -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss
| Command | Alias | Purpose |
|---|---|---|
goss validate | goss v | Run tests, show results |
goss serve | goss s | Expose health endpoint (default :8080/healthz) |
goss add <type> <name> | goss a | Add single resource test |
goss autoadd <name> | goss aa | Auto-discover all resources for a service |
goss render | goss r | Render gossfile with includes/templates |
goss validate --format documentation # verbose output
goss validate --retry-timeout 30s # retry for 30s (startup waits)
goss validate -g custom.yaml # custom gossfile
goss validate --vars vars.yaml # template variables
goss serve --listen-addr 0.0.0.0:9000 --format json --cache 30s
rspecish (default), documentation, json, junit, tap, nagios, prometheus, silent
| Type | Key Attributes | Notes |
|---|---|---|
file | exists, mode, owner, group, contents, filetype, sha256 | Supports checksums, symlink targets |
package | installed, versions | Use --package flag for manager type |
service | enabled, running | systemd/init |
port | listening, ip | Format: tcp:22:, tcp6:22:, udp:53: |
process | running | Match by command name |
command | exit-status, stdout, stderr, timeout | Default timeout 10s (in ms) |
user | exists, uid, gid, groups, home, shell | |
group | exists, gid | |
dns | resolvable, addrs, server | Record types: A, AAAA, CNAME, MX, etc. |
http | status, body, headers, allow-insecure | Auth, TLS certs, proxy support |
addr | reachable, timeout | Remote TCP/UDP reachability |
mount | exists, filesystem, source, opts, usage | defaults is fstab alias, not actual opt |
kernel-param | value | sysctl parameters |
interface | exists, addrs, mtu | Network interfaces |
gossfile | (import) | Include other gossfiles, supports globs |
matching | content, matches | Best with templates for complex assertions |
# Multiple resources consolidated under single type key
# YAML overwrites duplicate keys - never declare same type twice