Merge pull request #1623 from dmcgowan/docker-integration-readme
Integration test readme update
This commit is contained in:
Richard Scothern
commit
d654cfd985
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user