gRPCurl - curl for gRPC

Sun 26 July 2020 by admin

In previous blog post How kubernetes is interacting with docker ? I was writing about dockershim with golang gRPC example code to get list of docker images. This example was trivial but writing code to get it wasn't trival, is there any generic tool to make such requests ? In HTTP world there is a popular tool called curl in gRPC world there is an equivalent of it called grpcurl. It helps to make RPC methods on gRPC server from the cli. So how can we achieve the same results like in my previous blog post ? Installation is pretty straight forward, just download binary. Then download data structure and services from dockershim:

$ wget https://raw.githubusercontent.com/kubernetes/kubernetes/master/staging/src/k8s.io/cri-api/pkg/apis/runtime/v1alpha2/api.proto

download necessary tools to compile proto file into binary form accepted by grpcurl, instruction how to do that is on Compiling your protocol buffers. Then download requirements for this particular proto file gogo/protobuf. Now we can compile proto file into binary format:

$ protoc -I=$GOPATH/src --proto_path=. --descriptor_set_out=api.protoset --include_imports api.proto

using compiled version proto file we can list services

$ grpcurl --protoset api.protoset list
runtime.v1alpha2.ImageService
runtime.v1alpha2.RuntimeService
$ grpcurl --protoset api.protoset list runtime.v1alpha2.ImageService
runtime.v1alpha2.ImageService.ImageFsInfo
runtime.v1alpha2.ImageService.ImageStatus
runtime.v1alpha2.ImageService.ListImages
runtime.v1alpha2.ImageService.PullImage
runtime.v1alpha2.ImageService.RemoveImage
$ grpcurl --protoset api.protoset describe runtime.v1alpha2.ImageService.ListImages
runtime.v1alpha2.ImageService.ListImages is a method:
rpc ListImages ( .runtime.v1alpha2.ListImagesRequest ) returns ( .runtime.v1alpha2.ListImagesResponse );

here we have runtime.v1alpha2.ImageService.ListImages, let's make request:

$ grpcurl -plaintext --protoset api.protoset -unix /var/run/dockershim.sock runtime.v1alpha2.ImageService.ListImages
...
    {
      "id": "sha256:da86e6ba6ca197bf6bc5e9d900febd906b133eaa4750e6bed647b0fbe50ed43e",
      "repoTags": [
        "gcr.io/google-containers/pause:3.1",
        "gcr.io/google_containers/pause-amd64:3.1",
        "k8s.gcr.io/pause:3.1"
      ],
      "repoDigests": [
        "gcr.io/google-containers/pause@sha256:f78411e19d84a252e53bff71a4407a5686c46983a2c2eeed83929b888179acea",
        "gcr.io/google_containers/pause-amd64@sha256:59eec8837a4d942cc19a52b8c09ea75121acc38114a2c68b98983ce9356b8610",
        "k8s.gcr.io/pause@sha256:f78411e19d84a252e53bff71a4407a5686c46983a2c2eeed83929b888179acea"
      ],
      "size": "742472"
    }
...

We can skip compiling proto file, just use plaintext proto file or ask gRPC server directly via reflection. But how can we pass some data to request, grpcurl assist you to get template JSON parameters:

$ grpcurl -msg-template --protoset api.protoset describe  runtime.v1alpha2.ImageStatusRequest
runtime.v1alpha2.ImageStatusRequest is a message:
message ImageStatusRequest {
  .runtime.v1alpha2.ImageSpec image = 1;
  bool verbose = 2;
}

Message template:
{
  "image": {
    "image": "",
    "annotations": {
      "": ""
    }
  },
  "verbose": false
}

now we can compose request:

$ grpcurl -d '{"image": { "image": "gcr.io/google-containers/pause:3.1", "annotations": {  "": "" } }, "verbose": false }' -plaintext --protoset api.protoset -unix /var/run/dockershim.sock runtime.v1alpha2.ImageService.ImageStatus
{
  "image": {
    "id": "sha256:da86e6ba6ca197bf6bc5e9d900febd906b133eaa4750e6bed647b0fbe50ed43e",
    "repoTags": [
      "gcr.io/google-containers/pause:3.1",
      "gcr.io/google_containers/pause-amd64:3.1",
      "k8s.gcr.io/pause:3.1"
    ],
    "repoDigests": [
      "gcr.io/google-containers/pause@sha256:f78411e19d84a252e53bff71a4407a5686c46983a2c2eeed83929b888179acea",
      "gcr.io/google_containers/pause-amd64@sha256:59eec8837a4d942cc19a52b8c09ea75121acc38114a2c68b98983ce9356b8610",
      "k8s.gcr.io/pause@sha256:f78411e19d84a252e53bff71a4407a5686c46983a2c2eeed83929b888179acea"
    ],
    "size": "742472"
  }
}

Comments