src/cmd/cos_xfstests_runner/README.md

# COS Xfstests Runner container used in COS xfstests

## Overview

This is an docker image used by COS (Container-Optimized OS)
xfstests. It includes scripts and necessary dependencies for running
gce-xfstests under a given xfstests config against a given COS version.

The image is released at `gcr.io/cos-xfstests/cos-xfstests-runner` with a unique
tag for each release. This container image is not publicly available.

## Building COS Xfstests Runner Image

### Locally (for testing the image)

For testing, you can simply build and test this docker container locally on your
workstation:

```shell
  $ docker build -t cos-xfstests-runner:dev .
```

### Production (push into GCR)
Since `gcr.io/cos-xfstests/cos-xfstests-runner` is not publicly available, only
authenticated users can push into the GCR registry.

```shell
  $ VERSION=<version>  # e.g., 20171008
  $ docker build -t gcr.io/cos-xfstests/cos-xfstests-runner:$VERSION .
  $ docker build -t gcr.io/cos-xfstests/cos-xfstests-runner:latest .
  $ gcloud docker -- push gcr.io/cos-xfstests/cos-xfstests-runner:$VERSION
  $ gcloud docker -- push gcr.io/cos-xfstests/cos-xfstests-runner:latest
```

## Using COS Xfstests Runner Image

### Locally (for testing the image)

COS xfstests runner container will use the xfstests-bld tarball and kernel image
generated by COS kernel CI. To run this container locally, you can build the kernel
image using cos_kerenl_devenv container.

To run the COS xfstests runner locally:

```shell
  $ docker run --rm -v ~/.config/gcloud:/root/.config/gcloud cos-xfstests-runner:dev -x overlay -n xfs-vm -r gs://xueweiz-play/xfstests/R76-12188.0.0 -p cos-xfstests -z us-west1-c -b generic/269,generic/347,generic/405,generic/500
```

The container will download xfstests-bld tarball and kernel image from given GCS
bucket, then run `gce-xfstests` script on the given config. This will create one
GCE instance and two responding disks in the given project and zone. If they run
into soft lockup, the developer must manually clean them up.

The container image is set to use
[test appliance image](https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md#creating-a-new-gce-test-appliance-image)
"xfstests-201901211635" by default. Use the `--rootfs_image` to overwrite it.