Skip to main content
Version: Deploy 24.1

Setting Up JDBC and MQ Drivers

This topic describes how to add additional JARs to the Deploy classpath, specifically focusing on installing the Oracle JDBC driver. There are three main options available:

There are three options available:

Option 1: Build Deploy Images with Custom Libraries​

This option uses custom master and worker images to customize the Deploy’s lib folder with additional lib - Oracle JDBC. The example starts with building custom images with the additional jar, after that custom images are used to run the containers.

Prerequisites​

  • Deploy installed on a Kubernetes cluster (e.g., in the digitalai namespace).

  • A DockerHub account (or another image registry) to upload the custom images.

With this option, you will have statically built and prepared images that can be scanned and tested with your tool before any production use.

Note: In the following examples, we are downloading the image from the public repository. Ensure that your artifact repository is trusted and secured by your organization. The URL location of the JAR file is provided as an example and can refer to any other repository or library.

Steps​

  1. Create Dockerfile for master image with the following:
cat << EOF > Dockerfile-xl-deploy
FROM xebialabs/xl-deploy:24.1.2

USER 0

# download oracle JDBC driver
ENV LIB_VERSION=23.4.0.24.05
ENV LIB_FILE=ojdbc11-\${LIB_VERSION}.jar
ENV LIB_URL=https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/\${LIB_VERSION}/\${LIB_FILE}
# if you need to downaload by using auth for example basic auth, use RUN with curl line instead of following ADD command
# RUN curl -u $user:$pass -o /tmp/\${LIB_FILE} -L \${LIB_URL}
ADD \${LIB_URL} lib/\${LIB_FILE}
RUN chown 10001:10001 lib/\${LIB_FILE} && chmod 664 lib/\${LIB_FILE}

USER 10001

ENTRYPOINT ["/opt/xebialabs/tini", "--", "/opt/xebialabs/xl-deploy-server/bin/run-in-container.sh"]
EOF

  1. Create Dockerfile for worker image:
cat << EOF > Dockerfile-deploy-task-engine
FROM xebialabs/deploy-task-engine:24.1.2

USER 0

# download oracle JDBC driver
ENV LIB_VERSION=23.4.0.24.05
ENV LIB_FILE=ojdbc11-\${LIB_VERSION}.jar
ENV LIB_URL=https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/\${LIB_VERSION}/\${LIB_FILE}
# if you need to downaload by using auth for example basic auth, use RUN with curl line instead of following ADD command
# RUN curl -u $user:$pass -o /tmp/\${LIB_FILE} -L \${LIB_URL}
ADD \${LIB_URL} lib/\${LIB_FILE}
RUN chown 10001:10001 lib/\${LIB_FILE} && chmod 664 lib/\${LIB_FILE}

USER 10001

ENTRYPOINT ["/opt/xebialabs/tini", "--", "/opt/xebialabs/deploy-task-engine:/bin/run-in-container.sh"]
EOF

  1. Build and push the images to the DockerHub:

Note: Use build args for the username and password if you need to log in to your artifact repository.

docker build --build-arg user=your_username --build-arg pass=your_password -f Dockerfile-deploy-task-engine -t xebialabsunsupported/deploy-task-engine:24.1.2-ojdbc11 .
docker push xebialabsunsupported/deploy-task-engine:24.1.2-ojdbc11

  1. Customize CR with patch file:

Here’s how you can use custom images by updating the master and worker image tags and modifying the database configuration to use the Oracle JDBC driver.

cat << EOF > custom-image-and-external-db-patch-1.yaml
spec:
  external:
    db:
      enabled: true
      main:
        url: jdbc:oracle:thin:@//db_hostname:1521/db
        username: user
        password: pass
      report:
        url: jdbc:oracle:thin:@//db_hostname:1521/db
        username: user
        password: pass
  postgresql:
    install: false
  master:
    image: 
      repository: xebialabsunsupported/xl-deploy
      tag: 24.1.2-ojdbc11
    imagePullPolicy: Always
    diagnosticMode:
      enabled: false
  worker:
    image:
      repository: xebialabsunsupported/deploy-task-engine
      tag: 24.1.2-ojdbc11
    imagePullPolicy: Always
    diagnosticMode:
      enabled: false
EOF
  1. Patch the CR in digitalai namespace:
kubectl patch -n digitalai digitalaideploys.xld.digital.ai dai-xld \
  --type=merge --patch-file custom-image-and-external-db-patch-1.yaml
  1. Restart the master and worker pods.

Note: After patching the CR configuration, the master and worker will not automatically restart with the new settings. You will need to manually delete the StatefulSet (STS).

kubectl delete sts dai-xld-digitalai-deploy-master -n digitalai
kubectl delete sts dai-xld-digitalai-deploy-worker -n digitalai

After restarting, the master and worker pods will launch with the new images, which include the Oracle JDBC driver in the lib directory. The external Oracle DB configuration will be applied and managed through the central configuration server.

Option 2: Add Custom Libraries During Startup​

This option uses only custom configuration to customize the Deploy’s lib folder with additional Oracle JDBC library.

Prerequisites​

  • Deploy installed on the Kubernetes cluster (e.g., in the digitalai namespace)

With this option, containers will be dynamically prepared during each pod startup. Depending on the selected persistence type, the libraries are downloaded each time the pod restarts. This setup is more complex, as it involves CR changes that create new scripts executed before starting the master or worker, along with an additional volume mount containing the downloaded libraries.

Note: In the following examples, we download the image from the public repository. Ensure that your artifact repository is trusted and secured by your organization. The URL location of the JAR is provided as an example and it can refer to any other repository or library.

Steps​

  1. Customize CR with patch file, the following list of changes is done on master and worker pods:

  • initContainers - defines the initial container db-install that runs before master/worker container (it will be part of the master/worker pod) and downloads the library to the persisted directory /opt/xebialabs/xl-deploy-server/extra-lib. See the args part where is script for downloading lib.

  • extraVolumes - setup for the emptyDir volume, here you can use any other type of persistent storage that persists the volume between pod containers (or longer).

  • extraVolumeMounts - mounts a new folder extra-lib on the defined volume on the master/worker pod, the folder is used as the source of downloaded libraries on the master/worker pod.

  • extraConfiguration - define the new script as file bin/run-in-operator-custom.sh that is additionally copying the files from extra-lib folder to the master/worker lib directory so that the libraries downloaded with init container db-install are copied, and then starts the standard script run-in-operator.sh.

  • args - change the startup script to use a custom script defined in the extraConfiguration: bin/run-in-operator-custom.sh

  • external - external DB setup for the custom DB

  • postgresql - disable PostgreSQL subchart

  • diagnosticMode - if enabled, doesn't start Deploy. You can open the console and check the state in the container. Also, you can run any script in the console to test behavior in the container.

cat << EOF > custom-image-and-external-db-patch-2.yaml
spec:
  external:
    db:
      enabled: true
      main:
        url: jdbc:oracle:thin:@//db_hostname:1521/db
        username: user
        password: pass
      report:
        url: jdbc:oracle:thin:@//db_hostname:1521/db
        username: user
        password: pass
  postgresql:
    install: false
  master:
    initContainers:
      - name: db-install
        image: library/busybox:stable
        imagePullPolicy: IfNotPresent
        securityContext:
          runAsNonRoot: true
          runAsUser: 10001
        command:
          - "/bin/sh"
          - "-c"
        args:
          - |
            export LIB_VERSION=23.4.0.24.05
            export LIB_FILE=ojdbc11-\${LIB_VERSION}.jar
            export LIB_URL=https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/\${LIB_VERSION}/\${LIB_FILE}
            if [ -f "/opt/xebialabs/xl-deploy-server/extra-lib/${LIB_FILE}" ]
            then
              echo "\${LIB_FILE} exists"
            else
              mkdir -p /opt/xebialabs/xl-deploy-server/extra-lib 
              if wget -P /opt/xebialabs/xl-deploy-server/extra-lib \${LIB_URL}
              then
                echo "\${LIB_URL} downloaded"
              else
                echo "Download failed"
              fi
            fi
        volumeMounts:
          - name: extra-lib
            mountPath: /opt/xebialabs/xl-deploy-server/extra-lib
    extraVolumes:
      - name: extra-lib
        emptyDir: {}
    extraVolumeMounts:
      - name: extra-lib
        mountPath: /opt/xebialabs/xl-deploy-server/extra-lib
        readOnly: true
    extraConfiguration:
      bin_run-in-opertator-custom:
        path: "bin/run-in-operator-custom.sh"
        mode: 0755
        content: |
          #!/bin/bash

          cp -fv /opt/xebialabs/xl-deploy-server/extra-lib/* /opt/xebialabs/xl-deploy-server/lib/
          exec /opt/xebialabs/xl-deploy-server/bin/run-in-operator.sh $@
    args:
      - --
      - /opt/xebialabs/xl-deploy-server/bin/run-in-operator-custom.sh
    diagnosticMode:
      enabled: false
  worker:
    initContainers:
      - name: db-install
        image: library/busybox:stable
        imagePullPolicy: IfNotPresent
        securityContext:
          runAsNonRoot: true
          runAsUser: 10001
        command:
          - "/bin/sh"
          - "-c"
        args:
          - |
            export LIB_VERSION=23.4.0.24.05
            export LIB_FILE=ojdbc11-\${LIB_VERSION}.jar
            export LIB_URL=https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/\${LIB_VERSION}/\${LIB_FILE}
            if [ -f "/opt/xebialabs/deploy-task-engine/extra-lib/${LIB_FILE}" ]
            then
              echo "\${LIB_FILE} exists"
            else
              mkdir -p /opt/xebialabs/deploy-task-engine/extra-lib 
              if wget -P /opt/xebialabs/deploy-task-engine/extra-lib \${LIB_URL}
              then
                echo "\${LIB_URL} downloaded"
              else
                echo "Download failed"
              fi
            fi
        volumeMounts:
          - name: extra-lib
            mountPath: /opt/xebialabs/deploy-task-engine/extra-lib
    extraVolumes:
      - name: extra-lib
        emptyDir: {}
    extraVolumeMounts:
      - name: extra-lib
        mountPath: /opt/xebialabs/deploy-task-engine/extra-lib
        readOnly: true
    extraConfiguration:
      bin_run-in-opertator-custom:
        path: "bin/run-in-operator-custom.sh"
        mode: 0755
        content: |
          #!/bin/bash

          cp -fv /opt/xebialabs/deploy-task-engine/extra-lib/* /opt/xebialabs/deploy-task-engine/lib/
          exec /opt/xebialabs/deploy-task-engine/bin/run-in-operator.sh $@
    args:
      - --
      - /opt/xebialabs/deploy-task-engine/bin/run-in-operator-custom.sh
    diagnosticMode:
      enabled: false
EOF
  1. Patch the CR in digitalai namespace:
kubectl patch -n digitalai digitalaideploys.xld.digital.ai dai-xld \
  --type=merge --patch-file custom-image-and-external-db-patch-2.yaml
  1. Restart the master and worker pods.

Note: After patching the CR configuration, the master and worker will not automatically restart with the new settings. You will need to manually delete the STS:

kubectl delete sts dai-xld-digitalai-deploy-master -n digitalai
kubectl delete sts dai-xld-digitalai-deploy-worker -n digitalai

After restarting, the master and worker pods will launch with the new images, which include the Oracle JDBC driver in the lib directory. The external Oracle DB configuration will be applied and used from the central configuration server.

Option 3: Use Slim Images with Specific Directory for JDBC and Message Queue Driver​

The slim image is a lightweight version of the standard Deploy image, designed to include only essential drivers and components,thereby reducing the attack surface.

This option is similar to Option 2 but is tailored for the slim image. Instead of using the extra-lib directory, the slim image utilizes specific directories for JDBC and MQ drivers:

  • JDBC Drivers Directory: driver/jdbc

  • Message Queue (MQ) Drivers Directory: driver/mq

Tip: This documentation focuses on the Oracle JDBC driver. However, the process for adding MQ drivers is similar; they should be placed in the driver/mq directory.

Prerequisites​

Ensure you are using the slim version of the Deploy image, tagged as 24.3-slim (or the version you are working with).

Steps to add Oracle JDBC driver using slim image​

  1. Customize CR with a patch file:

Use the following patch file to download the Oracle JDBC driver and place it in the appropriate directory within the slim image:

cat << EOF > custom-slim-image-patch.yaml
spec:
  external:
    db:
      enabled: true
      main:
        url: jdbc:oracle:thin:@//db_hostname:1521/db
        username: user
        password: pass
      report:
        url: jdbc:oracle:thin:@//db_hostname:1521/db
        username: user
        password: pass
  postgresql:
    install: false
  master:
    initContainers:
      - name: db-install
        image: library/busybox:stable
        imagePullPolicy: IfNotPresent
        securityContext:
          runAsNonRoot: true
          runAsUser: 10001
        command:
          - "/bin/sh"
          - "-c"
        args:
          - |
            export LIB_VERSION=23.4.0.24.05
            export LIB_FILE=ojdbc11-\${LIB_VERSION}.jar
            export LIB_URL=https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/\${LIB_VERSION}/\${LIB_FILE}
            if [ -f "/opt/xebialabs/xl-deploy-server/driver/jdbc/${LIB_FILE}" ]
            then
              echo "\${LIB_FILE} exists"
            elif wget -P /opt/xebialabs/xl-deploy-server/driver/jdbc \${LIB_URL}
            then
              echo "\${LIB_URL} downloaded"
            else
              echo "Download failed"
            fi
        volumeMounts:
          - name: custom-jdbc-drivers
            mountPath: /opt/xebialabs/xl-deploy-server/driver/jdbc
    extraVolumes:
      - name: custom-jdbc-drivers
        emptyDir: {}
    extraVolumeMounts:
      - name: custom-jdbc-drivers
        mountPath: /opt/xebialabs/xl-deploy-server/driver/jdbc
        readOnly: true
    diagnosticMode:
      enabled: false
  worker:
    initContainers:
      - name: db-install
        image: library/busybox:stable
        imagePullPolicy: IfNotPresent
        securityContext:
          runAsNonRoot: true
          runAsUser: 10001
        command:
          - "/bin/sh"
          - "-c"
        args:
          - |
            export LIB_VERSION=23.4.0.24.05
            export LIB_FILE=ojdbc11-\${LIB_VERSION}.jar
            export LIB_URL=https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/\${LIB_VERSION}/\${LIB_FILE}
            if [ -f "/opt/xebialabs/deploy-task-engine/driver/jdbc/${LIB_FILE}" ]
            then
              echo "\${LIB_FILE} exists"
            elif wget -P /opt/xebialabs/deploy-task-engine/driver/jdbc \${LIB_URL}
            then
              echo "\${LIB_URL} downloaded"
            else
              echo "Download failed"
            fi
        volumeMounts:
          - name: custom-jdbc-drivers
            mountPath: /opt/xebialabs/deploy-task-engine/driver/jdbc
    extraVolumes:
      - name: custom-jdbc-drivers
        emptyDir: {}
    extraVolumeMounts:
      - name: custom-jdbc-drivers
        mountPath: /opt/xebialabs/deploy-task-engine/driver/jdbc
        readOnly: true
    diagnosticMode:
      enabled: false
EOF

The initContainer is configured to download the Oracle JDBC driver and place it directly in the driver/jdbc directory, which is already part of the image.

  1. Patch the CR in digitalai namespace.

Apply the patch to your Kubernetes resource:

kubectl patch -n digitalai digitalaideploys.xld.digital.ai dai-xld \
  --type=merge --patch-file custom-slim-image-patch.yaml

  1. Restart the master and worker pods.

Note: After patching the CR configuration, the master and worker will not automatically restart with the new settings. You will need to manually delete the STS:

kubectl delete sts dai-xld-digitalai-deploy-master -n digitalai
kubectl delete sts dai-xld-digitalai-deploy-worker -n digitalai

After restarting, the master and worker pods will launch with the new images, which include the Oracle JDBC driver in the lib directory. The external Oracle DB configuration will be applied and used from the central configuration server.