-p-500.jpg)
In micro-services driven architectures, a Service Catalog becomes a critical asset for software engineering teams. It provides a structured inventory of all the services, including their metadata, dependencies, teams responsible, related links and the environments they’re deployed in.
Lately, Service Catalogs are confused with “Internal Developer Portals”, but the latter being considered as a super set of the former. In this article, we will focus on Service Catalogs.
Internal Developer Portals include a lot more capabilities, like enabling developers with self-serve flows to scaffold and create a new service. You can read a detailed article on Internal Developer Portals, here.
Imagine you are a software engineer in a team of 100+ developers (possibly 1000+). You own a specific end-user operation and are building a new feature. You are facing an issue with the authentication layer in the application. You are trying to figure out whom to contact or where to find the service docs.
In a monolithic architecture with one repo, you could traverse the code (even this could be really hard) but in a microservices, the service could be in a different repo with abstractions — where or how to start can get non-trivial.
Guess what, you don’t have to ask your manager or peers to figure out whom to contact if you have a service catalog. The Service Catalog acts to unify all infrastructure tooling, services, and documentation into a single place. That said, some of the absolute benefits of using a service catalog are as follows:
1. Improved discoverability:
As a developer, you might feel that in this new feature you are developing, it’s essential to build a compression capability. Well what if another sister team has already built that 3 years ago? And you could use it with slight modification?
What if there’s a way to know what’s existing that can be reused without requiring to ask this in a full team meet? Yes. That’s what service catalog can help you do with just a simple search.
2. Tracking dependencies & related resources:
Well now that you landed on this old_compression_service, you decide to make the changes. Cut to 1 week later, you need to get it merged. But are you confident to make the PR? Have you done enough testing? Are you sure it won’t break anything big?
Your service catalog typically has link to documents (or documents itself) about:
3. Measuring Compliance, Security & Quality:
Now, say you created a new service. While deploying the new service for the first time, where does the service stand w.r.t it’s compliance, security & quality requirements?
Well it absolutely depends on your company and most Service Catalogs enable you to create a “scorecard”. You can create a custom definition of what your team considers a good benchmark by using a combination of DORA metrics, Operational maturity (has alerts configured? has dashboard links?), Health KPIs, security scans, and more.
I’ll now dive deeper into sharing insights about each of the below mentioned 8 tools, going through them one-by-one:
While evaluating Service Catalogs tools, it will be likely that you will come across Backstage. But Backstage is **not** a Service Catalog or even a Developer Portal. Open-source and created by Spotify, Backstage calls itself a ***“framework to create your own Internal Developer Portal”***. It has a hyper customization flexibility (coming at the cost of effort), it has a plugin ecosystem (with ~200 integrations) allowing integrations custom to your situation and has a thriving community.
1. Community: Vibrant Open Source project with active contributors and long list of adopters
2. Flexibility: Suitable for companies looking for a flexible framework to build their own internal developer portal. While there is a learning curve initially, some folks end up loving it.
3. Ecosystem: Large pool of ~200 plugins and connectors created by both community & vendors, enabling you to make the catalog rich with automation
While Backstage is great once implemented, there are couple of common challenges that teams often face getting off-the-ground with it:
1. Built in JS: To setup & use Backstage.io, your team will need to spend time coding in React / Node — as the entire stack is built on it and often a hurdle on why companies decide to not go ahead with Backstage. While any developer should ideally be able to code in any language, there is typically a learning curve and bandwidth that needs to be allocated for that. Many platform & devOps engineers (who often end up owning the Service Catalog & Internal Developer Portal charter) decide to not pick it up because of the same.
2. Additional effort for plugins: While there are some users who appreciate the flexibility, adding every plugin requires additional code effort.
3. Enterprise Functionality Development: Backstage doesn’t provide enterprise functions like SSO and audit logs out of the box. There are some teams that found that it was taking them longer than they planned to develop them and hence, decided to move with an alternate solution.
4. Scorecards: As Backstage.io is a framework, it doesn't offer a scorecards function which could otherwise act as a measure for organizations to drive security standards and operational maturity requirements across teams.
Free (Open Source with Apache 2.0 License)
Cortex is a YC-backed startup founded in 2019. Based out of San Francisco, Cortex’s Service Catalog is designed to provide immediate visibility of all software entities to developers, including but not limited to documentation, change history, dependencies, and ownership information. Being a leading commercial SaaS provider for this category, Cortex has a lot of user love behind it — especially for their integrations.
1. Powerful Scorecards: Compared to other commercial tools, Cortex offers scorecards where evaluation criteria can be based on metrics or custom data points using their native CQL (Cortex Query Language). This empowers users to add custom metrics like MTTR, SLOs, Apdex scores, etc. within their scorecard.
2. Cookiecutter-based Scaffolding: Cortex has a Service scaffolding feature based on Cookiecutter, an open source project to define boiler plating for any new service.
3. Monorepo support: Across all of their VCS integrations (BitBucket, Github, Gitlab, etc.), Cortex has specific mention with support for monorepos.
4. SSOs: Okta, Azure AD and Google supported.
1. Actions: Actions are a recent release in Cortex and have limited functionality with regards to the pre-defined templates,
2. No self signup: Cortex is an enterprise offering and requires setting up a call before a user can try the platform. They do have a platform demo on Youtube though.
There is no estimate or indication of the pricing by Cortex, publicly available.
Website: https://www.cortex.io/
Started in 2018, OpsLevel is based out of Toronto, Canada. OpsLevel is a SaaS platform focused on service catalogs, scorecards and service scaffolding capabilities.
1. Rubrics & Scorecards: OpsLevel has 2 concepts — Rubrics & Scorecards. While Scorecards are similar to how they exist on other platforms, Rubrics are a 2nd order drill down into defining the parameters your team wants to use & the checks it wants to put to track service quality. The emphasis here is to enable multi-fold evaluation parameters w.r.t security, scalability, reliability and any other category your team feels is important.
2. Security oriented integrations: OpsLevel integrations are deeply focused on security & designed to enable measuring security — the same can be seen with their extensive integrations with code quality, vulnerability tools like Aqua Sec, SonarQube, Veracode.
3. Actions: Actions related to self-service for developers for day-to-day operations are quite powerful and deep across different components for Self-hosted available.
The Scorecards in OpsLevel have powerful filters and checks but limited aggregation and calculations that are allowed on timeseries or dynamic data from external sources (e.g. MTTR / Service ApDex, etc.)
There is no estimate or indication of the pricing by OpsLevel, publicly available. OpsLevel provisions a 14-days trial period so you can try out their platform without having to setup a call or credit card information.
Website: https://www.opslevel.com/
Part of the Datadog observability platform, Datadog’s service catalog integrates closely with monitoring tools to provide real-time insights into service performance. It's ideal for teams that already rely on Datadog for monitoring and want to enhance service visibility.
1. Free: Complimentary with the APM services
2. DevEx: No change of platform or an additional platform for developers
3. Auto-discovery: Auto-discovers the services using the pre-existing APM instrumentation
1. Limited Scorecard integrations: While you can leverage almost any information from within Datadog for usage in Scorecard creation, there are limited integrations with 3rd party Static Code Analysis tools and security tools.
2. No scaffolding or actions: Datadog does not provide scaffolding or developer self-serve workflows as actions like other tools in the category.
No additional charges
Port is an Internal Developer Portal founded in Nov-2021 and HQ in Tel Aviv, Israel. It is most often recommended tool in the community due to ease of trying and a freemium option. It provides a service catalog, a self-service developer experience platform and automations associated with it.
1. Self-serve + Freemium Plan: Port has a freemium plan and does not require a credit card to signup. It is free upto team of 15 developers. Post that, they charge ~$25/developer/month.
1. Self-hosted available ✅
3. Ease of onboarding: I signed up on Port and found it intuitive and easy to get started. Completely worth evaluating as an option if it fits your requirement & time-to-value.
1. Limited Capability in Scorecards: You will be able to create scorecards but they are not as comprehensive as some of the other providers like Cortex. For instance, the rules here are limited to conditions on the fields defined (is there a Slack channel defined? Are alerts defined?) within a Service Catalog and does not support complex aggregations or functions on SLOs, MTTRs or other custom metrics.
2. Budget: In case you are a large enterprise, you might want to evaluate the cost of using Port and it’s budgetary.
Port has a freemium product offering with a free plan upto 15 editing/contributing developers in a team and $25/month/developer post that.
Website: https://www.getport.io/
Compass is a Service Catalog offering by Atlassian — the parent company behind products like JIRA, OpsGenie & Confluence. The product is an inspired by their internal portal that’s used across Atlassian teams. The tool does not call itself a Service Catalog or Internal Developer portal but a Developer Experience Platform.
1. Deep integrations within Atlassian ecosystem — in case you are already using Forge or BitBucket, it might be added value for your team to automate related workflows.
2. Cost effective offering compared to other alternatives in the market.
3. If you’re using Atlassian already, getting started with another of their service could be relatively easier than onboarding a new vendor.
1. Atlassian Compass moved out of beta into general availability on October 17, 2023. Given it’s freshness, it’s scorecard is still maturing and does not have complex actions or checks that are significantly few. (especially w.r.t integrations with Code Analysis & Security tools). Read more about a user checking in the Compass Community about features that it couldn’t find in the tool yet.
2. No native scaffolding or self-serve actions: In case you want to extend your Service Catalog into a Internal Developer Portal, Compass does not offer features for it yet. Given their positioning as DevEx platform and not internal developer portal, it is not clear if it’s a part of their future roadmap either.
3. Monorepo — Compass does not have out of the box compatibility with Monorepo and requires custom metrics to be instrumented to track it.
4. Self-hosted instance not available.
Considered to be cost effective compared to the cost of managing it in-house (~$7/month/user)
Started in June 2020, Roadie is a SaaS version of Backstage — removing the operational overhead of self-hosting while retaining the benefits of Backstage's ecosystem. It's particularly beneficial for teams seeking a quick deployment with minimal setup effort.
1. Low maintenance overhead: Roadie provides a managed version of Backstage so in case you want to leverage the power of OSS-driven Backstage, Roadie can be an easy alternative.
2. Tribal knowledge: Roadie team helps with best practices & faster go-live given their experience in deploying Backstage across multiple teams.
1. Limited Scorecards: While Roadie team have created Scorecards (which are not defacto available in Backstage), the integrations & checks supported here are limited. This means it’ll still require some bit of custom development (on Roadie team or your team?) to get to a quality that is otherwise promised by commercial tools.
2. Cost: Roadie charges about $20/user/month so in case you are restricted on financial budget but have access to engineering talent, it might be worth exploring developing it inhouse.
3. No self-hosted option available.
As per their website, the Roadie platform comes at a cost of ~$20/developer/month.
Website: https://roadie.io/
While basic, spreadsheets can serve as a starting point for small teams or projects with manageable numbers of services. However, they quickly become unwieldy as the number and complexity of services grow.
Quick Start: Collating information in tabular form at small scale is easy with Spreadsheets.
1. Lack of integrations: As Spreadsheets would require manual updation, it might not be suitable if you’re looking for auto-updation of all the assets & related resources.
2. Limited interface: Beyond a small team, Spreadsheet might not be very helpful or extensible w.r.t extending to an internal developer portal.
Free
The list is of 8 tools. What is this 9th one? If you feel after reading the top 8 that your answer is NOTA (None of the above), you could explore building a DIY Internal Developer Portal.
In case of doing so, here are some of the top reasons why other companies are doing that:
1. If you feel that your team is opinionated to not using Backstage due to it’s dependency on Javascript
2. If you have too many internally built tools for CI / CD and usual developer workflows and not too many options in Backstage plugins
3. If your team’s size can justify dedicating a few full-time resources to building it internally.
While building an internal developer portal in-house for scaffolding and developer self-service might be a suitable option, it is worth re-evaluating the cloud tools available given the extensive integrations with other commercial SaaS offerings that they have in the market.
Service Catalogs are a critical component for any large scale engineering team with microservices architecture. In case you are a small team, it might make sense to start off with Datadog Service Catalogs or spreadsheets or Atlassian Compass. In case you are looking for a feature rich implementation with low maintenance and high time-to-value, OpsLevel, Cortex, Port or Roadie might be suitable. In case you are looking for a completely flexible OSS platform to build internally and extend to become an Internal Developer Portal, Backstage could be a good option for you.
