Install the Platform on Red Hat OpenShift

Overview

This document provides instructions for installing the platform on Red Hat OpenShift Container Platform (OCP) using the standard Helm chart. It is a companion to the general Kubernetes / OpenShift (Helm) installation guide.

This guide focuses on the two primary differences when deploying to OpenShift:

1. Edge Routing: Using OpenShift's native Route resources for external access instead of standard Kubernetes Ingress.
2. Security: Complying with OpenShift's default restricted-v2 Security Context Constraint (SCC) without requiring custom SCCs or privileged anyuid permissions.

The platform's Helm chart is designed to work with restricted-v2 out of the box. All container images run as non-root users and listen on non-privileged ports (e.g., 8080), satisfying the SCC's requirements.

How it works

Security Context Constraint (SCC) Compliance

OpenShift uses Security Context Constraints (SCCs) to control pod permissions. By default, pods in a standard project are subject to the restricted-v2 SCC, which enforces several security policies. The platform's Helm chart is pre-configured to comply with these policies.

The restricted-v2 SCC requires that workloads:

• Run as a non-root user (runAsNonRoot: true).
• Do not request a specific user or group ID. OpenShift assigns a unique UID/GID from a range allocated to the project (e.g., 1000700000/10000).
• Disable privilege escalation (allowPrivilegeEscalation: false).
• Drop all Linux capabilities.
• Use the RuntimeDefault seccomp profile.
• Bind only to container ports above 1023.

The Helm chart's default securityContext values satisfy all these conditions. The application services (admin-api, admin-ui, runtime, worker, s2r-discovery-ingest) listen on the non-privileged container port 8080.

To ensure compliance, you must leave the securityContext.runAsUser, runAsGroup, and fsGroup values as null in your configuration. This allows the OpenShift admission controller to inject the correct UID and GID from the project's allocated range. The chart defaults are already null.

Edge Routing: Route vs. Ingress

The Helm chart supports both OpenShift Route and standard Kubernetes Ingress resources for exposing services. You must enable exactly one. Enabling both will cause the Helm installation to fail.

On OpenShift, using a Route is the most direct method, as it utilizes the built-in OpenShift Router (based on HAProxy).

flowchart TD
    subgraph "Helm Chart Configuration"
        A[Set `route.enabled: true`] --> B{OpenShift Route};
        C[Set `ingress.enabled: true`] --> D{Kubernetes Ingress};
    end

    subgraph "API Consumer Request"
        E[API Consumer] --> F[Edge Endpoint];
    end

    subgraph "OpenShift Cluster"
        B --> G[OpenShift Router];
        D --> H[Ingress Controller];
        G --> I[Platform Services];
        H --> I;
    end

    F -- DNS --> B;
    F -- DNS --> D;

If you already operate a preferred Ingress controller on your OCP cluster, you may use it by setting ingress.enabled: true and route.enabled: false.

Prerequisites

• OpenShift Container Platform 4.x: Any supported minor version.
• oc CLI: Logged into your OCP cluster.
• Helm 3.x: The helm CLI.
• Project: An OpenShift project (Kubernetes namespace) to host the platform.
• PostgreSQL 15+: A database instance reachable from the cluster pods.
• Secrets: Two Kubernetes Secret resources containing the database password and the platform's credential key. See the Configuration reference.
• Network Egress: Outbound HTTPS access to the Specaria platform for licensing and updates. See the Egress allow-list.

Installation Steps

1. Create the Project

Create a new project for the platform deployment. This command also allocates the UID/GID range that the restricted-v2 SCC will use for your pods.

oc new-project s2r

You can confirm the allocated UID range, but you do not need to use this value in your configuration.

oc get project s2r -o jsonpath='{.metadata.annotations.openshift\.io/sa\.scc\.uid-range}{"\n"}'
# Example output: 1000700000/10000

2. Configure Image Pull Secret

Container images are pulled from a private registry provided by Specaria. Create a docker-registry secret in your project with the credentials issued from the Specaria portal (portal.specaria.io).

oc create secret docker-registry s2r-registry \
    --docker-server=<registry-from-portal> \
    --docker-username='<robot-account-from-portal>' \
    --docker-password='<robot-token-from-portal>' \
    --docker-email='ops@example.com' \
    --namespace s2r

Then, reference this secret in your Helm values file.

imagePullSecret:
  create: false
imagePullSecrets:
  - s2r-registry

Alternatively, the chart can create the secret for you if you provide the credentials directly in your values file. See the main Helm guide for details.

3. Install the Helm Chart

Create a values.yaml file to configure the Helm release. The following example demonstrates a typical OpenShift configuration using a Route for path-based routing.

Example openshift-values.yaml

# Image source configuration.
global:
  image:
    registry: registry.example.com/specaria   # No trailing slash
    tag: "1.5.8"
    pullPolicy: IfNotPresent

# Reference the pre-created pull secret.
imagePullSecret: { create: false }
imagePullSecrets: [ s2r-registry ]

# Database connection details using existing secrets.
database:
  urlSecretName: s2r-db
  urlSecretKey: url
  passwordSecretName: s2r-db
  passwordSecretKey: password

# OCP restricted-v2 compatible security context. These are the chart defaults.
securityContext:
  enabled: true
  runAsNonRoot: true
  runAsUser: null
  runAsGroup: null
  fsGroup: null

# Disable Ingress and enable OpenShift Route.
ingress:
  enabled: false
route:
  enabled: true
  host: s2r.apps.<cluster-domain>     # Path-based routing under a single host
  tls:
    termination: edge
    insecureEdgeTerminationPolicy: Redirect
  paths:
    admin-ui:  /
    admin-api: /admin
    runtime:   /runtime

# Optional: Configure autoscaling and pod disruption budgets for high availability.
autoscaling:
  enabled: true
  targetCPUUtilizationPercentage: 70
podDisruptionBudget:
  enabled: true
  minAvailable: 1

Install the chart using Helm.

helm install s2r ./s2r-chart \
    --namespace s2r \
    --values openshift-values.yaml

4. Verify the Installation

After the Helm installation completes, verify that all components are running correctly.

1. Check deployment status:

   for d in admin-api admin-ui runtime worker s2r-discovery-ingest; do
     oc -n s2r rollout status deployment/$d
   done
   

2. Confirm pods are running with an assigned UID:

   # List all pods in the project
   oc -n s2r get pods
   
   # Check the runAsUser for each pod (should be a large, non-zero number)
   oc -n s2r get pod -l app.kubernetes.io/name=s2r \
     -o jsonpath='{range .items[*]}{.metadata.name}{"  uid="}{.spec.securityContext.runAsUser}{"\n"}{end}'
   

3. Check the Route status:

   oc -n s2r get routes
   

   The output should show the host you configured, which is now admitted by the OpenShift Router.

Once all pods are ready and the route is admitted, browse to the configured host (e.g., https://s2r.apps.<cluster-domain>/) to access the Admin UI. The first user to authenticate via your configured OIDC provider becomes the bootstrap administrator.

Pre-install Validation

You can validate your configuration before applying it to the cluster.

# Lint the chart with your values
helm lint ./s2r-chart --values openshift-values.yaml

# Render the Kubernetes manifests to inspect them locally
helm template s2r ./s2r-chart --values openshift-values.yaml

# Perform a server-side dry run against the OpenShift API server
helm install s2r ./s2r-chart --dry-run --namespace s2r --values openshift-values.yaml

Configuration Reference

This section details the OpenShift-specific configuration values for the Helm chart.

Route Configuration (route)

These values configure the OpenShift Route resource. They are only active when route.enabled: true.

Route TLS Configuration (route.tls)

Routing Strategy: Path-based vs. Host-based

The chart supports two routing strategies for Route resources.

1. Path-based (Default): A single hostname is shared by multiple services, which are differentiated by URL paths. Configure this using route.host and route.paths.
2. Host-based: Each service gets its own unique hostname. Configure this using route.perServiceHosts. This is required for passthrough TLS termination.

Example for host-based routing:

route:
  enabled: true
  perServiceHosts:
    admin-ui:  app.apps.<cluster-domain>
    admin-api: api.apps.<cluster-domain>
    runtime:   runtime.apps.<cluster-domain>
  tls:
    termination: edge

TLS Certificate Options

You can configure TLS for your Route in several ways:

1. Router Default Certificate: With termination: edge and no custom certificate provided, the OpenShift Router will serve its default wildcard certificate (e.g., for *.apps.<cluster-domain>). This is the simplest option.
2. OpenShift Service-Serving Certificates: For reencrypt termination, you can annotate the platform's Service resources to have OpenShift automatically mint internal serving certificates.
3. cert-manager: If you run cert-manager, you can use it to issue a certificate into a Secret and reference it in the Route via annotations.
4. Provided Certificate: You can provide your own PEM-encoded certificate materials directly in the Helm values under route.tls.key, route.tls.certificate, and route.tls.caCertificate.

Troubleshooting

See Also

• Kubernetes / OpenShift (Helm): The main guide for Helm-based installation.
• Configuration Reference: A comprehensive list of all configuration parameters.
• Deployment Runbook: Operational guidance for managing deployments.

All SOAP-to-REST docs