Conversion Service on OpenShift

Learn how to configure and deploy the Conversion Service on OpenShift.

Prerequisites

You have created an operational OpenShift cluster.
You have a valid license key for the Conversion Service.
Optional: You have a Windows Server machine with configured Microsoft Office for document conversion. This configuration is recommended for the best results when converting Microsoft Office documents.

Configure Conversion Service on OpenShift

Steps to implement the Conversion Service on OpenShift:

Use configuration file
Deploy on OpenShift
Import profiles
Enable Microsoft Office document conversion
HTTPS setup

Use configuration file

Deploy the Conversion Service with multiple replicas, a single shared volume for temporary files, and sticky sessions using the conversion-service.yaml configuration file below. Copy the code or change it to use it in your deployment:

##############################################################################
# DEPLOYMENT: 2 replicas
##############################################################################
apiVersion: apps/v1
kind: Deployment
metadata:
  name: conversion-service
spec:
  replicas: 2
  selector:
    matchLabels:
      app: conversion-service
  template:
    metadata:
      labels:
        app: conversion-service
    spec:
      containers:
      - name: conversion-service
        image: pdftoolsag/conversion-service:IMAGE_VERSION
        ports:
        - containerPort: 13033
        env:
        - name: LICENSEKEY
          value: "LICENSE_KEY_VALUE"
        volumeMounts:
        - name: convsrv-temp
          mountPath: "/tmp/convsrv"  # Single writable volume for all temp files
      volumes:
      - name: convsrv-temp
        emptyDir: {}  # One volume for all temp files
---
##############################################################################
# SERVICE: Exposes the pods internally on port 13033.
##############################################################################
apiVersion: v1
kind: Service
metadata:
  name: conversion-service
spec:
  selector:
    app: conversion-service
  ports:
    - protocol: TCP
      port: 13033
      targetPort: 13033
---
##############################################################################
# ROUTE: Cookie-based sticky sessions
##############################################################################
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: conversion-service
  annotations:
    haproxy.router.openshift.io/affinity: "cookie"
    haproxy.router.openshift.io/session-cookie-name: "conversion-service-session"
spec:
  to:
    kind: Service
    name: conversion-service
  port:
    targetPort: 13033

Replace the following:

IMAGE_VERSION: The Conversion Service version number. For example: 5.7.2, 5.7, 5, latest
LICENSE_KEY_VALUE: Pass the license key value.

note

haproxy.router.openshift.io/affinity: "cookie": Instructs the OpenShift HAProxy router to enable session affinity using cookies.
haproxy.router.openshift.io/session-cookie-name: "conversion-service-session": Sets the name of the cookie that the router uses to maintain session affinity.

These annotations ensure that all requests for a single conversion job are directed to the same pod (especially when using the Advanced API), preventing issues with stateful operations.

Deploy on OpenShift

Create a new project:
```
oc new-project PROJECT_NAME
```
Replace PROJECT_NAME with the name of the project.
Apply the conversion-service.yaml file:
```
oc apply -f conversion-service.yaml
```
Verify deployment:
```
oc get pods
```
Confirm that the Conversion Service and route are created:
```
oc get svc
oc get route
```
Test the Conversion Service endpoint. If your route hostname is conversion-service-PROJECT_NAME.apps-crc.testing, run:
```
curl http://conversion-service-PROJECT_NAME.apps-crc.testing/conversion/v1.0/rest
```
Replace PROJECT_NAME with the name of your project.

Enable Microsoft Office document conversion

To enable Microsoft Office document conversion for the Conversion Service on OpenShift, you have two possible options:

Recommended: Windows Server for Microsoft Office conversion
Office for the web service API

Recommended: Windows Server for Microsoft Office conversion

We recommend installing a dedicated Windows Server with Microsoft Office for the highest-fidelity Office conversion.

Deploy a Windows Server:
- Install Microsoft Office according to your licensing requirements.
- Use dedicated hardware or a virtual machine within your infrastructure.
Enable Office conversion in your Conversion Service profile. For more details, review Configure Microsoft Office file conversion.
If you intend to secure the traffic with HTTPS, install trusted certificates on Windows Server and OpenShift.

Office for the web service API

Using Office for the web service API has limitations—including reduced support for embedded fonts and potential localization or formatting issues.

caution

We do not recommend the Office for the web service API for critical or large-scale use cases. If you need a large-scale conversion of files, review Recommended: Windows Server for Microsoft Office conversion instead.

The following steps do not encompass specific actions but provide an overall direction to implement Office for the web service conversion with OpenShift:

Enable Office Conversion in your profile through the csconfig tool or by editing your existing profile. Office conversion is on by default, but ensure you set OfficeWebService in the processing steps of the Conversion Service.
Consent to application permissions and initialize token cache:
- Review Docker-specific tabs in Installing & configuring the local Microsoft Office installation documentation. Then, run csconfig office webinit inside the container to handle the OAuth.
- In OpenShift, you can mount a persistent volume (for example, a PVC) at /etc/convsrv so the token cache can be stored under /etc/convsrv/TokenCaches.
Set the following environment variables in your conversion-service.yaml file:
- SERVICE__OFFICE__TYPE=OfficeWebService
- SERVICE__OFFICE__USERNAME=myuser@myorganization.onmicrosoft.com
- Mount the volume with the token cache to /etc/convsrv in the container.

Import profiles

Profiles allow you to customize conversion behavior, such as image compression, PDF/A compliance, or other specialized settings. In an OpenShift environment, you can import profiles using a ConfigMap:

Export a Conversion Service profile. Review Configure and export a profile section of the Docker getting started guide.
Create a ConfigMap from the exported profile:
```
oc create configmap conversion-profile --from-file=ProfileExport-EXPORTED_PROFILE_VERSION.export
```
Replace the EXPORTED_PROFILE_VERSION: Use the version number of your exported profile. For example: 5.7.2

Update your conversion-service.yaml to mount the ConfigMap as a volume and set the environment variable IMPORT_PROFILES to the file's path. For example:

##############################################################################
# DEPLOYMENT
##############################################################################
apiVersion: apps/v1
kind: Deployment
metadata:
  name: conversion-service
spec:
  replicas: 2
  selector:
    matchLabels:
      app: conversion-service
  template:
    metadata:
      labels:
        app: conversion-service
    spec:
      containers:
      - name: conversion-service
        image: pdftoolsag/conversion-service:IMAGE_VERSION
        ports:
          - containerPort: 13033
        env:
          - name: LICENSEKEY
            value: "LICENSE_KEY_VALUE"
          - name: IMPORT_PROFILES
            value: "/etc/convsrv/ProfileExport-EXPORTED_PROFILE_VERSION.export"
          - name: WINDOWS_SERVICE_ENDPOINT
            value: "http://WINDOWS_SERVER_IP_ADDRESS:13033/conversion/v1.0/rest"
        volumeMounts:
          - name: convsrv-temp
            mountPath: "/tmp/convsrv"
          - name: convsrv-profile
            mountPath: "/etc/convsrv"
            readOnly: true
      volumes:
        - name: convsrv-temp
          emptyDir: {}
        - name: convsrv-profile
          configMap:
            name: conversion-profile

---
##############################################################################
# SERVICE
##############################################################################
apiVersion: v1
kind: Service
metadata:
  name: conversion-service
spec:
  selector:
    app: conversion-service
  ports:
    - protocol: TCP
      port: 13033
      targetPort: 13033

---
##############################################################################
# ROUTE
##############################################################################
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: conversion-service
  annotations:
    haproxy.router.openshift.io/affinity: "cookie"
    haproxy.router.openshift.io/session-cookie-name: "conversion-service-session"
spec:
  to:
    kind: Service
    name: conversion-service
  port:
    targetPort: 13033

Replace the following:

IMAGE_VERSION: The Conversion Service version number. For example: 5.7.2, 5.7, 5, latest
LICENSE_KEY_VALUE: Pass the license key value.
EXPORTED_PROFILE_VERSION: Use the version number of your exported profile. For example: 5.7.2
WINDOWS_SERVER_IP_ADDRESS: Pass the IP address of your Windows Server. If you don't want to use Microsoft Office Conversion, you can remove the WINDOWS_SERVICE_ENDPOINT environment variable.

Optional: If you configured Office for the web service API instead of the recommended Windows Server for Microsoft Office conversion:
- Remove the WINDOWS_SERVICE_ENDPOINT variable from the conversion-service.yaml file.
- Follow the instructions described in Office for the web service API section.
Deploy or update
```
oc apply -f conversion-service.yaml
```

The service starts with the imported profile.

HTTPS setup

Ensure the Conversion Service is secured with HTTPS in production environments. In OpenShift, you can configure TLS protocol termination at the route level.

Create or provide a valid TLS certificate.

To enable TLS in the route configuration, add a tls section:

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: conversion-service
spec:
  to:
    kind: Service
    name: conversion-service
  port:
    targetPort: 13033
  tls:
    termination: edge
    key: |
      -----BEGIN PRIVATE KEY-----
      ...
    -----END PRIVATE KEY-----
    certificate: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    caCertificate: |
      ...

Optional configurations

The following sections offer ideas for alternative configurations.

Configure HTTPS directly in the container

This section presents an alternative to the recommended HTTPS setup. If you prefer to configure HTTPS inside the container itself rather than at the OpenShift route layer, review Docker HTTPS configuration guide.

NGINX for complex setups

You can integrate an NGINX reverse proxy for more advanced routing or load balancing rules (for example, custom URL paths, additional security headers, or advanced caching). This can be done by:

Running NGINX as a sidecar container in the same pod as the Conversion Service.
Setting up NGINX in a separate deployment and routing traffic to your Conversion Service through the NGINX layer.

Prerequisites​

Configure Conversion Service on OpenShift​

Use configuration file​

Deploy on OpenShift​

Enable Microsoft Office document conversion​

Recommended: Windows Server for Microsoft Office conversion​

Office for the web service API​

Import profiles​

HTTPS setup​

Optional configurations​

Configure HTTPS directly in the container​

NGINX for complex setups​