goss: Open Source Cloud Infrastructure Management

What is goss?

Goss is an Apache-2.0 licensed, Go-based YAML test runner that validates the configuration of a server or container and can expose the result as a health endpoint, built for DevOps engineers and SREs who need fast, repeatable checks on Linux hosts, Docker containers, and Kubernetes workloads.

What it is

Goss lives in the infrastructure-as-code and DevOps tooling ecosystem, alongside the CI pipelines and monitoring systems that consume its output. It is a YAML-based alternative to serverspec, the Ruby tool that validates a server's configuration through a domain-specific language. Where serverspec asks the operator to write every assertion by hand, Goss starts from the live system: it inspects the current state of a machine and derives a test suite from it, so the known-good configuration is captured first and asserted later.

The concrete problem it solves is configuration drift and untested provisioning. After a machine is built, an image is baked, or a container starts, something has to confirm that the sshd configuration, the listening ports, the packages, and the services are still what they were meant to be. Goss turns that verification into a file that can be executed on demand, waited on until it passes, or served as an HTTP health endpoint for external monitors. Small to medium suites are near instantaneous, and the whole tool ships as a single small binary, which keeps it usable inside restricted hosts and container images where a full test framework would not fit.

Key capabilities

YAML test suites generated from current system state using the add command, so assertions begin as a snapshot of a working machine.
Three execution modes for one suite: run it once, wait on it with retries, or serve it as a health endpoint.
dgoss wrapper for testing containers, with additional user-submitted wrappers kgoss for Kubernetes and dcgoss for Docker Compose.
Distribution as a release tarball, for example goss_0.4.10_linux_x86_64.tar.gz from the GitHub releases page, extracted directly to /usr/local/bin/goss.
Build from source with make build, or with goreleaser using goreleaser build, --single-target, --clean, and --snapshot flags.
Published container image for running Goss inside containerized environments.
Health endpoint output aimed at monitoring tooling, reflected in the project's Nagios and Sensu topics.

Who uses it and how

CI pipelines that validate a freshly provisioned host or image; the README warns explicitly that pipelines should pin a specific release tag such as v0.4.10 rather than download latest, because the latest release may behave unexpectedly.
Container workflows using the dgoss wrapper to assert the contents and behaviour of a built image before it is promoted.
Kubernetes and Docker Compose teams using kgoss and dcgoss for container ordering and healthcheck examples, as described in the maintainer's blog post on simplified health checks.
Monitoring-driven operations teams that pull Goss output into existing alerting through the health endpoint rather than authoring separate checks.
Infrastructure-as-code practitioners who keep the YAML suite in version control next to provisioning code, so a machine build and its acceptance criteria travel together.

Getting started

The documented path is a manual install from a pinned GitHub release, streaming the tarball into /usr/local/bin/goss and optionally the dgoss wrapper into the same directory. Building from source is also supported through make build or goreleaser.

How it compares

The README positions Goss directly as a YAML-based alternative to serverspec, which is the closest comparable tool named in the project's own facts. The practical contrast is authoring model and footprint: Goss generates a starting suite from the machine's current state and ships as a single small Go binary, while serverspec expects assertions to be written by hand in a Ruby-based test framework.

When to use it — and when not to

A self-hoster needs to run a binary and keep a YAML file under version control; nothing in the facts indicates a required database, object store, or SMTP dependency, and suites can simply be executed, waited on, or served over HTTP. It is the wrong choice for anyone expecting configuration management or remediation, because Goss validates state rather than converging it, and pipelines that ignore the warning about latest will get unpredictable behaviour. The README itself is brief and defers heavily to documentation hosted on Read the Docs, so teams wanting everything explained in-repo should expect to follow external links, and the tracker carries 57 open issues at the time of writing.

project readme (upstream, from github) — read inline

Goss - Quick and Easy server validation

Goss in 45 seconds

Note: For testing containers see the dgoss wrapper. Also, user submitted wrapper scripts for Kubernetes kgoss and Docker Compose dcgoss.

Note: For some Docker/Kubernetes healthcheck, health endpoint, and container ordering examples, see my blog post.

Introduction

What is Goss?

Goss is a YAML based serverspec 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.

Why use Goss?

Goss is EASY! - Goss in 45 seconds
Goss is FAST! - small-medium test suites are near instantaneous, see benchmarks
Goss is SMALL! - 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, follow documented instructions, with arguments such as:

schema url=https://goss.readthedocs.io/en/stable/schema.yaml
schema version=Json schema version 7
file 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
title and meta (arbitrary data) attributes are persisted when adding other resources with goss 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/sshd

package:
  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 rendered using the goss render command. See example below

$ cd docs
$ goss --vars ./vars.yaml render > rendered_goss.yaml
# proceed with json schema validation of rendered_goss.yaml in your favorite IDE
# or in one of the Json schema validator listed in https://json-schema.org/implementations.html
# The following example is for 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.yaml

rendered_goss.yaml: fail: process.chrome: skip is required
rendered_goss.yaml: fail: service.sshd: skip is required
1 of 1 failed validation
rendered_goss.yaml: fail: process.chrome: skip is required
rendered_goss.yaml: fail: service.sshd: skip is required

JSON Schema maintains a table of validators.

Supported resources

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

Supported output formats

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

Community Contributions

goss-ansible - Ansible module for Goss.
degoss - Ansible role for installing, running, and removing Goss in a single go.
ansible-goss-install - Ansible role for installing Goss (option for install as user or root)
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.

Limitations

goss works well on Linux, but support on Windows & macOS is alpha. See platform-feature-parity.

The following tests have limitations.

Package:

rpm
deb
Alpine apk
pacman

Service:

systemd
sysV init
OpenRC init
Upstart

Frequently asked questions

Is goss free to use?

goss is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does goss do?

Quick and Easy server testing/validation

What is goss written in?

goss is primarily written in Go. Its source is publicly available at https://github.com/goss-org/goss, and it has 6,000 GitHub stars.