Skip to content

Quick start

Writing a simple sshd test

An initial set of tests can be derived from the system state by using the add or autoadd 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

Generated goss.yaml:

port:
  tcp:22:
    listening: true
    ip:

    - 0.0.0.0
  tcp6:22:
    listening: true
    ip:
    - '::'
service:
  sshd:
    enabled: true
    running: true
user:
  sshd:
    exists: true
    uid: 74
    gid: 74
    groups:
    - sshd
    home: /var/empty/sshd
    shell: /sbin/nologin
group:
  sshd:
    exists: true
    gid: 74
process:
  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 use templates, 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

Running a subset of tests with marks

Tests can be tagged with arbitrary marks (inspired by pytest -m) and then filtered at validation time. This is useful for:

  • Selective alerting - run only critical health checks in production
  • Incident response - quickly run network or storage categories
  • Flaky-test quarantine - tag flaky tests flaky and exclude them from CI

Add marks to any resource in your gossfile:

command:
  echo hello:
    exit-status: 0
    stdout: [hello]
    marks:

      - critical
      - fast
  echo slow:
    exit-status: 0
    stdout: [slow]
    marks:
      - slow
http:
  https://api.example.com/health:
    status: 200
    marks:
      - critical
      - network

Then filter at run time with --marks (include) and/or --exclude-marks:

# Only run tests marked "critical"
$ goss validate --marks critical

# Run tests marked "critical" OR "fast"
$ goss validate --marks critical,fast

# Exclude slow and flaky tests
$ goss validate --exclude-marks slow,flaky

# Combine: run critical tests but skip any that are also marked flaky
$ goss validate --marks critical --exclude-marks flaky

Resources with no marks are always included unless filtered out by --exclude-marks or other criteria. When --marks is set, unmarked resources are skipped. See docs/marks.md or the design spec for the full evaluation rules.

Marks also work on the health endpoint - pass them as query parameters, which override any defaults baked in via the serve command's flags:

$ goss serve --marks critical &
$ curl 'localhost:8080/healthz'                          # uses --marks critical
$ curl 'localhost:8080/healthz?marks=network'            # overrides: only network
$ curl 'localhost:8080/healthz?exclude-marks=slow,flaky' # include all but slow/flaky

When using goss add or goss autoadd, pass --marks to tag newly created resources automatically:

$ goss add --marks critical service sshd
$ goss autoadd --marks network nginx

Existing marks on previously parsed resources are preserved; the flag only applies to newly created ones.

Manually editing Goss files

Goss files can be manually edited to improve readability and expressiveness of tests.

A Json draft 7 schema available at https://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, follow documented instructions, with arguments such as:

  • schema url=https://goss.rocks/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:

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

Full list of available Json schema validators can be found in https://json-schema.org/implementations.html#validator-command%20line