grpc

README

grpc

import "github.com/blueprint-uservices/blueprint/plugins/grpc"

Package grpc is a plugin for deploying an application-level Golang service to a gRPC server.

Prerequisites

To compile a Blueprint application that uses grpc, the build machine needs to have protocol buffers and the grpc compiler installed. Installation instructions can be found on the gRPC Quick Start.

Wiring Spec Usage

To use the grpc plugin in your wiring spec, instantiate a workflow service and then invoke Deploy:

grpc.Deploy(spec, "my_service")

Any application-level service modifiers (e.g. tracing) should be applied to the service *before* deploying it with gRPC.

After deploying a service to gRPC, you will probably want to deploy the service in a process.

Example

The SockShop grpc wiring spec uses the grpc plugin.

Configuration and Arguments

The gRPC server requires an argument `bind_addr` to know which interface and port to bind to. This is a host:port string, typically looking something like "0.0.0.0:12345"

The gRPC client requires an argument `dial_addr` to know which hostname and port to connect to. This is a host:port string, typically looking something like "192.168.1.2:12345" or "myhost:12345"

Blueprint can automatically generate these addresses in some circumstances, but usually they have to be specified by you when running the application, such as when running processes or containers. For example, the process and container plugins will complain if arguments are missing.

Artifacts Generated

The plugin will generate a server-side handler that creates and runs a gRPC server, with the service as the request handling logic. The plugin will also generate a client implementation for other services to call the service. The plugin also generates marshalling code for packing arguments into protobuf structs and vice versa. This is implemented within the grpccodegen package.

To use this plugin requires the protocol buffers and grpc compilers are installed on the machine that is compiling the Blueprint wiring spec. Installation instructions can be found on the gRPC Quick Start.

Index

• func Deploy(spec wiring.WiringSpec, serviceName string)

func Deploy

func Deploy(spec wiring.WiringSpec, serviceName string)

Deploy can be used by wiring specs to deploy a workflow service using gRPC.

serviceName should be the name of an applciation-level service; typically one that was defined using workflow.Define.

Like many other modifiers, GRPC modifies the service at the golang level, by generating server-side handler code and a client-side library. However, GRPC should be the last golang-level modifier applied to a service, because thereafter communication between the client and server is no longer at the golang level, but at the network level.

Deploying a service with GRPC increases the visibility of the service within the application. By default, any other service running in any other container or namespace can now contact this service.

Generated by gomarkdoc

Documentation

Overview

Package grpc is a plugin for deploying an application-level Golang service to a gRPC server.

Prerequisites

To compile a Blueprint application that uses grpc, the build machine needs to have protocol buffers and the grpc compiler installed. Installation instructions can be found on the gRPC Quick Start.

Wiring Spec Usage

To use the grpc plugin in your wiring spec, instantiate a workflow service and then invoke Deploy:

grpc.Deploy(spec, "my_service")

Any application-level service modifiers (e.g. tracing) should be applied to the service *before* deploying it with gRPC.

After deploying a service to gRPC, you will probably want to deploy the service in a process.

Example

The SockShop grpc wiring spec uses the grpc plugin.

Configuration and Arguments

The gRPC server requires an argument `bind_addr` to know which interface and port to bind to. This is a host:port string, typically looking something like "0.0.0.0:12345"

The gRPC client requires an argument `dial_addr` to know which hostname and port to connect to. This is a host:port string, typically looking something like "192.168.1.2:12345" or "myhost:12345"

Blueprint can automatically generate these addresses in some circumstances, but usually they have to be specified by you when running the application, such as when running processes or containers. For example, the process and container plugins will complain if arguments are missing.

Artifacts Generated

The plugin will generate a server-side handler that creates and runs a gRPC server, with the service as the request handling logic. The plugin will also generate a client implementation for other services to call the service. The plugin also generates marshalling code for packing arguments into protobuf structs and vice versa. This is implemented within the grpccodegen package.

To use this plugin requires the protocol buffers and grpc compilers are installed on the machine that is compiling the Blueprint wiring spec. Installation instructions can be found on the gRPC Quick Start.

Index

• func Deploy(spec wiring.WiringSpec, serviceName string)

Functions

func Deploy

func Deploy(spec wiring.WiringSpec, serviceName string)

Deploy can be used by wiring specs to deploy a workflow service using gRPC.

serviceName should be the name of an applciation-level service; typically one that was defined using workflow.Define.

Like many other modifiers, GRPC modifies the service at the golang level, by generating server-side handler code and a client-side library. However, GRPC should be the last golang-level modifier applied to a service, because thereafter communication between the client and server is no longer at the golang level, but at the network level.

Deploying a service with GRPC increases the visibility of the service within the application. By default, any other service running in any other container or namespace can now contact this service.