Question: How to use grpc_api_configuration when using grpc-agteway remote plugin?

[DGuhr]

📚 Documentation

Hi 👋 I want to dockerize the generation of gateway code for my makefile, using the bufbuild/buf docker container and remote plugins. Now I struggle with generating the gateway code and cannot find a good doc on that one, so I added it under "documentation" for now.

My config in buf.gen.yaml is:

...
  - plugin: buf.build/grpc-ecosystem/gateway
    out: gen
    opt:
      - paths=source_relative
      - grpc_api_configuration=gw_mapping.yaml
...

and I've put everything in a flat folder structure to try it out.

Then i cd inside that folder and run docker run --rm -v `pwd`:`pwd` -w `pwd` bufbuild/buf generate .

Result: It generates the .pb.go and _grpc.pb.go in a former step also using remote plugins, so I guess that works generally.

But: It always fails with Failure: plugin "buf.build/grpc-ecosystem/gateway:v2.15.2" failed: failed to read gRPC API Configuration description from "gw_mapping.yaml": open gw_mapping.yaml: no such file or directory and tbh I have no clue if what I try to achieve here is even possible :) The examples at https://github.com/grpc-ecosystem/grpc-gateway#usage-with-remote-plugins don't use it. So would be great to clarify!

[johanbrandhorst]

Hi. It's not possible to use an external configuration file with the Buf remote plugins, unfortunately. Your best option is to either stop using a separate file and move to annotations, or use a local plugin. This is because this option to the grpc-gateway breaks the contract for running protobuf plugins, and it's not Buf's fault. Do you think we should add some documentation to explain this problem to users?

[DGuhr]

Hi @johanbrandhorst, understood, thank you for the fast response!

I am new to the whole protobuf/grpc world, so for me it wasn't clear that using the config file violates the remote plugin contract. I'd say yes, add a note that grpc_api_configuration files are not usable in that case would be nice :)

On a sidenote: Do you have an idea how one could use bufs docker image with grpc-gateway/openapiv2 with local plugins? I try to make the generation as easy and deterministic as possible, no matter the devs system, so ideally everyone just uses make proto-gen or sth and *.pb.gw.go and the yaml are generated. :)

[johanbrandhorst]

I actually wrote a blog post on this very topic 😄: https://jbrandhorst.com/post/plugin-versioning/.

For the docs, would you be willing to contribute an update to our README or docs to clarify this behavior for others?

[DGuhr]

thanks for the blogpost! opened a PR :)