Skip to main content

Introduction

The Portal Controller is a single integration that syncs Kratix Promises and Resource requests into a developer portal, such as Backstage or Cortex. It replaces the standalone Backstage Controller and Cortex Controller, which are both deprecated in favour of this controller.

Portal vs Port

"Portal" (this section) is Syntasso's unified catalogue-sync layer for developer portals such as Backstage and Cortex. It is unrelated to Port (port.io), a different third-party integration documented elsewhere in this section.

What the integration provides​

The Portal Controller enables platform teams to:

  • Connect the platform to one or more developer portals from a single SKEIntegration
  • Publish Kratix Promises and Resources as entities in Backstage or Cortex
  • Opt Promises and Resources into a portal with a label, rather than a dedicated CRD per portal
  • Route developer requests through review, by raising them as pull requests instead of applying them directly
  • Shape the generated entities per Promise with a PortalCustomization
  • Migrate from the standalone Backstage or Cortex controllers at your own pace, since both continue to work alongside the Portal Controller

Architecture​

A platform team declares every portal the platform exposes on one SKEIntegration of spec.type: portal-controller. Each portal has a portal type, backstage or cortex, and its own configuration.

A Promise (or Resource request) opts into a portal with a label:

metadata:
  labels:
    kratix.io/portal-backstage: "true"

When the Promise syncs, the controller runs a pipeline made up of three stages:

generate  →  [configure …]  →  writer
  • generate produces the entity documents for the portal, for example a Backstage Component and Template, or a Cortex entity and workflows.
  • configure (optional) runs zero or more author-supplied containers, declared on a PortalCustomization, that edit those documents in place. Most platforms use Portal Patch here rather than writing their own container.
  • writer ships the finished documents to the portal.

How the writer delivers depends on the portal type. A Backstage portal writes the documents to a Kratix Destination, a Git repository that Backstage then discovers through its catalog providers, so the controller never calls Backstage itself. A Cortex portal calls the Cortex API directly, and additionally runs a one-time setup Job and a long-lived status exporter. See Backstage and Cortex for the detail of each.

Where developer requests go​

For a Backstage portal you also choose a delivery mode, which decides what happens when a developer submits the generated form:

  • push, the default, applies the request to the platform straight away.
  • pull-request raises the request as a pull request against a Git repository, so a human reviews and merges it before anything is created. This is currently GitHub only.

See Delivery modes for how each mode works and how to choose between them.

Next steps​

  • Installation walks through installing the Portal Controller and connecting it to a portal.
  • Backstage covers configuring a Backstage portal, installing the SKE plugins, and choosing a delivery mode.
  • Cortex covers configuring a Cortex portal.
  • Customization covers the PortalCustomization resource and how to bind a Promise to one.
  • Portal Patch is the declarative way to shape the generated entities.
  • Migrating from Backstage and Migrating from Cortex cover moving an existing integration across.