OpenShift deployment

  1. Overview
  2. Prerequisites
  3. Requirements
    1. Hardware Requirements
      1. Postgres Database Sizing
    2. Infrastructure Requirements
  4. Getting Started
  5. Configuration Setup
    1. Cluster-scoped objects
  6. Security Context Constraints
    1. Namespace-scoped alternative
    2. What stays inside the namespace
  7. Storage
  8. Database Deployment
    1. Install the Crunchy Postgres Operator
      1. Via the OpenShift Web Console
      2. Via CLI
    2. Deploy a PostgresCluster
  9. Deploy PostgreSQL SSL Certificate
    1. Extract the Certificate Components
    2. Construct the Certificate Bundle
    3. Create the Kubernetes Secret
  10. Kueue Deployment
    1. Install the OpenShift Kueue Operator
    2. Create the Kueue Instance
    3. Label the SAS Retrieval Agent Manager Namespace
    4. Confirm the Kueue API version
    5. Deploy Kueue Queue Objects Manually
  11. OpenShift Service Mesh 3 Deployment
    1. Install the Kubernetes Gateway API CRDs
    2. Install the OpenShift Service Mesh 3 Operator
      1. Via the OpenShift Web Console
      2. Via CLI
    3. Deploy the IstioCNI Resource
    4. Deploy the Istio Control Plane
    5. Enroll the Release Namespace in Ambient Mesh
    6. Configure SAS Retrieval Agent Manager to Use the Waypoint
    7. Verify the Waypoint Is Running
  12. OpenShift Route TLS Configuration
    1. Option 1: Inline Certificates (Manual)
      1. Prerequisites
      2. Obtain Your Certificate
      3. Encode as Base64
      4. Configure in Helm Values
    2. Option 2: cert-manager Integration (Automated)
      1. Prerequisites
      2. Install the openshift-routes Controller
      3. Create a cert-manager Issuer or ClusterIssuer
      4. Configure in Helm Values
      5. Security Considerations
  13. Next steps

Overview

This guide describes deploying SAS Retrieval Agent Manager on an OpenShift cluster.

Complete Get started first. It covers the common prerequisites, tools, and license retrieval for every platform.

Prerequisites

In addition to the common prerequisites:

  • Ability to create resources in the OpenShift environment for the SAS Retrieval Agent Manager project
  • A PostgreSQL database server with bidirectional connectivity to the cluster

Requirements

Hardware Requirements

Cluster sizing is platform-independent. Small, Medium, and Large worker node requirements are the same as on AKS and EKS. See Cluster sizing.

This example shows a Small cluster with a highly available control plane:

Node Type Count CPUs RAM Disk Notes
Control Plane Node (tainted) 3 4 8GB 50GB  
Worker Nodes 2 8 32GB 200GB Use 64GB for embedding or vectorization workloads
NFS Server Node 1 8 16GB 200GB Optional if using CSI storage; can also serve as a worker node

For Medium and Large clusters, keep this control plane and NFS configuration and scale the worker nodes to the tier requirements.

Postgres Database Sizing

Follow the PostgreSQL sizing recommendations here.

Infrastructure Requirements

  • OpenShift version: 4.19.1

Getting Started

We do not support the entire infrastructure deployment process for OpenShift like we do with AWS, Azure, and Open Source Kubernetes. You will need an already functioning OpenShift cluster. If you’re interested in deploying an OpenShift cluster, please refer to Red Hat documentation here.

Configuration Setup

For the OpenShift deployment, all of the necessary deployment changes will occur if you set the platform key in the Values file to openshift as seen here:


# @schema
# enum:
#   - "azure"
#   - "aws"
#   - "kubernetes"
#   - "openshift"
# required: true
# default: "azure"
# @schema
# -- Platform we are deploying on. (azure, aws, kubernetes, openshift)
platform: openshift

Setting platform: openshift changes four things:

  1. It creates a SecurityContextConstraints object, a ClusterRole, and a ClusterRoleBinding that grants the SCC to the SAS Retrieval Agent Manager ServiceAccounts.
  2. It removes runAsUser, runAsGroup, and runAsNonRoot from the pod and container security contexts, so OpenShift assigns a UID from the namespace range.
  3. It defaults ingress.classType to route, so the chart creates OpenShift Route objects instead of Ingress objects.
  4. It defaults the storage class name to nfs-client and does not create a StorageClass. If your cluster names its storage differently, set storage.customStorageClass.name and the storageClassName on each PVC. See Storage below.

Cluster-scoped objects

Several objects the chart creates are cluster-scoped, which means installing with the defaults requires cluster administrator privileges. Each one can be turned off and supplied by an administrator instead, so that the release itself creates nothing outside its own namespace:

Object Created when Turn it off with
SecurityContextConstraints, ClusterRole platform: openshift security.scc.create: false
ClusterRoleBinding platform: openshift security.scc.binding: namespace (or none)
ResourceFlavor, ClusterQueue integrations.kueue.enabled: true integrations.kueue.createClusterObjects: false
StorageClass storage.customStorageClass.create: true storage.customStorageClass.create: false (the default on OpenShift)
Istio Gateway (waypoint) integrations.istio.enabled: true integrations.istio.enabled: false

To confirm a given values file creates nothing cluster-scoped, render it and look for objects with no namespace:

helm template retrieval-agent-manager <chart> -n retagentmgr -f values.yaml \
  | grep -E '^kind:' | sort | uniq -c

Security Context Constraints

By default, an OpenShift installation creates three cluster-scoped objects: a SecurityContextConstraints object, a ClusterRole, and a ClusterRoleBinding. Installing the chart therefore requires cluster administrator privileges. If you must keep all role bindings inside your namespace, use the namespace-scoped alternative below.

The chart creates a dedicated SCC named <release-name>-scc rather than using the built-in anyuid or privileged SCCs. It grants only what the application needs:

  • SYS_NICE capability, for process priority
  • runAsUser: RunAsAny and fsGroup: RunAsAny
  • MKNOD dropped, no privileged containers, no host network, IPC, PID, ports, or host paths

OpenShift does not generate a system:openshift:scc:<name> ClusterRole for custom SCCs. It ships those ClusterRoles as static manifests for its built-in SCCs only; oc adm policy add-scc-to-user creates them on the fly for everything else. The chart therefore creates the ClusterRole itself, alongside the SCC.

This matters if you write the RBAC by hand. A RoleBinding or ClusterRoleBinding that references a ClusterRole which does not exist is accepted by the API server and silently grants nothing. Pods then fail admission with:

provider "retrieval-agent-manager-scc": Forbidden: not usable by user or serviceaccount

Namespace-scoped alternative

A SecurityContextConstraints object is cluster-scoped and cannot be namespaced. However, the binding can be. A RoleBinding that references a ClusterRole grants that role only within its own namespace, which avoids the cluster-wide grant.

Use this approach when your OpenShift administrator does not permit ClusterRoleBinding objects for application workloads.

Step 1. Keep platform: openshift, and move the cluster-scoped objects out of the release.

platform: openshift

security:
  scc:
    # An administrator applies the SCC, its ClusterRole, and the RoleBinding; see step 2.
    create: false
    # The chart creates no binding at all. See the note below on why `namespace` is wrong here.
    binding: none

Keep platform: openshift. Earlier versions of this guide told you to set platform: kubernetes to suppress the SCC, but platform also controls the security contexts: on kubernetes the chart keeps the explicit runAsUser, runAsGroup, and runAsNonRoot values instead of letting OpenShift assign a UID from the namespace range. security.scc.* separates the two concerns, so you no longer have to misreport the platform.

Use binding: none here, not binding: namespace. namespace asks the chart to create the RoleBinding, which the restricted installer this section exists for cannot do: Kubernetes RBAC refuses to let any identity grant permissions it does not itself hold, so the install fails with

rolebindings.rbac.authorization.k8s.io "retrieval-agent-manager-scc-binding" is forbidden:
user "..." is attempting to grant RBAC permissions not currently held:
{APIGroups:["security.openshift.io"], Resources:["securitycontextconstraints"],
 ResourceNames:["retrieval-agent-manager-scc"], Verbs:["use"]}

An administrator can lift that by granting the installer either use on the SCC or bind on the ClusterRole, but both are cluster-scoped grants, so an administrator is involved either way. Applying the RoleBinding in step 2 is the shorter path.

binding: namespace is still the right choice when the installer already holds one of those grants, or when only the SCC itself is applied out of band.

Step 2. Apply the SCC, the ClusterRole, and the RoleBinding.

Use the example manifests. Edit the namespace and release name if you do not use the defaults, then apply the file. A cluster administrator must apply it, because the SCC and the ClusterRole are both cluster-scoped:

oc apply -f scc-namespace-scoped.yaml

The manifests create:

Object Scope Purpose
SecurityContextConstraints Cluster Identical to the one the chart would create, but with an empty users list
ClusterRole Cluster system:openshift:scc:retrieval-agent-manager-scc. OpenShift does not create this for custom SCCs; without it the binding grants nothing
RoleBinding Namespace Grants the ClusterRole above to the ServiceAccounts in your namespace only

Do not apply this file while binding: namespace is set. Both it and the chart create a RoleBinding named retrieval-agent-manager-scc-binding, and Helm refuses to adopt an object it did not create, so the next helm upgrade fails with:

Error: UPGRADE FAILED: Unable to continue with update: RoleBinding
"retrieval-agent-manager-scc-binding" in namespace "retagentmgr" exists and cannot be imported
into the current release: invalid ownership metadata; label validation error: missing key
"app.kubernetes.io/managed-by"

To recover, either delete the hand-applied object and let the chart own it, or keep this file and switch to binding: none:

oc delete rolebinding retrieval-agent-manager-scc-binding -n retagentmgr

Step 3. Verify the grant before you install.

# Confirm the SCC exists
oc get scc retrieval-agent-manager-scc

# Confirm the ClusterRole the binding references exists.
# This is the check that catches the most common mistake: a binding that resolves to nothing.
oc get clusterrole system:openshift:scc:retrieval-agent-manager-scc

# Confirm the RoleBinding is namespaced, not cluster-wide
oc get rolebinding retrieval-agent-manager-scc-binding -n retagentmgr

oc adm policy who-can use scc retrieval-agent-manager-scc -n retagentmgr does not detect a missing ClusterRole. It reports the binding, not whether the role that the binding names exists. Use the oc get clusterrole check above instead.

Step 4. Install the chart.

The ServiceAccounts must exist for the binding to take effect, but a RoleBinding may reference a ServiceAccount that does not exist yet. You can apply the manifests before or after the Helm install; the subjects resolve once the chart creates the ServiceAccounts.

Note: If you change the Helm release name or any serviceAccount.name value, update the subject names in the manifests to match. If you change the SCC name, set security.scc.name so the chart’s binding points at it.

Nothing in this section requires you to set serviceAccount.create: false. The manifests in step 2 may name ServiceAccounts that do not exist yet, so let the chart create them.

If your administrator does pre-create the ServiceAccounts and you set api.serviceAccount.create: false, keep in mind that this suppresses only the ServiceAccount object. The chart still creates the namespace-scoped Role and RoleBinding that the API needs to read and watch Deployments, Jobs and the rest of its own namespace, and still binds them to the name in api.serviceAccount.name.

Earlier chart versions gated that RBAC on serviceAccount.create as well. On those versions, pre-provisioning the account left the API running under the right identity with no permissions, and it failed at runtime with deployments.apps is forbidden. If you are upgrading from one of them, confirm the grant resolves:

oc auth can-i watch deployments.apps -n retagentmgr \
  --as=system:serviceaccount:retagentmgr:retrieval-agent-manager-api

See Troubleshooting.

What stays inside the namespace

The SCC and its ClusterRole are the only cluster-scoped objects this release needs. Everything else the chart grants is namespace-scoped and is created by the installer, so a restricted installer does not need an administrator for it:

Object Scope Created by Purpose
SecurityContextConstraints Cluster Administrator (step 2) Lets the pods start
system:openshift:scc:... ClusterRole Cluster Administrator (step 2) Makes the SCC grantable
retrieval-agent-manager-scc-binding RoleBinding Namespace Administrator (step 2) Grants the SCC in this namespace only
retrieval-agent-manager-api Role + RoleBinding Namespace Chart Lets the API manage its own workloads
retrieval-agent-manager-db-init Role + RoleBinding Namespace Chart Lets database initialization read its credentials secret
retrieval-agent-manager-upgrade-cleanup Role + RoleBinding Namespace Chart Lets the pre-upgrade hook clear completed jobs
retrieval-agent-manager-postgrest Role + RoleBinding Namespace Chart Lets PostgREST read the Keycloak certificate secret

An SCC governs whether a pod is admitted. It has no bearing on what that pod may ask the Kubernetes API for once it is running; that is the namespace RBAC in the lower half of the table. The two fail in different ways, so do not diagnose one as the other: an SCC problem keeps pods from starting, while missing RBAC leaves pods running and healthy but returning 403.

Storage

The chart does not create a StorageClass on OpenShift. It defaults the name to nfs-client, which is unlikely to match your cluster. Check what is available and set the name explicitly:

oc get storageclass
storage:
  customStorageClass:
    create: false
    name: <your-storage-class>
  embedding:
    pvc:
      # Must support ReadWriteMany: the API and the vectorization workloads mount it together.
      storageClassName: <your-rwx-storage-class>
      accessModes:
        - ReadWriteMany
      size: 40Gi
  application:
    pvc:
      storageClassName: <your-storage-class>
      accessModes:
        - ReadWriteOnce
      size: 20Gi

If the embedding PVC stays Pending after installation, the storage class either does not exist or does not support ReadWriteMany:

oc get pvc -n retagentmgr
oc describe pvc embedding-pv -n retagentmgr

Database Deployment

SAS Retrieval Agent Manager requires a PostgreSQL 15+ database. On OpenShift, the Crunchy Postgres for Kubernetes operator provides a quick and convenient way to deploy PostgreSQL directly on the cluster. However, running PostgreSQL inside the cluster shares resources with the application workloads and will result in degraded performance compared to a dedicated external PostgreSQL installation. A dedicated external PostgreSQL database is the preferred approach for production deployments.

Note: Follow the PostgreSQL sizing recommendations to determine your required database size before deploying.

Install the Crunchy Postgres Operator

The Crunchy Postgres operator can be installed via the OpenShift web console or via the CLI using an OperatorGroup and Subscription.

Via the OpenShift Web Console

  1. Log in to the OpenShift web console.
  2. Navigate to Operators → OperatorHub.
  3. Search for “Crunchy Postgres for Kubernetes”.
  4. Select the operator and click Install.
  5. Choose the target namespace (e.g., postgres-operator) and click Install.

Via CLI

Create the namespace and operator resources using the following commands:

# Create the namespace for the Postgres Operator
oc new-project postgres-operator

# Create an OperatorGroup scoped to the namespace
cat <<EOF | oc apply -f -
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: postgres-operator-group
  namespace: postgres-operator
spec:
  targetNamespaces:
    - postgres-operator
EOF

# Create a Subscription for the Crunchy Postgres Operator
cat <<EOF | oc apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: crunchy-postgres-operator
  namespace: postgres-operator
spec:
  channel: v5
  name: crunchy-postgres-operator
  source: certified-operators
  sourceNamespace: openshift-marketplace
EOF

Verify the operator is running:

oc -n postgres-operator get pods --selector=postgres-operator.crunchydata.com/control-plane=postgres-operator

Deploy a PostgresCluster

Once the operator is running, create a PostgresCluster resource. The spec.openshift: true flag is required for OpenShift environments.

cat <<EOF | oc apply -f -
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: sas-ram-db
  namespace: postgres-operator
spec:
  openshift: true
  postgresVersion: 15
  instances:
    - name: instance1
      replicas: 1
      dataVolumeClaimSpec:
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 128Gi
  backups:
    pgbackrest:
      repos:
        - name: repo1
          volume:
            volumeClaimSpec:
              accessModes:
                - "ReadWriteOnce"
              resources:
                requests:
                  storage: 128Gi
  users:
    - name: sasramadmin
      databases:
        - sasram
      options: "SUPERUSER"
EOF

Track the status of your cluster:

oc -n postgres-operator describe postgresclusters.postgres-operator.crunchydata.com sas-ram-db

Once running, retrieve the connection credentials from the generated secret:

# The secret is named <clusterName>-pguser-<userName>
oc -n postgres-operator get secret sas-ram-db-pguser-sasramadmin -o jsonpath='{.data.uri}' | base64 -d

Note: For more details on cluster configuration, user management, and high availability, refer to the Crunchy Postgres for Kubernetes documentation.

Deploy PostgreSQL SSL Certificate

PGO sets up a PKI and enables TLS for all connections by default. You must extract the CA and TLS certificates from the cluster-generated secrets and build a combined cert.pem bundle for SAS Retrieval Agent Manager to use.

Extract the Certificate Components

PGO stores the cluster certificates in a secret named <clusterName>-cluster-cert. Extract the required files:

# Extract the CA certificate (used as trustedcerts.pem and ca.crt)
oc -n postgres-operator get secret sas-ram-db-cluster-cert -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

# Extract the server TLS certificate
oc -n postgres-operator get secret sas-ram-db-cluster-cert -o jsonpath='{.data.tls\.crt}' | base64 -d > tls.crt

# Extract the server TLS private key
oc -n postgres-operator get secret sas-ram-db-cluster-cert -o jsonpath='{.data.tls\.key}' | base64 -d > tls.key

Construct the Certificate Bundle

Follow Secure the database connection to build the combined cert.pem bundle and create the Kubernetes secret. On OpenShift, use the files extracted above:

cat ca.crt ca.crt tls.crt tls.key > combined-cert.pem

Note: When using PGO’s built-in PKI, the chain cert and intermediate cert are the same ca.crt. If you have configured spec.customTLSSecret with your own PKI, use your own trustedcerts.pem in place of the first ca.crt.

Create the Kubernetes Secret

On OpenShift, use oc to create the project and the secret:

# The correct namespace to store all SAS Retrieval Agent Manager Resources
oc new-project retagentmgr

# Create a secret with the PostgreSQL SSL bundle
oc create secret generic postgres-ssl-cert --from-file=cert.pem=combined-cert.pem -n retagentmgr

Note: It is critical to enter the name of the secret in the postgreSQLCertSecret key in the values file, under vectorizationHub.config. For example:

vectorizationHub:
  config:
    postgreSQLCertSecret: 'postgres-ssl-cert'

Kueue Deployment

On OpenShift, Kueue is installed via the OpenShift Kueue Operator rather than the upstream Helm chart used on other platforms.

Install the OpenShift Kueue Operator

  1. Log in to the OpenShift web console.
  2. Navigate to Operators → OperatorHub.
  3. Search for “Kueue” and select the OpenShift Kueue Operator.
  4. Click Install and accept the defaults.

Alternatively, install via CLI. Confirm the package name and the channels your catalog offers first, because both are version-specific:

oc get packagemanifest -n openshift-marketplace kueue-operator \
  -o jsonpath='{.status.defaultChannel}{"\n"}{range .status.channels[*]}{.name}{"\n"}{end}'

On OpenShift 4.22 this reports stable-v1.4 as the default, alongside stable-v1.3. Substitute the channel you intend to use:

cat <<EOF | oc apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: kueue-operator
  namespace: openshift-operators
spec:
  channel: stable-v1.4
  name: kueue-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
EOF

Install into openshift-operators. That namespace ships an AllNamespaces OperatorGroup, which is what this operator requires. Installing it into a dedicated namespace with an OwnNamespace OperatorGroup fails, and the CSV reports:

OwnNamespace InstallModeType not supported, cannot configure to watch own namespace

Wait for the operator to report Succeeded before continuing:

oc get csv -n openshift-operators -l operators.coreos.com/kueue-operator.openshift-operators

Create the Kueue Instance

Once the operator is running, create a Kueue cluster resource to enable Kueue with the BatchJob integration framework:

cat <<EOF | oc apply -f -
apiVersion: kueue.openshift.io/v1
kind: Kueue
metadata:
  name: cluster
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: kueue-operator
spec:
  config:
    integrations:
      frameworks:
        - BatchJob
  logLevel: Normal
  managementState: Managed
  operatorLogLevel: Normal
EOF

Verify that Kueue is available:

oc get kueue cluster -o jsonpath='{.status.conditions}'

The Available condition should show status: "True" before proceeding.

Label the SAS Retrieval Agent Manager Namespace

For Kueue to manage workloads in the retagentmgr namespace on OpenShift, the following label must be applied to the namespace:

oc label namespace retagentmgr kueue.openshift.io/managed=true

Note: Without this label, Kueue will not intercept and manage vectorization jobs in the retagentmgr namespace and those jobs will fail to be queued correctly.

Confirm the Kueue API version

The chart renders the queue objects as kueue.x-k8s.io/v1beta2 by default. Upstream Kueue served v1beta1 until 0.15, and the OpenShift Kueue Operator lags upstream, so check what your cluster actually serves:

oc api-resources --api-group=kueue.x-k8s.io

If it reports v1beta1, set the API version in your values file. Rendering the wrong one fails with no matches for kind "ClusterQueue":

integrations:
  kueue:
    apiVersion: kueue.x-k8s.io/v1beta1

Deploy Kueue Queue Objects Manually

Three objects are involved, and only one of them is namespaced:

Object Scope
ResourceFlavor Cluster
ClusterQueue Cluster
LocalQueue Namespace

Choose the mode that matches what your cluster permits. Never let the chart and the manifests create the same object: the names collide, and Helm refuses to adopt objects it does not own.

The chart manages everything (default). Requires cluster administrator privileges.

integrations:
  kueue:
    enabled: true

An administrator owns the cluster-scoped objects. Use this when application installers may not create cluster-scoped objects. The release still creates the namespaced LocalQueue, which is what binds its namespace to the quota.

integrations:
  kueue:
    enabled: true
    createClusterObjects: false

Apply only the ResourceFlavor and ClusterQueue documents from the example queue manifests, and delete the LocalQueue document before applying.

You manage everything. Set integrations.kueue.enabled: false and apply the whole example file.

oc apply -f kueue-queues.yaml

Match the ClusterQueue quotas to the capacity of the cluster you built. See Job scheduling quotas.

The ClusterQueue must select the namespace you install into. A selector that does not match is not reported as an error: the LocalQueue simply never admits anything, and the vectorization and evaluation jobs sit Pending with no event explaining why. If you create the ClusterQueue yourself, confirm its spec.namespaceSelector matches retagentmgr.

Verify that the objects are created:

oc get resourceflavor retrieval-agent-manager
oc get clusterqueue cluster-queue
oc -n retagentmgr get localqueue genai-queue

The LocalQueue should report the ClusterQueue as active:

oc -n retagentmgr get localqueue genai-queue -o jsonpath='{.status.conditions}'

OpenShift Service Mesh 3 Deployment

Red Hat OpenShift Service Mesh 3 (OSSM3) is an optional integration that enables L7 traffic management for the SAS Retrieval Agent Manager. When enabled, the Helm chart deploys an Istio ambient-mode waypoint proxy into the release namespace. The waypoint is an Envoy sidecar-free proxy that processes all HTTP traffic and injects the X-Forwarded-For header with the real source pod IP.

Note: This section requires an OpenShift cluster with the Kubernetes Gateway API CRDs installed (see below). OSSM3 is based on the Sail Operator and uses a fundamentally different resource model from OSSM 1/2 — ServiceMeshControlPlane is not used here.

Install the Kubernetes Gateway API CRDs

OSSM3 ambient mode relies on the Kubernetes Gateway API. Install the standard channel CRDs before installing the operator:

oc apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml

Verify the CRDs are established:

oc get crd gateways.gateway.networking.k8s.io httproutes.gateway.networking.k8s.io \
  referencegrants.gateway.networking.k8s.io grpcroutes.gateway.networking.k8s.io

Install the OpenShift Service Mesh 3 Operator

Via the OpenShift Web Console

  1. Log in to the OpenShift web console.
  2. Navigate to Operators → OperatorHub.
  3. Search for “OpenShift Service Mesh” and select the Red Hat OpenShift Service Mesh operator (version 3.x).
  4. Click Install, select All namespaces scope, and accept the defaults.
  5. Wait for the operator status to show Succeeded.

Via CLI

cat <<EOF | oc apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: servicemeshoperator3
  namespace: openshift-operators
spec:
  channel: stable
  name: servicemeshoperator3
  source: redhat-operators
  sourceNamespace: openshift-marketplace
EOF

Wait for the operator to be ready:

oc -n openshift-operators wait --for=condition=Ready pod \
  -l name=sailoperator --timeout=120s

Deploy the IstioCNI Resource

Ambient mode requires the Istio CNI plugin to redirect traffic at the node level without injecting sidecars. Create an IstioCNI resource in the istio-cni namespace:

oc new-project istio-cni

cat <<EOF | oc apply -f -
apiVersion: sailoperator.io/v1
kind: IstioCNI
metadata:
  name: default
spec:
  version: v1.24.3
  namespace: istio-cni
  profile: openshift-ambient
EOF

Verify the CNI daemonset is running on all nodes:

oc -n istio-cni wait --for=condition=Ready pod \
  -l k8s-app=istio-cni-node --timeout=180s

Deploy the Istio Control Plane

Create the Istio resource that provisions the istiod control plane:

oc new-project istio-system

cat <<EOF | oc apply -f -
apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  version: v1.24.3
  namespace: istio-system
  profile: openshift-ambient
EOF

Monitor the control plane until it reaches Healthy status:

oc -n istio-system wait --for=condition=Ready istio default --timeout=180s

You can also inspect the status in detail:

oc -n istio-system get istio default -o jsonpath='{.status}' | jq

Enroll the Release Namespace in Ambient Mesh

Label the retagentmgr namespace to opt it into ambient-mode data-plane processing. This must be done before installing the SAS Retrieval Agent Manager Helm chart so that the waypoint Gateway is created in an ambient-enabled namespace.

# Enroll the namespace in Istio ambient mode
oc label namespace retagentmgr istio.io/dataplane-mode=ambient

# Instruct all pods/services in the namespace to route through the waypoint
oc label namespace retagentmgr istio.io/use-waypoint=waypoint

Note: The istio.io/use-waypoint label value must match the integrations.istio.waypoint.name value in your ram-values.yaml (default: waypoint).

Configure SAS Retrieval Agent Manager to Use the Waypoint

Enable the Istio integration in your ram-values.yaml:

integrations:
  istio:
    enabled: true
    waypoint:
      # Must match the value used in the istio.io/use-waypoint namespace label
      name: waypoint
      # "all" processes both east-west service traffic and ingress workload traffic
      waypointFor: all

When enabled: true, the chart creates a Gateway resource with gatewayClassName: istio-waypoint in the release namespace. The Istio gateway controller detects this and deploys an Envoy waypoint deployment.

Verify the Waypoint Is Running

After the Helm chart is installed, confirm the waypoint deployment is healthy:

# Check the waypoint Gateway resource
oc -n retagentmgr get gateway waypoint

# Check the Envoy waypoint pod deployed by the Istio gateway controller
oc -n retagentmgr get pods -l gateway.istio.io/managed=istio.io-mesh-controller

# Confirm the waypoint is programmed (PROGRAMMED=True)
oc -n retagentmgr get gateway waypoint -o jsonpath='{.status.conditions}' | jq

The Programmed condition should show status: "True" before proceeding to the Application Deployment step.


OpenShift Route TLS Configuration

SAS Retrieval Agent Manager exposes services on OpenShift via Route resources, which need to be secured with TLS certificates. OpenShift’s Route API does not support referencing a Secret by name (unlike Kubernetes Ingress); instead, the certificate and private key must be embedded directly in the Route’s spec.tls section.

This section explains how to configure TLS for OpenShift Routes using two approaches:

  1. Inline certificates — provide PEM-encoded certificate and key directly in Helm values
  2. cert-manager integration — use cert-manager to automate certificate issuance and renewal

Option 1: Inline Certificates (Manual)

The simplest approach is to provide your certificate and private key as PEM-encoded text in the Helm values file.

Prerequisites

  • A valid TLS certificate (.crt file) in PEM format
  • A corresponding private key (.key file) in PEM format
  • Optionally, a CA certificate (.crt file) for certificate chains

Obtain Your Certificate

Get or generate your certificate through any means (commercial CA, self-signed, Let’s Encrypt, etc.). For example:

# Self-signed example (valid for testing; do NOT use in production)
openssl req -x509 -newkey rsa:4096 -keyout tls.key -out tls.crt -days 365 -nodes \
  -subj "/CN=aiagent.sasram.kh.asegroup.com"

Encode as Base64

Encode the certificate and key for use in Helm values:

# Display certificate content as base64 (for the values file)
cat tls.crt | base64 -w 0

# Display key content as base64 (for the values file)
cat tls.key | base64 -w 0

# Optional: display CA certificate if you have a certificate chain
cat ca.crt | base64 -w 0

Configure in Helm Values

In your ram-values.yaml:

ingress:
  enabled: true
  classType: route  # "route" for OpenShift
  domain: aiagent.sasram.kh.asegroup.com
  tls:
    enabled: true
    secretName: ingress-tls  # Name for the Kubernetes secret created by the chart
    certificate: |
      -----BEGIN CERTIFICATE-----
      MIIDXTCCAkWgAwIBAgIJAJC1...
      ...
      -----END CERTIFICATE-----
    key: |
      -----BEGIN RSA PRIVATE KEY-----
      MIIEpAIBAAKCAQEA2Z3x4...
      ...
      -----END RSA PRIVATE KEY-----
    caCertificate: |
      -----BEGIN CERTIFICATE-----
      MIIDgTCCAmkCAQAwDQYJ...
      ...
      -----END CERTIFICATE-----

Note: The chart will create a Kubernetes Secret named ingress-tls from these values. This secret is used by nginx/contour ingress resources (if configured), and for cert-manager CertificateRequest objects when needed.

Option 2: cert-manager Integration (Automated)

For automated certificate issuance and renewal, integrate with cert-manager using the OpenShift Routes controller add-on. This approach uses annotations on the Route to request and manage certificates from a cert-manager Issuer or ClusterIssuer.

Prerequisites

  • cert-manager installed in the cluster (e.g., via Red Hat’s cert-manager Operator for OpenShift)
  • openshift-routes controller installed separately (NOT included with standard cert-manager)
  • A cert-manager Issuer or ClusterIssuer configured in your cluster (e.g., ACME-based, self-signed, or corporate PKI)

Install the openshift-routes Controller

The openshift-routes controller is a separate add-on from the cert-manager project. It watches Route resources for cert-manager annotations and patches their spec.tls section with certificate and key data.

# Install openshift-routes in the cert-manager namespace
helm install openshift-routes -n cert-manager \
  oci://ghcr.io/cert-manager/charts/openshift-routes \
  --version v0.10.0

Verify the controller is running:

oc -n cert-manager get pods -l app.kubernetes.io/name=openshift-routes

Create a cert-manager Issuer or ClusterIssuer

If you don’t already have an Issuer configured, create one. This example uses ACME with Let’s Encrypt:

cat <<EOF | oc apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - http01:
          ingress: {}
EOF

For self-signed or corporate CA Issuers, refer to the cert-manager documentation.

Configure in Helm Values

In your ram-values.yaml:

ingress:
  enabled: true
  classType: route  # "route" for OpenShift
  domain: aiagent.sasram.kh.asegroup.com
  tls:
    enabled: true
    secretName: ingress-tls
    # Leave certificate/key/caCertificate empty when using cert-manager
    certificate: ""
    key: ""
    caCertificate: ""
    certManager:
      enabled: true
      issuerRef:
        name: letsencrypt-prod  # Name of your ClusterIssuer or Issuer
        kind: ClusterIssuer     # Use "Issuer" for namespace-scoped, "ClusterIssuer" for cluster-scoped
      dnsNames:
        - aiagent.example.com   # Additional DNS names (optional; ingress.domain is always included)
      duration: 2160h           # Certificate lifetime (optional; defaults to cert-manager default)
      renewBefore: 360h         # How long before expiry to renew (optional; defaults to 1/3 of duration)

When certManager.enabled: true, the chart:

  1. Adds cert-manager annotations (cert-manager.io/issuer-name, etc.) to all Route resources
  2. The openshift-routes controller detects these annotations and creates a CertificateRequest through cert-manager
  3. The Issuer issues a certificate and signs the request
  4. The openshift-routes controller patches the Route’s spec.tls.certificate and spec.tls.key with the signed certificate
  5. On renewal (default: 2/3 through the certificate lifetime), the process repeats automatically

Verify the Routes have certificates:

# List routes in the retagentmgr namespace
oc -n retagentmgr get routes

# Inspect a specific route's TLS section
oc -n retagentmgr get route <route-name> -o jsonpath='{.spec.tls}' | jq

Security Considerations

The openshift-routes controller is designed for single-tenant clusters. Important caveats:

  • Multi-tenant risk: Any user who can edit a Route can request certificates for any domain via the annotations. This grants cluster-wide certificate request capability to Route editors. On shared clusters, use one or more of:
    • RBAC to restrict who can edit Routes
    • Domain-validating (ACME) Issuers to prevent arbitrary domains
    • cert-manager’s approver-policy to gate issuance
  • Namespace isolation: The controller reconciles Routes across all namespaces using a single service account, so consider applying namespace-level RBAC as well.

For more details, see the openshift-routes project README.


Next steps

  1. Configure the database — install and enable the pgcrypto and vector extensions.
  2. GPG keys — generate and back up the encryption keys.
  3. Install and upgrade — deploy the application.

Note: OpenShift installs Kueue and the service mesh through operators, as described above, rather than through the Helm charts listed on the Install dependencies page.