Making gRPC requests with grpcurl

Hey folks, so this is just going to be a short video to walk through gRPC Curl. This is a command line tool which is open source and it takes inspiration from the curl command and basically allows you to interact with your gRPC services via the command line. This is really useful for testing or debugging or just general interaction with gRPC APIs, and it allows you to do these tests without having to write any client code yourself.

So in this video, we're going to walk through the installation process and then go through some basic usage to see how we can make different types of calls using gRPC Curl. The tool is available for all major operating systems and there's a few different ways that you can install it: you can either download the binary from the releases page, use brew if you're using Mac, install it via Docker and run it through Docker, or build it from source using go install.

For this video, I built a simple Hello World service, one that we've seen in plenty of previous videos as well. Let's start out by running the server. Now that it's up and running, we'll create a very basic request to make a "say hello" call against our server. We start by calling the grpc-curl command and, because we're not using TLS for this, we'll pass a plain text flag. Next, we have to provide an import path to our protobuf directory where our protobufs live - in our case we're just passing "proto" which is this directory here.

Then we provide the protobuf file name, which in this case is hello.proto. Next, we need to pass a JSON representation of our request. Similar to curl, we use the -d flag, and inside that we can put a JSON representation of our protobuf request. For this, we have a single string which is a name, so we'll pass "name": "Chris". After that, we provide the address which will be localhost:50051.

Finally, we need to pass the package, the service, and the RPC name. This will be "hello" which is the package, "HelloService" which is the service, and "SayHello" which is the RPC name, in the format of hello.HelloService/SayHello. That should be the entire command to make a simple gRPC call, and as you can see we get the response back which is the message "hello Chris".

Now, it's slightly inconvenient that we have to pass the protobuf import path and the protobuf file. There is something we can do on the server side to avoid this when using our gRPC curl command: use reflection. To register reflection, there is a package in the gRPC library called reflection. This is just the regular Google gRPC library that we've been using throughout this course, and we just need to call the reflection.Register function and pass our gRPC server into it.

What reflection does is enable a gRPC service on our server which provides information about the APIs that the server exposes. This is really useful for testing locally and making calls against a server, but it's worth noting that this will expose information that you probably don't want exposed in your public or production server, so I wouldn't recommend using this in production. However, for testing and maybe even in a staging environment, this is fine.

I've already enabled this on our server, so we can modify our command and just remove the proto flag and the import flag. Running it now, we still get our response as before. To prove that this is due to reflection, if I comment out the reflection registration and restart our server, this will fail because we're not supporting the reflection API.

There are some other useful commands as well in gRPC curl. The list command will show all the services that are exposed on the server. We can call this by doing grpc-curl with the plain text flag, the address, and then the word "list". As you can see, it lists two services for reflection (because we've enabled reflection on our server) and our hello service as well. This is quite useful if you have a server with many different gRPC services exposed, as you can check which services are actually up and running.

Another useful command is the describe command. This is similar to list but it will describe all of the available services and methods on the server. When you run this, you can see it first describes the two reflection services with their service definitions and RPCs, and then does the same for our hello service. By using this, you can see exactly what RPCs are exposed along with their requests and responses.

So far we've looked at how to make calls against a plain text server, but of course we might have a server running with TLS and need to make encrypted requests. For this example, I've added an environment variable called TLS_MODE and we can configure this to either enable server-side TLS or MTLS on our server. I've provided some certificates here as well that we can use when making calls through gRPC curl.

Let's toggle the TLS_MODE to "tls" and restart the server. The gRPC curl command is similar to before - we'll first pass in our JSON request object with the name. Then we need to provide a CA cert as a trusted authority, which will be used to verify the service certificate when it gets passed back to the client. We'll use the cacert flag and pass the path to our CA cert from the certs directory.

Just to prove this is running in TLS mode, if we remove the cacert flag, this should fail - and as you can see it does fail with "certificate not trusted" because we didn't pass in that trusted certificate authority cert. Now let's look at MTLS as well. We'll start the server in MTLS mode. The command is similar, but now we also need to pass the client certificates. We use the cert flag to set the client cert and the key flag for the client key file.

This should make a successful call to the gRPC server using MTLS. To prove it's running in MTLS mode, if we try running this without the client certs and just with the CA cert, it should fail - and it does time out because it couldn't verify the client certs.

So here were just some basic examples of how to use gRPC curl. This is a really great tool for making requests against your server without having to write your own client code. If you're like me, you'll find yourself using this a lot as you're developing gRPC applications because it's very easy to use. In the coming lessons, we're going to keep looking at how we can test our gRPC services, mainly focusing on how we can write integration tests and unit tests.