Cloud Native Computing Foundation gRPC Conf 2020, 5 Aug 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Stop Breaking the Proto! Designing for Change in an Microservices World - Ryan Michela, Salesforce

Description

Stop Breaking the Proto! Designing for Change in an Microservices World - Ryan Michela, Salesforce

What's worse than having to deploy ten microservices? Having to deploy ten microservices at exactly the same time. When every change is a breaking API change, every deploy is a lockstep deploy. In this talk we explore techniques and best practices for evolving protobuf contracts without breaking downstream callers. We start by looking at what constitutes a breaking change, and then explore tactical ways to avoid breaking the service contract. Finally, we will dive into proto design patterns that can minimize the need to break our API contracts. Apply the techniques in this talk and never worry about breaking your downstream API callers again.

A

Stop breaking the proto designing for change in a microservices world, hello, everybody, my name is ryan michella and I work for salesforce building service meshes.

A

I've been building with grpc for four years now and started the reactive grpc project to bridge grpc and reactive programming technologies together in java.

A

This talk is about designing services using grpc to maximize the resiliency to change grpc services change all the time. We learn more about our problem space and need to refactor our contracts. We add new features to our services and need to expose them from within an api.

A

We discover our services have become too complicated and need to divide them into smaller independent parts. Changing our services is inevitable.

A

How we anticipate this change and prepare for it makes the difference between a small refactoring and a ground-up rewrite in this talk, we'll look at techniques for accommodating change in our services, we'll take advantage of the advantage of the capabilities afforded to us by grpc, we'll look at how proto design techniques for keeping our service contracts healthy in the long term.

A

We'll look at project design techniques that help our code base, adapt to changing requirements and, finally, we'll look at contract versioning techniques to help us stay sane, as we upgrade our system before we dive in. I find it helpful to review what makes a service here's my definition.

A

A service is a versionable bounded context of functionality, exposing a well-defined public contract over standardized plumbing and encapsulating a single cohesive concept. That's a lot but note how it doesn't say anything about deployment. Monoliths and microservices are just different ways to package services.

A

While this talk focuses on microservices, the guidance applies equally well to monoliths.

A

Three aspects of this definition pertain directly to grpc.

A

A service needs to have a well-defined, explicit contract that defines all of the operations and data structures needed to interact with the service. This car, this contract serves as a separate the external api from the internal implementation details.

A

Ideally, no special knowledge should be needed to call the service outside of what's in the contract. This means no mandatory, metadata or magic request. Headers. It's also important for a service to be independently versionable, so it can evolve separately from its dependencies. Independent versioning means one service can expose multiple versions of its contract simultaneously.

A

For example, a service might implement credit card processing, v1 and v2 contracts, while having 15 independent binary releases over time. Finally, a service should embody a single, cohesive concept. Cohesion is a common ideal in software and helps us prevent service contracts from turning into a dumping ground of unrelated operations.

A

Grpc is an ideal fit to the service definition with many of its properties aligning nicely to what we want. For example, grpc is contract. First protofiles are independently versionable and cleanly separate a services contract from its implementation. Details strongly typed with built-in backwards and forwards compatibility, which makes versioning our contracts easier.

A

Finally, grpc is natively multiplexed, which allows multiple allows us to host multiple versions of the same contract in the same process on the same port. This lets us cleanly separate service discovery from version version selection.

A

Now that we've identified what parts of alpha what we want from an ideal service. Let's look at some techniques to get ourselves there, starting with protobuf design techniques.

A

The first thing we want to do is establish rules around proto-contract versioning semantic versioning is a great place to start. When we apply semver to proto-contracts, we can map different kinds of changes to each of the version components.

A

Major versions of a contract are fundamentally incompatible with each other. For example, http 1 and 2. minor changes are interoperable within the same major version series. Minor changes are typically additive in nature, such as adding new fields or operations to a contract. Finally, patch versions are for non-functional changes like documentation, improvements.

A

Once you've established semver as a versioning system for your proto contracts, you should put the major version in the contract and enter the protocol package. Doing so gives us three advantages.

A

First, it's clear from looking at the contract which compatible series of versions the contract belongs to. Second putting the version of the packet in the version in the package makes it easy to multiplex multiple versions of the same contract in a service. Grpc uses the whole package name and operation name when routing requests to an implementation.

A

Putting the version in the package name eliminates any conflict between different version, implementations of an operation with the same name. Finally, putting the major version in the package name prevents type conflicts and generated code. Protoc translates contact contract namespace into code namespace. Creating a unique namespace for each version allows similar types from different versions to co-exist peacefully.

A

With our contract version package sorted out, the next thing we should look at is proto style. Google has published multiple grpc style guides. Sticking to the official style guides ensures consistencies between our protos, helps, avoid some language, specific code generation quirks and prevents unintentionally breaking changes from entering the contract.

A

The open source community has some great automated tools. You can use to enforce style and compatibility checks automatically. The google aip linter and protoloc are two that first come to mind.

A

A common problem with service contracts is that they tend to grow organically over time. They start cohesive, but lose focus as new operations are added one at a time. The contract is soon a mess. It's important to recognize when this is happening and correct it by breaking an unfocused contract into separate cohesive contracts with a new version.

A

This is just like the interface segmentation principle of the solid oop principles. For example, we can split the complex v1 contracts seen here into three cohesive v2 contracts, for each for a facet of the service, crud search and signing clients that need search, but not signing no longer need to import unneeded apis.

A

Applying isp to grpc contracts promotes cohesion amongst each service's contract operations. Furthermore, consumers only reference the subset behavior that they need from a service.

A

This reduces client churn when contract changes happen, because each so us, because each smaller contract can be versioned independently.

A

Ensuring our message types are cohesive is just as important as having a cohesive service, a common mistake when defining services is to share requests and response types, requests and response types should be exclusive to a grpc operation, even if the contents look identical, think of them as parameter lists for their respective functions.

A

Even though two functions share a similar signature, it doesn't mean that their parameter lists are literally the same construct.

A

Keeping separate types gives you the flexibility to augment one operation in the future without impacting the api of other operations. Now this force duplication only goes one layer deep. The type types used by request and response messages can be shared as needed. For example, a find cocktail response and a get cocktail response can both return a recipe object. This sharing is okay, because recipe is part of the domain model, while request and response messages are tightly coupled to the rpc operations themselves.

A

So far, we've focused on techniques for keeping individual proto contracts flexible and accommodating future change. Now, let's look at ways. We can structure our project to ensure we don't paint our code into a corner while our service contracts change.

A

The first and most important rule when coding against grpc is to never pass around proto-generated classes.

A

It seems like a convenient shortcut to use generated protoclasses as your domain objects for data transfer objects, but resist this urge generated protoclasses will come back to haunt you in many ways. First, the generated just make terrible dtos in some languages their api is really unwieldy and the objects themselves are immutable. This really clutters up the code that uses these types second generated. Protoclasses are not often open to expand extension.

A

Adding behavior to these classes is either unnatural in your language or outright impossible, and finally, using generated protoclasses in your logic couples your code to a particular version of the contract.

A

This is a mistake that will bite you the hardest when major version changes needed. If your business logic is defined in terms of v1 generated types, you'll need to do a major rewrite to redefine in terms of v2 generated types and good luck, supporting v1 and v2 types at the same time with the same code.

A

So how can we structure our code so that we never depend on generated protos? I like to use a three module layout when building a service. Let's start with the middle module, the implementation module, the implementation module is pure; it has zero proto or grpc dependencies. It's also where all of our business logic goes. Business operations accept and return only dtos and primitive data types which allows it to be completely unit testable without any references to grpc upstream dependencies. We call like other services or data stores are represented in this module. Using simple type interfaces.

A

Unit tests can mock these interfaces so that the tests are completely self-contained above the implementation module is the api module. This module is where grpc generated proto classes and the grpc server stub lives.

A

No business logic is in this layer. All server stubs delegate to the implementation module below doing proto-dto object translation as needed. If a contract has more than one version, each version's generated stubs call down into the shared implementation. We can implement the adapter pattern where necessary.

A

This way, you don't have to duplicate your business logic between versions. The bottom layer is our dependencies module. This module provides concrete implementations for each upstream dependency used by the logic once again, there's no business logic in this layer just implements the interfaces provided by the implementation module in terms of their upstream services.

A

If you want, you can wrap all three layers in an ioc container to automatically wire them together at runtime.

A

Let's recap: we've looked at techniques for structuring our proto contracts to keep them flexible in the face of change and we've looked at project layout techniques to ensure our code stays just as adaptable, but how do we best manage contract change itself? To answer that question, we have to look at some techniques for managing contract change over.

A

Time the first step to managing contract change is accepting that breaking changes will happen. I've worked on projects before that went on to unnatural lengths to avoid breaking changes.

A

The results were harder to work with, and the breaking change would have been, for example, don't co-mingle versions of the same contract. This would be like putting grpc operations called, get cocktail v1 and get cocktail v2 and get cocktail v3 in the same proto, each with different signatures.

A

Not only does this bloat your contract and to decrease its cohesiveness, but it also makes it nearly impossible to cleanly cut over from one new version to another. Another thing to avoid version is to ver. Another thing is to avoid versioning independent operations instead of the whole contract. This would be like putting get cocktail v2 in a veto, v2 contract all by itself and relying on the v1 contract for everything else.

A

New developers need to reference two different proto contracts to work with your service, while also knowing which v1 operations have been deprecated instead version the entire contract anytime, any operation experiences a breaking change.

A

Unfortunately, versioning a whole contract is painful. There's a new proto to distribute new stubs to write more marshalling code is needed. You need to integrate with your implementation layer.

A

This should be avoided whenever possible, but not to the point of contorting. Your code base additive changes, optional fields and flags can go a long way towards extending the life of your contract. For example, you want to introduce machine translation to your cocktail service.

A

Instead of breaking the whole contract to introduce this capability, you can add a translate to language field. To get contract, get cocktail, operation old clients won't know about this field and won't send it new clients can request translation by setting the field while old clients continue to work. Just as is no breaking changes are necessary.

A

If, however, you decide to break a contract, use it as an opportunity to do the right, refactoring you've held off on frequently breaking a contract with small changes, isn't really annoying to your downstream consumers.

A

As we've seen, service contracts sometimes change in incompatible ways necessitating a breaking change to the contract. Luckily, grpc has some built-in smarts to accommodating running multiple contract versions. Side by side, remember: grpc is natively multiplexing. This means that multiple contract implementations can share the same port and the same process as long as they have different name spaces.

A

If you put the major contract version into the proto namespace, this won't be a problem for you. You just have to implement each server stub independently and wire them up against your shared business logic layer. When working with multiple contract versions, I like to keep three different versions active at the same time, the v current version is what we want our current consumers to use today. The previous version is what callers who haven't upgraded are still using. You may need more than one of these if you have downstream callers who are really slow to upgrade.

A

When you start working on a new version of your contract, you can publish it as a v-next version and only share the contract with select partners. This way you can rapidly iterate on vnext without sacrificing the stability of v current or v previous.

A

I hope you've learned something today and feel more confident in managing change in your services. We've covered proto design techniques for handling change within a contract. We've covered the layout techniques for handling chain, contract change within our code and finally, we've covered contract, versioning techniques for managing changes between contract versions. Over time.

A

If you take nothing else away, remember this. The contract version is not your implementation version. Don't couple the two together change is inevitable. You can either anticipate it in your design or be run over by it when it comes. And, finally, you need to practice deliberate design. Your proto contract is the most important interface to your service. You can change an implementation all you want, but if you break the contract, your changes will affect everyone around.

A

You, we've covered a lot, I'm sure you have questions I'm available on twitter and on the stream to answer them with that. Happy coding.