Humanitec and Compass: Key ingredients for platform success

You’re all set to begin your platform journey. You have the time, you have the resources, and your manager is fully on board. You start by doing some “light” research into the right tools to use to build your Internal Developer Platform. All of a sudden, you’ve lost hours down the CNCF rabbit hole, and you’re left scratching your head. Many of these tools look like they do the same thing, so how do you choose? Let’s take a look at two such tools that often cause confusion when it comes to how they differ and how they should be used: the developer portal by Compass and the Humanitec Platform Orchestrator.

Before we get into it, let’s set things straight from a category perspective. According to Gartner's definition, "Internal developer portals serve as the interface through which developers can discover and access internal developer platform capabilities.”

Meanwhile, a Platform Orchestrator is the centerpiece of an enterprise-grade Internal Developer Platform (IDP), allowing for Dynamic Configuration Management (DCM) across the entire software delivery lifecycle (will explain more later).

In this article, I’ll walk you through the key features of the Humanitec Platform Orchestrator and the Compass developer portal, explain how they work within an IDP, and talk integration tactics.

Spotlight: The Humanitec Platform Orchestrator

As mentioned, the Humanitec Platform Orchestrator sits at the core of an IDP and enables a clear separation of concerns. It does this by enabling DCM, a methodology used to structure the configuration of compute workloads. Platform engineers define how resources should be provisioned in a dynamic and standardized way. Developers create workload specifications, describing everything they need to run successfully. This removes the need for developers to define and maintain environment-specific workload configs. They can use an open-source workload specification called Score to define resources required by their workloads in a declarative way. With every git-push, the Platform Orchestrator automatically figures out the necessary resources and configs for their workload to run. 

When used to build an IDP, the Platform Orchestrator cuts out a bunch of manual tasks. The platform team defines the rules, and the Platform Orchestrator handles the rest, as it follows a “RMCD” execution pattern: 

1. Read: interpret workload specification and context.
2. Match: identify the correct configuration baselines to create application. configurations and identify what resources to resolve or create based on the matching context. 
3. Create: create application configurations; if necessary, create (infrastructure) resources, fetch credentials and inject credentials as secrets.
4. Deploy: deploy the workload into the target environment wired up to its dependencies.

No more configs headaches, just more time to focus on the important stuff that adds real value. 

Spotlight: Compass

Like the Platform Orchestrator, developer portals like Compass also play a pivotal role from the platform perspective, mainly since it acts as the interface to the platform, enhancing the developer experience. However, the Platform Orchestrators and portals are different categories, occupy different planes of a platform’s architecture, and have different primary use cases.

Note: The components and tools referenced below apply to a GCP-based setup, but all are interchangeable. Similar reference architectures can be implemented for, AWS, Azure, or any hybrid setup. Use this reference as a starting point, but prioritize incorporating whatever components your setup already has in place.

For example, where the Platform Orchestrator is the centrepiece of an IDP, Compass is a developer portal which acts as the user interface to the platform. The fact that Compass is built by Atlassian may be an advantage since many engineering teams already use JIRA. Main features include:

• A software catalog (including service ownership, additional information like who is on call, etc.) that looks very similar to JIRA
• Score Cards that offer a framework to ensure your software components are healthy and that teams are following recommended best practices. 
• Plenty of useful integrations (VCS, CI pipelines, Slack, etc.) along with guidance on how to disconnect, uninstall, and import components. 

So, why not compare?

Comparing the Humanitec Platform Orchestrator and Compass is like comparing apples and oranges. They both play key roles in building a successful platform, BUT they're far from the same thing. The Platform Orchestrator’s main role is to generate and manage configs. It interprets what resources and configs are required for a workload to run, creates app and infrastructure configs based on rules defined by the platform team, and executes them. This removes the need for developers to worry about dealing with environment-specific configs for their workloads since the Platform Orchestrator handles it all in the background. Compass, on the other hand, acts as the platform interface, offering everything you need to monitor service ownership, recent code changes or app health:

Building an Internal Developer Platform with Compass and the Humanitec Platform Orchestrator

The real magic happens when these two tools join forces. While they support different application lifecycle stages, they can be used together to build an effective enterprise-grade IDP that significantly boosts DevOps productivity.

But when it comes to using the Humanitec Platform Orchestrator and Compass, it's not about choosing one over the other. What matters is the order in which you bring them into the mix and how you integrate them.

Step one, let's set the foundation right. You should architect your IDP to drive standardization. And the best way to do that is by starting with a Platform Orchestrator like the one from Humanitec. Next, you can decide what abstraction layers should be exposed to developers in the portal and what self-service actions you need to offer them. For this, you can adopt Compass as a developer portal on top of the platform. 

Compass and Humanitec in action

Here’s an example of what using the Humanitec Platform Orchestrator and Compass together can look like:

1. First, you’ll need to set up both, Humanitec and Compass, and configure your CI pipeline.
2. Create a Self-Service Action: You initiate a self-service action for a microservice in Compass.
3. Utilize a template: This template includes preset information or a boilerplate code, housing a sample service and a Score file, which delineates the workload dependencies.
4. Build Execution: Compass implements this template by invoking GitHub Actions to build the service.
5. Once the service is built, the Platform Orchestrator is notified and dynamically creates configuration files based on the deployment context. The Platform Orchestrator can derive the context from API calls or from tags passed on by your CI system.
6. Humanitec deploys the new service.
7. The resulting new microservice deployment entity will appear in the Compass service catalog.

Don’t forget that the problems usually occurring after day one won’t yet have been solved by scaffolding yet (e.g. the complexity of app and infra configurations, adding or removing resources the workloads depend on such as databases, DNS, storage for different types of environments, etc.).

This is where the Platform Orchestrator and Score come into play. 

By using Score, an open-source workload specification standard, developers can now easily request the resources their workload depends on or change configs in a very simple way depending on the context (e.g. environment type). Let’s take an example:

1. Add the following request to the Score file
       Bucket
                    Type: s3

2. Run a git-push

3. The Orchestrator will pick this up and update or create the correct S3 based on the context, create the app configs and inject the secrets.

4. At the end, it will register the new resource in the portal.

5. Resources provisioned by Humanitec based on requests from the Score file will be shown on the Compass service catalog for visibility and also to enable a graphical overview of the resources.

With this setup, developers can choose which interaction to use for which activity:

Get the foundation right 

To round up, both the Humanitec Platform Orchestrator and a developer portal like Compass play key (and complementary) roles in helping you achieve IDP success. The main thing to remember is that it’s all about which tool to adopt first and how. You should first lay the foundational architecture of your platform, which includes a Platform Orchestrator. Then standardize config management. Only after this should you consider adopting a developer portal. To see this in action, check out our reference architecture for GCP setups using the Platform Orchestrator, Compass, and more.