Blueprints

Introduction

The goal of an internal developer portal is to provide a product-like experience to developers – so they can easily self-service with less cognitive load.

Blueprints are key in delivering this product-like developer experience. They enable platform engineers and DevOps folks to define the right abstractions for developers and to evolve over time as needs (and the technical environment) change. 

What are blueprints and what can you do with them?

Blueprints are the foundational building blocks of the internal developer portal. They hold the schema of the entities you wish to represent in the software catalog. (For example, you might have a blueprint for packages, K8s clusters, microservices, and VMs – each one defining the metadata associated with these entities.)

Blueprints are completely customizable, and they support any number of properties the user chooses, all of which can be modified as you go.

Just as important as the individual blueprints is the way that they relate to one another (“relations”). Relations are the connections between blueprints, capturing the dependencies between them. Relationships can be single (e.g., a package version to a package) or multiple (e.g.,the packages used by a service), and they enable the representation of the software catalog as a dynamic graph database. 

The backbone of the internal developer portal

Blueprints are critical for building the internal developer portal: 

1. Blueprints describe the data you want inside the software catalog.

The process begins by defining detailed blueprints that describe the characteristics of different assets like microservices, environments, packages, clusters, and databases. The properties should be driven by questions that we’d like to answer (e.g., “who owns an asset?”). Then, real-world entities from your infrastructure are associated with these blueprints, forming the software catalog entities through auto-discovery. You can also use templates inside the product or templates that come with the relevant Port integration (in some cases).

2. Blueprints define self-service actions for developers through the portal.

These actions cover a wide range of tasks, including provisioning, termination, and day 2 operations on any asset exposed in the software catalog. With blueprints, developers can easily interact with the platform, reducing the cognitive load on DevOps teams.

3. Blueprints define metrics and quality standards for catalog entities.

These metrics and standards are formalized via Scorecards. Scorecards can also indicate the health, quality, and readiness of specific elements within the platform. Having a “source of truth” for these metrics enables automated decision-making based on the status of entities, helping ensure compliance and standards. Scorecards also form the basis for driving engineering quality initiatives.

Blueprints support a product-like developer experience

So what makes blueprints powerful? In a nutshell, they help platform engineering and DevOps build a data model to answer the right questions for your engineering org – providing flexibility and context that support self-service. 

Letting you define your own data model - Your data model should be driven by the specific questions you want to answer about different services and the use cases you want to enable for developers. What’s the ideal data model for infrastructure as code (IaC), Kubernetes, GitOps, or alert management? The right answer is unique to your organization – and depends on the specific information that’s most useful to your dev teams. This is where blueprints shine. Instead of imposing a rigid and opinionated data model, blueprints let platform engineers or DevOps define the ideal data model for your engineering org. 

Being adjustable over time - Things change: your infrastructure, your applications, your team structure, the questions your engineering organization cares about, the use cases you want to cover in the portal. And blueprints are designed to change with you. The ability to continuously update blueprints – by extending or refining properties and metadata – means that you can easily support new services. And tools like data migration and versioning mean that you’ll always be able to keep your software catalog aligned with your latest data model. 

‍Providing context – Your code is not your app. How your app behaves depends on the environment it’s running in and the ecosystem of tools and dependencies surrounding the end user. And a static software catalog that only includes metadata – and not runtime data – rarely provides developers with the context they need. Blueprints provide an easy way to enrich the data model with contextual “running service” data: references to the service, environment, and deployment, as well as real-time information such as status, uptime, and more. This provides critical context to help answer questions like, “What is the current running version of service x in environment y?”