- Notifications
You must be signed in to change notification settings - Fork0
Quick and Easy server testing/validation
License
marcinpraczko/goss
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
**
Note: For testing containers see thedgoss wrapper.Also, user submitted wrapper scripts for Kuberneteskgossand Docker Composedcgoss.
Note: For some Docker/Kubernetes healthcheck, health endpoint, andcontainer ordering examples, see my blog posthere.
Goss is a YAML basedserverspec alternative tool for validating a server's configuration.It eases the process of writing tests by allowing the user to generate tests from the current system state.Once the test suite is written they can be executed, waited-on, or served as a health endpoint.
- Goss is EASY! -Goss in 45 seconds
- Goss is FAST! - small-medium test suites are near instantaneous, seebenchmarks
- Goss is SMALL! - <10MB single self-contained binary
Note: For macOS and Windows, see:platform-feature-parity.
This will install goss anddgoss.
Note: Usingcurl | sh is not recommended for production systems, use manual installation below.
# Install latest version to /usr/local/bincurl -fsSL https://goss.rocks/install| sh# Install v0.4.8 version to ~/bincurl -fsSL https://goss.rocks/install| GOSS_VER=v0.4.8 GOSS_DST=~/bin sh
curl -L https://github.com/goss-org/goss/releases/latest/download/goss-linux-amd64 -o /usr/local/bin/gosschmod +rx /usr/local/bin/gosscurl -L https://github.com/goss-org/goss/releases/latest/download/dgoss -o /usr/local/bin/dgoss# Alternatively, using the latest master# curl -L https://raw.githubusercontent.com/goss-org/goss/master/extras/dgoss/dgoss -o /usr/local/bin/dgosschmod +rx /usr/local/bin/dgoss
# See https://github.com/goss-org/goss/releases for release versionsVERSION=v0.4.8curl -L"https://github.com/goss-org/goss/releases/download/${VERSION}/goss-linux-amd64" -o /usr/local/bin/gosschmod +rx /usr/local/bin/goss# (optional) dgoss docker wrapper (use 'master' for latest version)VERSION=v0.4.8curl -L"https://github.com/goss-org/goss/releases/download/${VERSION}/dgoss" -o /usr/local/bin/dgosschmod +rx /usr/local/bin/dgoss
make build
Using the Goss container image
An initial set of tests can be derived from the system state by using theaddorautoadd commands.
Let's write a simple sshd test using autoadd.
# Running it as root will allow it to also detect ports$ sudo goss autoadd sshd
Generatedgoss.yaml:
port:tcp:22:listening:trueip: -0.0.0.0tcp6:22:listening:trueip: -'::'service:sshd:enabled:truerunning:trueuser:sshd:exists:trueuid:74gid:74groups: -sshdhome:/var/empty/sshdshell:/sbin/nologingroup:sshd:exists:truegid:74process:sshd:running:true
Now that we have a test suite, we can:
- Run it once
$goss validate...............Total Duration: 0.021s # <- yeah, it's that fast..Count: 15, Failed: 0
- Edit it to usetemplates, and run with a vars file
goss --vars vars.yaml validate- keep running it until the system enters a valid state or we timeout
goss validate --retry-timeout 30s --sleep 1s- serve the tests as a health endpoint
$goss serve&$curl localhost:8080/healthz#JSON endpoint$goss serve --format json&$curl localhost:8080/healthz#rspecish response via content negotiation$goss serve --format json&$curl -H"Accept: application/vnd.goss-rspecish" localhost:8080/healthz
Goss files can be manually edited to improve readability and expressiveness of tests.
AJson draft 7 schema availableathttps://goss.rocks/schema.yaml makes it easier to edit simple goss.yaml files in IDEs,providing usual coding assistance such as inline documentation, completion and static analysis.See #793 for screenshots.
For example, to configure the Json schema in JetBrains intellij IDEA,followdocumented instructions,with arguments such as:
schema url=https://goss.rocks/schema.yamlschema version=Json schema version 7file path pattern=*/goss.yaml
In addition, Goss files can also be further manually edited (without yet full json support) to use:
- Patterns
- Advanced Matchers
- Templates
titleandmeta(arbitrary data) attributes are persisted when adding other resources withgoss add
Some examples:
user: sshd: title: UID must be between 50-100, GID doesn't matter. home is flexible meta: desc: Ensure sshd is enabled and running since it's needed for system management sev: 5 exists: true uid: # Validate that UID is between 50 and 100 and: gt: 50 lt: 100 home: # Home can be any of the following or: - /var/empty/sshd - /var/run/sshdpackage: kernel: installed: true versions: # Must have 3 kernels and none of them can be 4.4.0 and: - have-len: 3 - not: contain-element: 4.4.0 # Loaded from --vars YAML/JSON file {{.Vars.package}}: installed: true{{if eq .Env.OS "centos"}} # This test is only when $OS environment variable is set to "centos" libselinux: installed: true{{end}}Goss.yaml files with templates can still be validated through the Json schema after being renderedusing thegoss render command. See example below
$cd docs$goss --vars ./vars.yaml render> rendered_goss.yaml#proceed with json schema validation of rendered_goss.yamlin your favorite IDE#orin one of the Json schema validator listedin https://json-schema.org/implementations.html#The following example isfor a Linux AMD64 host$curl -LO https://github.com/neilpa/yajsv/releases/download/v1.4.1/yajsv.linux.amd64$chmod a+x yajsv.linux.amd64$sudo mv yajsv.linux.amd64 /usr/sbin/yajsv$yajsv -s goss-json-schema.yaml rendered_goss.yamlrendered_goss.yaml: fail: process.chrome: skip is requiredrendered_goss.yaml: fail: service.sshd: skip is required1 of 1 failed validationrendered_goss.yaml: fail: process.chrome: skip is requiredrendered_goss.yaml: fail: service.sshd: skip is required
Full list of available Json schema validators can be found inhttps://json-schema.org/implementations.html#validator-command%20line
- package - add new package
- file - add new file
- addr - add new remote address:port - ex: google.com:80
- port - add new listening [protocol]:port - ex: 80 or udp:123
- service - add new service
- user - add new user
- group - add new group
- command - add new command
- dns - add new dns
- process - add new process name
- kernel-param - add new kernel-param
- mount - add new mount
- interface - add new network interface
- http - add new network http url with proxy support
- goss - add new goss file, it will be imported from this one
- matching - test for matches in supplied content
- rspecish -(default) Similar to rspec output
- documentation - Verbose test results
- json - JSON, detailed test result
- tap - TAP style
- junit - JUnit style
- nagios - Nagios/Sensu compatible output /w exit code 2 for failures.
- prometheus - Prometheus compatible output.
- silent - No output. Avoids exposing system information (e.g. when serving tests as a healthcheck endpoint).
- goss-ansible - Ansible module for Goss.
- degoss - Ansible role for installing, running, and removing Goss in a single go.
- kitchen-goss - A test-kitchen verifier plugin for Goss.
- goss-fpm-files - Might be useful for building goss system packages.
- packer-provisioner-goss - A packer plugin to run Goss as a provision step.
- gossboss - Collect and view aggregated Goss test results from multiple remote Goss servers.
goss works well on Linux, but support on Windows & macOS is alpha. Seeplatform-feature-parity.
The following tests have limitations.
Package:
- rpm
- deb
- Alpine apk
- pacman
Service:
- systemd
- sysV init
- OpenRC init
- Upstart