diff options
author | Yong Ni <yongni@google.com> | 2017-05-09 18:12:10 -0700 |
---|---|---|
committer | Yong Ni <yongni@google.com> | 2017-05-19 09:01:24 -0700 |
commit | b2e4bfa1ef0c10a1ad363c655d2f74f1ab9e5790 (patch) | |
tree | 9777a5170d99c55f6b054d375c7935952339876f /tools/interop_matrix/README.md | |
parent | af3cc761adfd06b7620b77d70e87640b7a341ba1 (diff) |
Merge matrix feature branch into master.
Features included in this merge:
- Added script to build and upload docker image for matrix test.
- Added script to create test cases and created go__master testcases based on it.
- Created dictionary for runtimes and gRPC releases for supported languages.
- Added go 1.7 and 1.8 Dockerfile/templates.
See tools/interop_matrix/README.md for details.
Diffstat (limited to 'tools/interop_matrix/README.md')
-rw-r--r-- | tools/interop_matrix/README.md | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/tools/interop_matrix/README.md b/tools/interop_matrix/README.md new file mode 100644 index 0000000000..8493099d1a --- /dev/null +++ b/tools/interop_matrix/README.md @@ -0,0 +1,40 @@ +# Overview + +This directory contains scripts that facilitate building and running gRPC tests for combinations of language/runtimes (known as matrix). + +The setup builds gRPC docker images for each language/runtime and upload it to Google Container Registry (GCR). These images, encapsulating gRPC stack +from specific releases/tag, are used to test version compatiblity between gRPC release versions. + +## Instructions for creating GCR images +- Edit `./client_matrix.py` to include desired gRPC release. +- Run `tools/interop_matrix/create_matrix_images.py`. Useful options: + - `--git_checkout` enables git checkout grpc release branch/tag. + - `--release` specifies a git release tag. Make sure it is a valid tag in the grpc github rep. + - `--language` specifies a language. + For examle, To build all languages for all gRPC releases across all runtimes, do `tools/interop_matrix/create_matrix_images.py --git_checkout --release=all`. +- Verify the newly created docker images are uploaded to GCR. For example: + - `gcloud beta container images list --repository gcr.io/grpc-testing` shows image repos. + - `gcloud beta container images list-tags gcr.io/grpc-testing/grpc_interop_go1.7` show tags for a image repo. + +## Instructions for adding new language/runtimes* +- Create new `Dockerfile.template`, `build_interop.sh.template` for the language/runtime under `template/tools/dockerfile/`. +- Run `tools/buildgen/generate_projects.sh` to create corresponding files under `tools/dockerfile/`. +- Add language/runtimes to `client_matrix.py` following existing language/runtimes examples. +- Run `tools/interop_matrix/create_matrix_images.py` which will build and upload images to GCR. Unless you are also building images for a gRPC release, make sure not to set `--gcr_tag` (the default tag 'master' is used for testing). + +*: Please delete your docker images at https://pantheon.corp.google.com/gcr/images/grpc-testing?project=grpc-testing afterwards. Permissions to access GrpcTesting project is required for this step. + +## Instructions for creating new test cases +- Create test cases by running `LANG=<lang> [RELEASE=<release>] ./create_testcases.sh`. For example, + - `LANG=go ./create_testcases.sh` will generate `./testcases/go__master`, which is also a functional bash script. + - `LANG=go KEEP_IMAGE=1 ./create_testcases.sh` will generate `./testcases/go__master` and keep the local docker image so it can be invoked simply via `./testcases/go__master`. Note: remove local docker images manually afterwards with `docker rmi <image_id>`. +- Stage and commit the generated test case file `./testcases/<lang>__<release>`. + +## Instructions for running test cases against a GCR image +- Run test cases by specifying `docker_image` variable inline with the test case script created above. +For example: + - `docker_image=gcr.io/grpc-testing/grpc_interop_go1.7:master ./testcases/go__master` will run go__master test cases against `go1.7` with gRPC release `master` docker image in GCR. + + +Note: +- File path starting with `tools/` or `template/` are relative to the grpc repo root dir. File path starting with `./` are relative to current directory (`tools/interop_matrix`). |