What Is a Microservice Catalog and Why Do You Need One?

Is this story familiar? You and your engineers decide that a microservices architecture is right for your software. You’re humming along, building out everything, but by the fifth or sixth service, you start to notice issues. You realize you can’t find anything. Then you start asking yourself why certain parts of the data are duplicated over there and over there. You notice a service has been failing and wonder, “How long has this been going on?”

I suspect some of these questions are familiar.

Thankfully, there’s something that can help you answer those questions. A microservice catalog can give you a single pane of glass into your system. This blog post will walk you through what a microservice catalog is, why it’s important, and how you can get one for your company.

What Is a Microservice Catalog? The Quick Definition

A microservice catalog is a place where you can see all the different services you’re building and deploying. This gives you one pane of glass that will let you see what applications you have, where the source code for those applications is and how they’re deploying. The catalog can also take on a lot of other types of data that you can centralize to give you a holistic view of everything.

Depending on what your concerns are, you can adapt your catalog to whatever type of critical data you need across your services. The catalog can also help other developers discover what’s already out. For instance, let’s say you had an authentication system deployed. To let other developers discover this service and use whatever API it has exposed, it would be nice if there was a place they could search for and find this service along with its developer documentation. What would be even better is if the catalog had examples and other useful information to let developers get started quickly using this service. The goal is to ensure that this is where developers or anyone else can search, find, and use everything your company has built.

Do I Need a Microservice Catalog for My Organization?

What are the signs that your organization needs a microservice catalog? One thing that’s probably a clear signal is if developers are asking around for information frequently. Instead of having somewhere to look for data or processes, they ask other developers where something is. This is a signal that there needs to be something that all the developers can use to search for their answers first instead of bothering other people about something that a catalog could answer.

Another clear signal is when your organization is growing fast and so are the number of teams you have. As you grow, you’ll experience exponential growth in your communication channels. This isn’t a sustainable approach because communication will get increasingly difficult. Instead, giving people a tool to help ease parts of the communication channels would be beneficial.

A microservice catalog can help you with some communication lines.

A microservice catalog can help you with some of those communication lines. That’s because it has useful documentation for every service. With some work, it’s also self-serviced so that people can browse and find the answer they need without having to get anyone else involved. It empowers people to find the information they need when they need it.

Yet another clear signal is when you finally have enough services that one person couldn’t reasonably keep track of them all. This is a fuzzier metric and will depend on what you’re doing. But if you have so many things that you need more than one person to explain what’s going on, then it’s a good time to start putting a microservice catalog together to keep track of everything.

What Do I Put in a Microservice Catalog?

Let’s summarize some of the use cases for a microservice catalog:

• A single website that can display information for the kind of service or application you deploy.
• Links to the source code and developer documentation.
• Links and endpoint links for API use cases.
• Links to example usages.
• Information and links on the production system.
• Statistics on the performance of the production system.
• Links to the build system that pushes those services or applications to production.
• Anything else that anyone on that team may find helpful for using your services.

As you can see, there’s a wide variety of good use cases for such a product. It helps empower everyone who’s involved and lets people answer their own questions. This product might start small on day one, but you can provide the ability to quickly add information. Then you can allow it to be extended with other sources of information as well. Pretty soon, this tool can become invaluable to your organization.

The ultimate goal will be to get as much useful information here as possible. This will take time and curation of information. You’ll find that some data points will be far more valuable than others. And over time, you’ll home in on what people actually need.

Don’t be afraid to experiment! Add data and information that people consider helpful and get rid of what people judge to be useless. As you grow, keep thinking about how to find the best information.

What Are Some Effective Practices to Follow?

An important feature of these catalogs is to make them authoritative and extendable. You want to ensure that this is the true source of information for any part of your systems. Then on top of that, you want to ensure that people can add, update or even remove parts.

For newer organizations, it’s easier to start with a microservices catalog sooner than later. Once it’s a known source of information, that ball kind of keeps itself rolling.

For newer organizations, it’s easier to start with a microservices catalog sooner than later.

For larger organizations, you’ll have to slowly bake in features until you get mass adoption and usage. That’s not exactly an easy feat. But the important thing is to start small and keep growing the system. Coming up with a simple list of everything a developer deploys to production is a great start. Then add information to each deployable that people regularly look for.

What Are Some of the Challenges?

So, you’ve decided that you want a microservices catalog. What might impede your efforts?

Well, it depends on how well-established your company is in your development practices. Getting anything new in that kind of environment is always a bit of work. There will always be adoption problems because of something new. But this is where you demonstrate the value of the system. First, you try to find a common data point among your services. Then you try to get information into one single easy-to-use place, if possible. That’s how you can start dipping your toe into this idea.

The next problem will be to try to keep things up to date.

In any kind of information system, keeping things from rotting is always a significant task. It takes discipline and organization to ensure success. This is where it makes sense to have things that are easy to update or change — or better yet, having something that automatically updates itself. If much of the data in the system is automated, then no one has to babysit it. However, there will be portions of the system that just need to be manually curated from time to time. This will take discipline to ensure that the information is accurate and correct. As the system gets refined, hopefully the manual work is reduced to as a small a footprint as possible.

Conclusion and Learning More

Hopefully, this blog post has given you an idea of what makes up a good microservice catalog. And maybe it inspired you to start looking at ways to create one.

You’ve got a lot of things to keep track of, so try to make it so you don’t have to keep track of all your different services in special bookmarks or in everyone’s browser. Make the microservices catalog a one-stop shop for every team member. That way, you can ensure everyone on the team can get the answers they need without having to bother others. Also, everyone can get a bird’s-eye view of everything that’s going on.

Finally, do you need help managing your distributed cloud architecture and controlling sprawl? Check out configure8. Unlike container-based solutions that stop at service boundaries, configure8 has built the first universal catalog with a knowledge explorer interface that organizes your entire software development operation — all your services, all your infrastructure, and key data like performance, security, cost, ownership, documentation, dependencies and dependents, in one place.