From ab2394446ccde47ed07fb86743f4a425107c6298 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Tue, 12 Apr 2016 14:03:56 -0700 Subject: [PATCH] Integration test readme update Updates the readme to mention running the tests using golem. Also provides instructions for making test development easier. Signed-off-by: Derek McGowan (github: dmcgowan) --- contrib/docker-integration/README.md | 153 +++++++-------------------- 1 file changed, 40 insertions(+), 113 deletions(-) diff --git a/contrib/docker-integration/README.md b/contrib/docker-integration/README.md index 15e0a080a..bc5be9d96 100644 --- a/contrib/docker-integration/README.md +++ b/contrib/docker-integration/README.md @@ -1,136 +1,63 @@ # Docker Registry Integration Testing -These integration tests cover interactions between the Docker daemon and the -registry server. All tests are run using the docker cli. +These integration tests cover interactions between registry clients such as +the docker daemon and the registry server. All tests can be run using the +[golem integration test runner](https://github.com/docker/golem) -The compose configuration is intended to setup a testing environment for Docker -using multiple registry configurations. These configurations include different -combinations of a v1 and v2 registry as well as TLS configurations. +The integration tests configure components using docker compose +(see docker-compose.yaml) and the runner can be using the golem +configuration file (see golem.conf). -## Running inside of Docker -### Get integration container -The container image to run the integation tests will need to be pulled or built -locally. +## Running integration tests -*Building locally* -``` -$ docker build -t distribution/docker-integration . -``` +### Run using multiversion script -### Run script +The integration tests in the `contrib/docker-integration` directory can be simply +run by executing the run script `./run_multiversion.sh`. If there is no running +daemon to connect to, run as `./run_multiversion.sh -d`. -Invoke the tests within Docker through the `run.sh` script. +This command will build the distribution image from the locally checked out +version and run against multiple versions of docker defined in the script. To +run a specific version of the registry or docker, Golem will need to be +executed manually. -``` -$ ./run.sh -``` +### Run manually using Golem -Run with aufs driver and tmp volume -**NOTE: Using a volume will prevent multiple runs from needing to -re-pull images** -``` -$ DOCKER_GRAPHDRIVER=aufs DOCKER_VOLUME=/tmp/volume ./run.sh -``` +Using the golem tool directly allows running against multiple versions of +the registry and docker. Running against multiple versions of the registry +can be useful for testing changes in the docker daemon which are not +covered by the default run script. -### Example developer flow +#### Installing Golem -These tests are useful for developing both as a registry and docker -core developer. The following setup may be used to do integration -testing between development versions +Golem is distributed as an executable binary which can be installed from +the [release page](https://github.com/docker/golem/releases/tag/v0.1). -Insert into your `.zshrc` or `.bashrc` +#### Running golem with docker -``` -# /usr/lib/docker for Docker-in-Docker -# Set this directory to make each invocation run much faster, without -# the need to repull images. -export DOCKER_VOLUME=$HOME/.docker-test-volume +Additionally golem can be run as a docker image requiring no additonal +installation. -# Use overlay for all Docker testing, try aufs if overlay not supported -export DOCKER_GRAPHDRIVER=overlay +`docker run --privileged -v "$GOPATH/src/github.com/docker/distribution/contrib/docker-integration:/test" -w /test distribution/golem golem -rundaemon .` -# Name this according to personal preference -function rdtest() { - if [ "$1" != "" ]; then - DOCKER_BINARY=$GOPATH/src/github.com/docker/docker/bundles/$1/binary/docker - if [ ! -f $DOCKER_BINARY ]; then - current_version=`cat $GOPATH/src/github.com/docker/docker/VERSION` - echo "$DOCKER_BINARY does not exist" - echo "Current checked out docker version: $current_version" - echo "Checkout desired version and run 'make binary' from $GOPATH/src/github.com/docker/docker" - return 1 - fi - fi +#### Golem custom images - $GOPATH/src/github.com/docker/distribution/contrib/docker-integration/run.sh -} -``` +Golem tests version of software by defining the docker image to test. -Run with Docker release version -``` -$ rdtest -``` +Run with registry 2.2.1 and docker 1.10.3 -Run using local development version of docker -``` -$ cd $GOPATH/src/github.com/docker/docker -$ make binary -$ rdtest `cat VERSION` -``` +`golem -i golem-dind:latest,docker:1.10.3-dind,1.10.3 -i golem-distribution:latest,registry:2.2.1 .` -## Running manually outside of Docker -### Install Docker Compose +#### Use golem caching for developing tests -[Docker Compose Installation Guide](https://docs.docker.com/compose/install/) +Golem allows caching image configuration to reduce test start up time. +Using this cache will allow tests with the same set of images to start +up quickly. This can be useful when developing tests and needing the +test to run quickly. If there are changes which effect the image (such as +building a new registry image), then startup time will be slower. -### Start compose setup -``` -docker-compose up -``` +Run this command multiple times and after the first time test runs +should start much quicker. +`golem -cache ~/.cache/docker/golem -i golem-dind:latest,docker:1.10.3-dind,1.10.3 -i golem-distribution:latest,registry:2.2.1 .` -### Install Certificates -The certificates must be installed in /etc/docker/cert.d in order to use TLS -client auth and use the CA certificate. -``` -sudo sh ./install_certs.sh -``` - -### Test with Docker -Tag an image as with any other private registry. Attempt to push the image. - -``` -docker pull hello-world -docker tag hello-world localhost:5440/hello-world -docker push localhost:5440/hello-world - -docker tag hello-world localhost:5441/hello-world -docker push localhost:5441/hello-world -# Perform login using user `testuser` and password `passpassword` -``` - -### Set /etc/hosts entry -Find the non-localhost ip address of local machine - -### Run bats -Run the bats tests after updating /etc/hosts, installing the certificates, and -running the `docker-compose` script. -``` -bats -p . -``` - -## Configurations - -Port | V2 | TLS | Authentication ---- | --- | --- | --- -5000 | yes | no | none -5002 | yes | no | none -5440 | yes | yes | none -5441 | yes | yes | basic (testuser/passpassword) -5442 | yes | yes | TLS client -5443 | yes | yes | TLS client (no CA) -5444 | yes | yes | TLS client + basic (testuser/passpassword) -5445 | yes | yes (no CA) | none -5446 | yes | yes (no CA) | basic (testuser/passpassword) -5447 | yes | yes (no CA) | TLS client -5448 | yes | yes (SSLv3) | none