Install and upgrade the Portal Controller

Install the controller once per platform, then configure Backstage or Cortex. This guide verifies the Deployment and PortalCustomization CRD.

Requirements

You need cluster administrator access, kubectl, SKE and Syntasso registry credentials. The examples use Portal Controller v0.6.1.

Component	Requirement	Needed for
SKE	`v0.59.0` or later	The status format supported by this controller
SKE Operator	`v0.34.0` or later	Operator-managed deployment and portal configuration
Portal Controller	`v0.6.1`	The examples and features documented here
`@syntasso/plugin-ske-backend`	`v0.24.0` or later	Backstage request actions and namespace resolution
`@syntasso/plugin-ske-frontend`	`v0.22.0` or later	Backstage entity pages and namespace selection
Portal Patch	Independently versioned, optional	Declarative customisation; check the recipe reference

Install the Backstage packages in Backstage.

Install the Portal Controller

Use the SKE Operator, or install standalone if it does not manage this integration.

Check for an existing installation

kubectl get skeintegrations
kubectl get deployment ske-portal-controller --namespace kratix-platform-system

Look for spec.type: portal-controller. Only one integration of this type is allowed. Reuse it: verify or upgrade, preserving its name and portal entries.

If only the Deployment exists, check how it is managed before installing another controller.

Create the integration resource

For a new installation, save this as portal-controller.yaml:

Existing installations

Do not apply portals: [] to an existing integration. It removes configured portals.

apiVersion: platform.syntasso.io/v1alpha1
kind: SKEIntegration
metadata:
  name: portal-controller
spec:
  type: portal-controller
  version: v0.6.1
  portals: []

kubectl apply --filename portal-controller.yaml

The operator installs the Deployment, CRD, Service Account and RBAC. The empty list configures no portal instances.

Verify the installation

For operator-managed installations, replace <INTEGRATION_NAME> with the existing resource name:

kubectl wait --for=condition=IntegrationDeploymentReady \
  skeintegration/<INTEGRATION_NAME> --timeout=180s
kubectl get skeintegration <INTEGRATION_NAME> \
  -o jsonpath='{.status.lastAppliedVersion}{"\n"}'

Expect IntegrationDeploymentReady: True and the requested applied version, v0.6.1 in this example. Check the controller and CRD for either installation method:

kubectl rollout status deployment/ske-portal-controller \
  --namespace kratix-platform-system --timeout=180s
kubectl wait --for=condition=Established \
  crd/portalcustomizations.platform.syntasso.io --timeout=60s
kubectl get configmap ske-portal-config --namespace kratix-platform-system

Next, configure Backstage or Cortex and verify publication. For failed installation checks, see Troubleshoot portal sync.

Upgrade the controller

Upgrade prerequisites

Before upgrading to Portal Controller v0.4.0 or later, upgrade the SKE Operator to v0.34.0 or later.

Upgrade Backstage plugins first. New Templates may require actions absent from older plugins.

SKE v0.59.0 requires Portal Controller v0.4.2 or later. Review controller releases, SKE releases and Backstage plugin releases.

Check release notes and compatibility. Upgrade prerequisites first.
Change only spec.version in your existing integration manifest.
Apply that manifest through your normal deployment process. For a locally managed file:
```
kubectl apply --filename portal-controller.yaml
```
Verify installation, then test publication and request delivery.

For standalone upgrades, repeat the manifest download and Kustomize apply below using the target release. Preserve the configuration ConfigMap and your local overlays. Do not apply the empty bootstrap ConfigMap again.

Installing without the SKE Operator

This path requires SKE and its pipeline adapter. Do not combine it with an operator-managed controller.

Check platform dependencies

Check SKE's namespace, pipeline adapter configuration and registry Secret:

kubectl get namespace kratix-platform-system
kubectl get configmap kratix-platform-pipeline-adapter-config \
  --namespace kratix-platform-system \
  -o jsonpath='{.data.PIPELINE_ADAPTER_IMG}{"\n"}'
kubectl get secret syntasso-registry --namespace kratix-platform-system

The ConfigMap must contain a non-empty PIPELINE_ADAPTER_IMG. Restore missing dependencies through your SKE installation process before proceeding. These commands do not print credentials.

Download and configure the released manifest

In a new local directory for this installation, download the manifest:

mkdir portal-controller-install
cd portal-controller-install
curl --fail --location --output ske-portal-controller.yaml \
  https://syntasso-enterprise-releases.s3.eu-west-2.amazonaws.com/ske-portal-controller/v0.6.1/ske-portal-controller.yaml

The manifest includes the CRD, RBAC, Service Account and Deployment, but no namespace or pull credentials. Save this overlay as kustomization.yaml beside it:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ske-portal-controller.yaml
patches:
  - target:
      kind: Deployment
      name: ske-portal-controller
    patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: ske-portal-controller
      spec:
        template:
          spec:
            imagePullSecrets:
              - name: syntasso-registry

Create the portal configuration

For a new installation, save this as portal-config.yaml. It configures no portal instances:

apiVersion: v1
kind: ConfigMap
metadata:
  name: ske-portal-config
  namespace: kratix-platform-system
data:
  connections.yaml: "[]"

kubectl apply --filename portal-config.yaml

If the ConfigMap exists, preserve its entries. Add portal instances using the configuration reference. Create any referenced Cortex credential Secret through your Secret management process first.

Deploy and verify

kubectl apply --kustomize .

Repeat the Deployment, CRD and ConfigMap checks under verification. Do not run the SKEIntegration checks: standalone installations have no integration resource.

Air-gapped environments

Mirror the images below and configure registry access before installing:

Image	Needed for
`ghcr.io/syntasso/ske-portal-controller:<VERSION>`	The controller and bundled adapter
`ghcr.io/syntasso/portal-patch:<VERSION>`	Optional Portal Patch recipes
An overridden `adapterConfig.image`	A portal with an adapter override
Each `PortalCustomization` container image	Custom configure stages

The Kratix pipeline adapter image is also required and is part of the SKE installation. For operator-managed installations, use the operator's registry configuration. For standalone installations, add image replacements to your Kustomize overlay for both the Deployment image and its PORTAL_ADAPTER_IMG environment value. The pipeline adapter ConfigMap must also name a reachable image.

Adapter pull-secret overrides are separate from controller Deployment pull credentials. See Adapter reference.

Next steps

Follow Backstage or Cortex to configure publication, then verify the portal-to-platform request path. Use Troubleshoot portal sync if deployment, setup or generation fails.

Use the portal configuration reference for fields and bindings, the Adapter reference for generation settings, and Configure sync and setup Jobs for cluster policies.

Requirements​

Install the Portal Controller​

Check for an existing installation​

Create the integration resource​

Verify the installation​

Upgrade the controller​

Installing without the SKE Operator​

Check platform dependencies​

Download and configure the released manifest​

Create the portal configuration​

Deploy and verify​

Air-gapped environments​

Next steps​