Adapter reference

The adapter generates portal documents and handles Cortex publication and status export. It is bundled in the controller image; no separate deployment is needed.

Image and workload overrides

The adapter uses the controller's image unless overridden with adapterConfig. This example requires an existing Destination named backstage-catalogue:

apiVersion: platform.syntasso.io/v1alpha1
kind: SKEIntegration
metadata:
  name: portal-controller
spec:
  type: portal-controller
  version: v0.6.1
  portals:
    - name: prod
      type: backstage
      config:
        destination:
          name: backstage-catalogue
      adapterConfig:
        image: ghcr.io/syntasso/ske-portal-controller:v0.6.1
        generate:
          args:
            - "--single-spec-page=false"

Field in `adapterConfig`	Behaviour
`image`	Single image reference, `repo:tag` or `repo@sha256:<DIGEST>`. No separate version field. Use a released image compatible with the controller and plugins.
`imagePullSecrets`	Extra Secret names, merged and deduplicated with `syntasso-registry`. Applies to adapter workloads, not the controller Deployment's pull credentials.
`generate.args`	Extra flags passed to generate for every Promise and request bound to this instance.
`exporter.deploymentSpec`	Cortex-only strategic-merge overlay for the status exporter Deployment spec.

The built-in portal types determine their own writer and exporter behaviour. Use PortalCustomization for per-Promise document changes and Job configuration for sync/setup Job policies.

Portal-wide generate flags

Flag	Type	Behaviour
`--single-spec-page=false`	Backstage	Uses a page per top-level `spec` property. One Specification page is the default.
`--fixed-namespace=<NAMESPACE>`	Cortex	Fixes the create workflow's namespace and hides that input. Must be a valid DNS-1123 label. Update/delete workflows use the selected entity's namespace.

For Backstage namespace policy, use config.requestNamespace, not the Cortex flag. Portal Patch can reshape individual Promises where a portal-wide setting would be too broad.

Arguments are visible

Do not put credentials in generate.args. Arguments are visible to anyone who can read the Job. Use credential Secrets for Cortex API access.

Cortex exporter overlay

This fragment adds node placement to an otherwise complete Cortex portal entry:

adapterConfig:
  exporter:
    deploymentSpec:
      template:
        spec:
          nodeSelector:
            tier: portal

Use pod-level fields such as nodeSelector, tolerations and affinity. The controller reapplies its exporter container, Service Account, labels, credential injection and pull secrets after merging; a containers entry cannot replace the exporter container. See Cortex exporter configuration.

Generated documents

Controller-managed generate and configure stages share /kratix/output. Configure containers read the parent object at /kratix/input/object.yaml and edit output files in place.

Type	Lane	Files
Backstage	Promise	`catalog-info.yaml`: a Promise Component and request Template, as separate YAML documents
Backstage	Resource	`catalog-info.yaml`: a Resource Component
Cortex	Promise	`promise-entity.yaml`, `entity-type.yaml`, `workflow-create.yaml`, `workflow-update.yaml`, `workflow-delete.yaml`
Cortex	Resource	`resource-entity.yaml`

Backstage's writer publishes through a Kratix Work and Destination; Cortex's writer calls the Cortex API. Intermediate file paths are not the final StateStore paths that Backstage discovers. See Backstage output paths.

Do not write a duplicate /kratix/metadata/destination-selectors.yaml entry from a configure container. The generator already selects the output directory, and the writer rejects duplicate entries for it.

Promise Template

The ske:configure-resource action creates or updates a Kratix Resource Request and can be used in a Template to make these requests from within Backstage. In gitops and hybrid modes it works by pushing the generated Resource Request manifest to a Git repository; in Kubernetes API mode it applies the manifest directly via the Kubernetes API. The Template allows all Promise API fields to be filled in within Backstage.

In pull-request mode, the Template proposes a GitHub pull request. This push-mode outline omits specification fields, tracking steps and namespace policy:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  description: Jenkins as a Service
  name: jenkins-promise-template
  title: Jenkins
spec:
  lifecycle: experimental
  owner: kratix-platform
  parameters:
    - properties:
        objname:
          description: Name for the request in the platform cluster
          title: Name
          type: string
        objnamespace:
          description: Namespace for the request in the platform cluster
          title: Namespace
          type: string
      required:
        - objname
        - objnamespace
      title: Jenkins Instance Metadata
  # other properties
  steps:
    - action: ske:configure-resource
      id: ske-configure-resource
      input:
        manifest: |
          apiVersion: marketplace.kratix.io/v1alpha1
          kind: Jenkins
          metadata:
            name: ${{ parameters.objname }}
            namespace: ${{ parameters.objnamespace}}
          spec: ${{ parameters.spec | dump }}
      name: Create a Jenkins
  type: kratix-resource

The Kratix Catalog Entities

The front-end plugin provides specific entity pages for both Kratix Promises and Kratix Resources. To get all features of the plugin, your Components must include a few fields and annotations so that the front-end plugin can render the right data.

Kratix Promise Entity

Kratix Promises should be created with a set of kratix.io/ annotations which are used to convey metadata to the front-end plugin. The name, title and description should also be set to appropriate values.

For example, considering a Promise that provides a Jenkins resource, the Component definition would look like this:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: jenkins-promise # Name of the Promise Component
  title: Jenkins Promise # Title to be displayed in Backstage
  description: Jenkins as a Service # Description of the Promise
  tags:
    - kratix
  annotations:
    backstage.io/kubernetes-id: cicd
    kratix.io/type: promise # This tells the front-end plugin that this is a Promise
    kratix.io/promise-name: cicd # The Promise's metadata.name
    kratix.io/api-name: Jenkins # The Kind of the resource provided by the Promise
    kratix.io/api-group: marketplace.kratix.io # The Group of the resource provided by the Promise
    kratix.io/status: |
      {"message": "Some Status Message"}
    kratix.io/backstage-promise-template: jenkins-promise-template # metadata.name of the Backstage Template used to create the resource
spec:
  lifecycle: production
  owner: kratix-platform
  type: kratix-promise
  # remainder of the component spec...

Kratix Resource Entity

Kratix Resources should be created with a set of kratix.io/ annotations which are used to convey metadata to the front-end plugin. The name, title and description should also be set to appropriate values.

The relationship between the Resource and the Promise can be displayed in the front-end plugin by adding a dependsOn relation to the spec, which references the Promise Component via an entity reference.

For example, considering a Jenkins resource requested on the Promise shown above, the Component definition for the Jenkins resource would look like this:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-request-jenkins # Name of the Resource Component
  title: "my-request Jenkins" # Title to be displayed in Backstage
  description: "my-request Jenkins created via cicd Promise" # Description of the resource
  annotations:
    backstage.io/kubernetes-label-selector: cicd-cr=my-request
    kratix.io/type: resource # This tells the front-end plugin that this is a Kratix Resource
    kratix.io/status: |
      {"message": "Some Status Message"}
    kratix.io/promise-name: cicd # The Jenkins Promise's metadata.name
    kratix.io/group: "marketplace.kratix.io" # Promise API Group
    kratix.io/version: "v1alpha1" # Promise API Version
    kratix.io/kind: Jenkins # Promise API Kind
    kratix.io/name: my-jenkins # Name of the Resource
    kratix.io/namespace: default # Namespace of the Resource
    kratix.io/backstage-promise-template: jenkins-promise-template # metadata.name of the Backstage Template used to create the resource
spec:
  type: kratix-resource
  lifecycle: production
  owner: kratix-platform
  dependsOn:
    - component:default/jenkins-promise
  # remainder of the component spec...

Image and workload overrides​

Portal-wide generate flags​

Cortex exporter overlay​

Generated documents​

Promise Template​

The Kratix Catalog Entities​

Kratix Promise Entity​

Kratix Resource Entity​