Why “running service” should be part of the data model in your internal developer portal

Introduction

‍

We’re ambivalent. On the one hand, we would like the setup of our internal developer portal to be super quick. We want you to choose some blueprints (which represent the data model in Port), use an exporter to get the data inside, and voila - watch your software catalog come to life. On the other hand, we think it’s important to stop for a moment to think about the data model you want reflected in your internal developer portal. This post will explain why the data model matters, how it makes the software catalog better, and will do all that featuring our favorite data model blueprint: running service. 

‍

Data models and internal developer portals 

An internal developer portal has a software catalog at its core. While you may imagine a relatively “flat” catalog with basic data - ownership, on-call, some logs, software catalogs are actually pretty rich in terms of the data they contain, and can provide significant value. They can serve as a general purpose software catalog containing all metadata and support many use cases, far beyond improving the developer experience, as we’ll show below.

‍

But initially, they are used by developers and operations people to understand the SDLC, in context. 

‍

Spotify’s Backstage set out to solve this very same data model problem and defined 6 kinds of data model elements for a software catalog. They are:

• Component
• API
• Resource
• System
• Domain; and 
• Group

‍

Backstage’s data model is a C4 model adaptation, and covers most data model needs. But one part is missing, and this is the “running service” element. Let’s take a look at it.

‍

{{cta_6}}

‍

What is the running service blueprint?

While it is natural to set up blueprint elements for services and the environments they run in, the running service represents the fact that one single service is usually deployed to multiple environments at the same time. For example, a service can run in a development, staging, or production environment. If it’s a single-tenant architecture, each service is deployed in many customer environments. So if we want the software catalog to track a version of a  service in a given environment, what we want to track is the “running service” - to see a “live” version of a service running in a specific environment. It will include references to the service, environment, and deployment, as well as real-time information such as status, uptime, and any other relevant data. 

‍

A running service entity in the software catalog

Let’s look at a specific example. We have now ingested data from our K8s, GitOps, CI/CD etc - and it has populated into the predefined running service. This service (an “entity” in Port) is called “rating-production”. Some of its properties can only appear in running services. You can see the image tag, the datadog logs and other data showing how the service behaves in this specific environment - all of which can only be shown in the context of the running service. This type of view can’t happen in a “classic” software catalog that doesn’t show running services.

‍

‍

Using CI/CD and Port’s entities to deploy running services 

One of the more interesting use cases for Port’s internal developer portal is accessing its general purpose software catalog within existing CI/CD workflows. We call this workflow automation.

‍

Let’s imagine a developer uses a self-service action - “deploy service in an environment” (you see what it looks like in our live demo). The developer selects the service to be deployed and the environment - test, QA, production. The CI/CD needs to set this up - and it uses Port’s software catalog to pull data about the specific service, environment, cluster and cloud account, check whether it is subject to nightly shutdown, is the service production critical, what is the deployment strategy and more. It then deploys accordingly. Since Port has entities for all such environments, and they are built as a graph, resulting in an elegant solution. 

‍