1# Docker images used for gRPC testing 2 3Most of our linux tests on the CI run under a docker container, since that makes it easier 4to maintain the test environment and the dependencies. Having an easily reproducible test 5environment also make it easier to reproduce issues we see on CI locally. 6 7The docker image definitions we use live under `tools/dockerfile` directory (with the 8exception of `third_party/rake-compiler-dock` docker images). 9 10## Version management 11 12The docker images we use for testing evolve over time (and newer/older versions of it 13might not work with newer/older revisions of our code). 14 15For each dockerfile (which is identified by the directory in which is it located), 16the "current version" that's being used by testing is determined by the 17corresponding `.current_version` file, which contains the full docker image name, 18including artifact registry location, docker image name, the current tag and the 19SHA256 image digest. 20 21Example: 22For `tools/dockerfile/test/cxx_debian11_x64/Dockerfile`, there is a 23`tools/dockerfile/test/cxx_debian11_x64.current_version` file which contains info 24as follows: 25``` 26us-docker.pkg.dev/grpc-testing/testing-images-public/cxx_debian11_x64:[CURRENT_CHECKSUM]@sha256:[CURRENT_SHA256_DIGEST] 27``` 28This info can be passed directly to `docker run` command to get an environment 29that's identical what what we use when testing on CI. 30 31## Updating the images 32 33The authoritative version of docker images we use for testing is stored in artifact registry, 34under the repository `us-docker.pkg.dev/grpc-testing/testing-images-public`. 35 36If you've made modifications to a dockerfile, you can upload the new version of the artifact 37registry as follows: 38 39If you haven't configured authentication in Docker for us-docker.pkg.dev previously, run: 40``` 41gcloud auth configure-docker us-docker.pkg.dev 42gcloud auth login 43``` 44 45Rebuild the docker images that have been modified locally and upload the docker images to 46artifact registry (note that this won't overwrite the "old" versions of the docker image 47that are already in artifact registry) 48``` 49tools/dockerfile/push_testing_images.sh 50``` 51 52Build modified docker images locally and don't push to artifact registry. This option is 53very useful for quick local experiments. The script is much faster if it doesn't have to 54interact with artifact registry: 55``` 56# very useful for local experiments 57LOCAL_ONLY_MODE=true tools/dockerfile/push_testing_images.sh 58``` 59 60## Migrating from dockerhub 61 62In the past, our testing docker images were [hosted on dockerhub](https://hub.docker.com/u/grpctesting), 63but we are in the process of migrating them artifact registry now. 64 65This temporary feature might simplify the migration: 66``` 67# try pull existing images from dockerhub instead of building the from scratch locally. 68TRANSFER_FROM_DOCKERHUB=true tools/dockerfile/push_testing_images.sh 69``` 70