# 2.4 Openshift Container Platform (OCP)

## **Openshift Container Platform**

ZTrust can be deployed on the Openshift Container Platform. The prerequisites of deploying ZTrust on OCP are as follows.

### **Prerequisites**

* **OCP Version 4.15 or higher**:&#x20;
  * We recommend deploying production-grade ZTrust SSO on OCP cluster as Kind deployment.
  * ZTrust SSO is not a stateless app. It maintains user sessions and cache and requires a database.
  * ZTrust SSO uses OCP's service discovery to discover similar ZTrust pods and create ZTrust clusters automatically for HA.
  * OCP can automatically restart pods, auto-rollout upgrades, and auto-scale pods with zero downtime.
  * Sticky sessions are more efficiently handled with OCP Routes and Service.
  * For production, multi-tenant, HA-enabled ZTrust → use OCP.
* **Minimum vCPU & RAM**
  * ZTrust SSO requires a minimum of 800 millicore CPUs and 600 MB of RAM during startup.
  * With a standard load, ZTrust consumes around 300 millicores of CPU and 1200 MB of RAM per pod.
  * The usage may vary depending on the number of users, active user sessions, and features used.
* **Database**

  * For a production-grade setup, ZTrust needs a **database** to persist the ZTrust configuration and user data. The following table shows a list of supported databases for ZTrust

    <table><thead><tr><th width="259">Database</th><th>Option</th><th>Tested version</th></tr></thead><tbody><tr><td>Maria DB Server</td><td>mariadb</td><td>11.2</td></tr><tr><td>Micosoft SQL Server</td><td>mssql</td><td>2022</td></tr><tr><td>MySQL</td><td>mysql</td><td>8.4</td></tr><tr><td>Oracle Database</td><td>oracle</td><td>23.5</td></tr><tr><td>PostgreSQL</td><td>posgres</td><td>17</td></tr><tr><td>Amazon Aurora PostgreSQL</td><td>postgres</td><td>16.8</td></tr></tbody></table>

  * It is recommended to use 100 GB storage for the SQL DB for up to 100,000 users. The storage may increase if the number of users is increased.
* **Route**: Use route for,
  * Session stickiness
    * ZTrust relies on session cookies during login and admin console use.
    * If requests bounce between different ZTrust pods, users may get logged out or see errors.
    * Route can enforce sticky sessions via cookie affinity, ensuring all user requests hit the same pod for the session.
  * TLS termination & hostname handling
    * ZTrust requires a fixed hostname in OCP Route (ZT\_HOSTNAME); otherwise, redirects and OIDC flows fail.
    * Route handles:
      * TLS termination
      * Large Tokens in auth header.
      * Hostname routing. For multi-organisation setup, Route is helpful in setting up multiple hosts for the same ZTrust instance. Route hosts option can be leveraged for isolating organisation-specific traffic and routing to a shared ZTrust instance (Pod).
    * Load balancing & failover
      * If you run multiple ZTrust pod replicas, OCP Route and Service balances traffic automatically.
      * Route gives finer control: health checks, failover, and pod draining during rolling upgrades.
    * Compatibility with OIDC/SAML flows
      * OIDC & SAML redirect flows need absolute URLs and consistent session state.
      * OCP Route simplifies this by presenting a single, stable public endpoint even if backend pods move around.
    * Custom routing & path handling
      * Many setups run ZTrust under a path (e.g., /auth).
      * Route handles path rewrites, forwarding, and securing access with annotations.
* **RabbitMQ** – Version 3.12.2 (recommended)
  * ZTrust SSO uses RabbitMQ-based interactions with the ZTrust Authenticator app via the MQTT protocol. You should ensure that your RabbitMQ has the following:
    * RabbitMQ version is 3.12.2
      * The TLS certificates are added to RabbitMQ, and MQTTS is configured.
      * A writable virtual host is configured with the right permissions of the topic exchanges for the RabbitMQ user.
      * For a production-grade RabbitMQ, it is recommended to go with 30 GB of disc space in the virtual host.
* **SSL/TLS certificates**
  * Certificates are required during the runtime of ZTrust SSO on OCP to enable better encryption and production grade. Please ensure you have a valid CA signed certificate for the ZTrust deployment. Alternatively, you can use a `Let’s Encrypt`  or Self-signed certificate in your non-prod environment.
  * ZTrust SSO requires the SSL certificates' public and private keys during pod startup for a production-grade setup. Hence, OCP Route should be configured with 'Passthrough' or 'Edge' TLS Termination, maintaining both route termination and pod certificates as same.

### **Deploy on OCP**

Once the prerequisites are satisfied, you are ready to deploy the ZTrust SSO on your OCP Cluster. Let’s consider the OCP deployment kind with service and route for this installation. The following environment variables are required to be added to ZTrust SSO deployment.

<table><thead><tr><th width="201">Environment Variable</th><th width="320">Description</th><th>Accepted Values (Format)</th></tr></thead><tbody><tr><td>ZT_DB</td><td>Database type (e.g., postgres, mysql, mariadb).</td><td>mariadbmssqlmysqloraclepostgres</td></tr><tr><td>ZT_DB_URL</td><td>Full JDBC URL string including host, port, and database name.</td><td>jdbc:postgresql://url:port/db-name</td></tr><tr><td>ZT_DB_USERNAME</td><td>Database username with privileges to access the DB.</td><td><em>&#x3C;string></em></td></tr><tr><td>ZT_DB_PASSWORD</td><td>Database password.</td><td><em>&#x3C;string></em></td></tr><tr><td>ZTRUST_ADMIN</td><td>Default Admin username for ZTrust Admin Console.</td><td><em>&#x3C;string></em></td></tr><tr><td>ZTRUST_ADMIN_PASSWORD</td><td>Default password for Admin user.</td><td><em>&#x3C;string></em></td></tr><tr><td>ZT_HOSTNAME</td><td>Defines the external hostname (base URL) that ZTrust uses to generate redirects, tokens, and OIDC/SAML endpoints.</td><td>auth.example.com</td></tr><tr><td>ZT_PROXY</td><td>This variable tells ZTrust how to handle proxy headers (like X-Forwarded-For, X-Forwarded-Proto) when running behind reverse proxies or ingress controllers (NGINX, HAProxy, ALB, etc.). If ZTrust is behind a reverse proxy use “<strong>edge</strong>”. If the proxy terminates TLS and then re-encrypts traffic back to ZTrust then use “<strong>reencrypt</strong>”​If the proxy is not terminating TLS, but just passing it through to ZTrust then use “<strong>passthrough</strong>”</td><td>edge reencrypt passthrough</td></tr><tr><td>PROXY_ADDRESS_FORWARDING</td><td>Same as ZT_PROXY but useful in older ZTrust versions</td><td>true false</td></tr><tr><td>ZT_HTTPS_CERTIFICATE_FILE</td><td>Path to the TLS/SSL certificate file (.crt or .pem) that ZTrust should use for HTTPS. The certificates can be mounted via configmap to the ZTrust deployment.</td><td>/tmp/ztrust/tls.crt</td></tr><tr><td>ZT_HTTPS_CERTIFICATE_KEY_FILE</td><td>Path to the certificate private key file (.key or .pem) that ZTrust should use for HTTPS. The private key can be mounted via configmap to the ZTrust deployment.</td><td>/tmp/ztrust/tls.key</td></tr></tbody></table>

1. Create a namespace in your OCP cluster, "ztrust-sso", using the oc command.\\

   ```shell
   oc new-project ztrust-sso
   ```

   &#x20;\
   Or,

   1. Log into the web-console of the OCP cluster.\\

      <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2Fi0hTI3r28z43fb9XNq2Q%2FScreenshot%202025-09-06%20004659.png?alt=media&#x26;token=250be0f5-b073-45f2-8abe-869a1feee296" alt=""><figcaption><p>Fig2.4.a: Welcome page of OCP cluster</p></figcaption></figure>

   2. In the Sidebar, click **Home ⇒ Projects**.\\

      <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FwIUoQbgtq8M6fIkbLwFj%2FScreenshot%202025-09-06%20004750.png?alt=media&#x26;token=c4fbe69a-c8f5-41d1-9abe-053e243402ba" alt=""><figcaption><p>Fig. 2.4.b: Navigating to Projects in OCP</p></figcaption></figure>

   3. Click the **Create Project** button. Give it a name, "ztrust-sso", and description.\\

      <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2Ftze8cBXt3xqwv10fnFu4%2Fimage.png?alt=media&#x26;token=818c6f41-3d1a-4279-832f-2335bed3b121" alt=""><figcaption><p>Fig. 2.4.c: Creating a new project in OCP</p></figcaption></figure>

      <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FHk7EahSeaMdUOt116DBt%2FScreenshot%202025-09-06%20004906.png?alt=media&#x26;token=35b42806-8227-47ef-bdf1-8920316c60de" alt=""><figcaption><p>Fig. 2.4.d: Giving a name to the project in OCP</p></figcaption></figure>

   4. Click Create.

2. Create a OCP TLS secret in the same namespace using the following command.\\

   {% code overflow="wrap" %}

   ```shell
   oc create secret tls ztrust-tls-secret --key path/to/key-file --cert path/to/cert-file
   ```

   {% endcode %}

   &#x20;

3. In the web-console, click **Workloads ⇒ Secrets**\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FtNFXfHHwWmvIComBocXd%2Fimage.png?alt=media&#x26;token=36d04e75-3ee1-46a3-9663-67d63ad1008c" alt=""><figcaption><p>Fig. 2.4.e: Navigating to Workloads ⇒ Secrets in OCP</p></figcaption></figure>

4. Click on `ztrust-tls-secret`.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2Fac1fmiwYFFK1rZnVF5A7%2Fimage.png?alt=media&#x26;token=59ad1ca6-b84c-4f7c-90b3-988b5293ee2d" alt=""><figcaption><p>Fig. 2.4.f: Opening the tls secret in OCP</p></figcaption></figure>

5. Click on **Add Secret to Workload** button\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FHl0nH0FzFGvb0ockHBM4%2Fimage.png?alt=media&#x26;token=40820ec4-575d-466b-90e0-a55b5b79f495" alt=""><figcaption><p>Fig. 2.4.g: Adding the secret to the workload in OCP</p></figcaption></figure>

6. Now, we will create a **Image Pull secret**. Go to **Workloads ⇒ Secrets**. Click on **Create Secret** button and select **Image Pull secret**.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FmkSUVwKYO5ORCMMko4nG%2Fimage.png?alt=media&#x26;token=d9c662f1-f5e5-41a2-b4e7-ba698b705a69" alt=""><figcaption><p>Fig. 2.4.h: Navigating to Worloads ⇒ Secrets and creating an image pull secret in OCP</p></figcaption></figure>

7. Fill in the details and click **Create**.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FOOZvFYLswsNaK8WYeDXl%2FScreenshot%202025-09-06%20013620.png?alt=media&#x26;token=5623f33e-6e33-4b93-8617-c817a2754cec" alt=""><figcaption><p>Fig. 2.4.i: Filling in the details for image pull secret in OCP</p></figcaption></figure>

8. In the web-console, click **Workloads ⇒ Deployment**.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FIO8sm9f0qFuDYqFsKDhi%2Fimage.png?alt=media&#x26;token=28b1de69-cb15-49d0-b629-33bd12403258" alt=""><figcaption><p>Fig. 2.4.j: Navigating to Workloads ⇒ Deployments in OCP</p></figcaption></figure>

9. Click on **Create Deployment** button.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FzAKUp9ppTQwBUHTjBDgf%2Fimage.png?alt=media&#x26;token=d5973559-449f-4d60-9a3b-1d1619d76c46" alt=""><figcaption><p>Fig. 2.4.k: Creating a new deployment in OCP</p></figcaption></figure>

10. Fill the following **YAML** file. You can change the name of the deployment, labels, secrets and volumes as per your convenience.

    ```yaml
    apiVersion: v1
    items:
    - apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: ztrust-sso
      namespace: ztrust-sso
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: ztrust-sso
      template:
        metadata:
          labels:
            app: ztrust-sso
        spec:
          containers:
          - command:
            - /opt/ZTrust/bin/zt.sh
            - start
            env:
            - name: ZTRUST_ADMIN
              value: <admin-username>
            - name: ZTRUST_ADMIN_PASSWORD
              value: <admin-paddword>
            - name: PROXY_ADDRESS_FORWARDING
              value: "true"
            - name: ZT_PROXY
              value: edge
            - name: ZT_DB
              value: postgres
            - name: ZT_DB_URL
              value: jdbc:postgresql://<url:port>/<db-name>
            - name: ZT_DB_USERNAME
              value: <db-username>
            - name: ZT_DB_PASSWORD
              value: <db-password>
            - name: ZT_HOSTNAME
              value: <auth.example.com>
            - name: ZT_HTTPS_CERTIFICATE_FILE
              value: /tmp/ztrust/tls.crt
            - name: ZT_HTTPS_CERTIFICATE_KEY_FILE
              value: /tmp/ztrust/tls.key
            image: registry.prodevans.com/ztrust-sso/ztrust-sso:
            imagePullPolicy: IfNotPresent
            name: ztrust-container
            ports:
            - containerPort: 8443
              protocol: TCP
            resources: {}
            volumeMounts:
            - mountPath: /tmp/ztrust
              name: ztrust-cert
              readOnly: true
          dnsPolicy: ClusterFirst
          imagePullSecrets:
          - name: <image-pull-secret-name>
          securityContext: {}
    ```

    \
    \&#xNAN;*Note the TLS secret attached as the volume mount in this deployment. The TLS secret should be mounted to ZTrust deployment to a readable path. Openshift will create the read-only mount point directory in the pod which is only readable. Then the TLS certificates will be available as certificate files.*\
    *Please don't attach the TLS secret to "/tmp/" directory since it will block that directory and will not allow the "ZTrust-SSO" container to create cache files there*\\

11. Click **Save** and you should be seeing the pods rolling up and changing to running state in the OCP.

12. Then we need to create a service for this deployment. In the web-console, click **Networking ⇒ Services**.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FLAzdIJ9narCtYH6f1FY4%2Fimage.png?alt=media&#x26;token=f7e82f7b-6539-4bc9-b554-d11ec7c08ff7" alt=""><figcaption><p>Fig. 2.4.l: Navigating to Networking ⇒ Services in OCP</p></figcaption></figure>

13. Click on **Create Service** button.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F0TbDBVBbw8YAbs19oIhM%2Fimage.png?alt=media&#x26;token=607d6850-6927-47d4-823b-fbb00c48bf68" alt=""><figcaption><p>Fig. 2.4.m: Creating a new service in OCP</p></figcaption></figure>

14. Fill in with the following **YAML** file.

    ```yaml
    apiVersion: v1
    kind: Service
    metadata:
      name: ztrust-service
      namespace: ztrust-sso
    spec:
      selector:
        app: ztrust-sso
      ports:
        - protocol: TCP
          port: 8443
          targetPort: 8443
    ```

    \
    \&#xNAN;*Note the port number and selector, which should be matching with your deployment you created in the previous step.*\\

15. Click **Save** and you should be able to see the new service created in your OCP cluster.

16. Now the service has to be exposed to outside networks using a **Route**. To create a **Route** in the same namespace, click **Networking ⇒ Routes**.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FS2YvPwZ1s1aXqzwO1jaK%2Fimage.png?alt=media&#x26;token=ebaa053e-df6c-43e1-ae29-fbb90142bd48" alt=""><figcaption><p>Fig. 2.4.n: Navigating to Networking ⇒ Routes in OCP</p></figcaption></figure>

17. Click on the **Create Route** button.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F11SFZtp8CwGTjUGsN6Ef%2Fimage.png?alt=media&#x26;token=c9256b17-2851-4079-8c61-0826feaf3c4f" alt=""><figcaption><p>Fig. 2.4.o: Creating a new route in OCP</p></figcaption></figure>

18. Give a **Name**, "ztrust", to the route and remove the '/' from the **Path**.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FlUFXU0ZiskgMhd9vLNLf%2Fimage.png?alt=media&#x26;token=8bdca579-84f4-482d-9249-85bba5641151" alt=""><figcaption><p>Fig. 2.4.p: Filling the details for the route in OCP</p></figcaption></figure>

19. Select the **Service** you just created and select the **Target port**.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F2CfC8UGQx2Zs6WCRJuN6%2FScreenshot%202025-09-06%20011923.png?alt=media&#x26;token=5c2d451a-9a2c-4e7c-9f92-750be9aab269" alt=""><figcaption><p>Fig. 2.4.q: Selecting the service and a target port for the route in OCP</p></figcaption></figure>

20. Check the **Secure Route** checkbox and select the **TLS Termination** as **Passthrough**.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FSxuhW7yRRCFxocaGeG7R%2FScreenshot%202025-09-06%20012031.png?alt=media&#x26;token=766be8b4-ebf2-4678-bffa-b6d4dd4e060a" alt=""><figcaption><p>Fig. 2.4.r: Securing the route in OCP</p></figcaption></figure>

21. Click **Create**.

22. Now, copy the **URL** and paste into the deployment **YAML** as the value of **ZT\_HOSTNAME**.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FAN0Q0MM66bfIZYVNgv9C%2Fimage.png?alt=media&#x26;token=e5e0957a-191d-416d-b071-53294925b991" alt=""><figcaption><p>Fig. 2.4.s: Generated route URL in OCP</p></figcaption></figure>

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FH4oZVWcdCgk4ecKVVb92%2Fimage.png?alt=media&#x26;token=7796a753-d753-4aa4-b179-702832cf2860" alt=""><figcaption><p>Fig. 2.4.t: Mapping the deployment YAML to the generated route URL in OCP</p></figcaption></figure>

23. Click **Save**.

Now, your ZTrust service should be acessible, and you should be able to navigate to the ZTrust Admin Console.
