Skip to main content
Version: Release 24.1

Setting Up JDBC and MQ Drivers

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

There are three options available:

Option 1: Build Release Images with Custom Libraries​

This option uses custom master and worker images to customize the Release’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​

  • Release 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 using the following command:
cat << EOF > Dockerfile
FROM xebialabs/xl-release: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-release-server/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 -t xebialabsunsupported/xl-release:24.1.2-ojdbc11 .
docker push xebialabsunsupported/xl-release: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:
  image: 
    repository: xebialabsunsupported/xl-release
    tag: 24.1.2-ojdbc11
  imagePullPolicy: Always
  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
  diagnosticMode:
    enabled: false
EOF

  1. Patch the CR in digitalai namespace:
kubectl patch -n digitalai digitalaireleases.xlr.digital.ai dai-xlr \
  --type=merge --patch-file custom-image-and-external-db-patch-1.yaml
  1. Restart the Release pods.

After restarting, the 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 and used from xl-release.conf file in the conf folder.

Option 2: Add Custom Libraries During Startup​

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

Prerequisites​

  • Release 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 Release. 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:
  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-release-server/extra-lib/${LIB_FILE}" ]
          then
            echo "\${LIB_FILE} exists"
          else
            mkdir -p /opt/xebialabs/xl-release-server/extra-lib 
            if wget -P /opt/xebialabs/xl-release-server/extra-lib \${LIB_URL}
            then
              echo "\${LIB_URL} downloaded"
            else
              echo "Download failed"
            fi
          fi
      volumeMounts:
        - name: extra-lib
          mountPath: /opt/xebialabs/xl-release-server/extra-lib
  extraVolumes:
    - name: extra-lib
      emptyDir: {}
  extraVolumeMounts:
    - name: extra-lib
      mountPath: /opt/xebialabs/xl-release-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-release-server/extra-lib/* /opt/xebialabs/xl-release-server/lib/
        exec /opt/xebialabs/xl-release-server/bin/run-in-container.sh $@
  args:
    - --
    - /opt/xebialabs/xl-release-server/bin/run-in-operator-custom.sh
  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
  diagnosticMode:
    enabled: false
EOF

  1. Patch the CR in digitalai namespace:
kubectl patch -n digitalai digitalaireleases.xlr.digital.ai dai-xlr \
  --type=merge --patch-file custom-image-and-external-db-patch-2.yaml
  1. Restart the Release pods.

After restarting, the 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 and used from xl-release.conf file in the conf folder.

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

The slim image is a lightweight version of the standard Release 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 /opt/xebialabs/xl-release-server/driver/mq directory.

Prerequisites​

Ensure you are using the slim version of the Release 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
  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-release-server/driver/jdbc/${LIB_FILE}" ]
          then
            echo "\${LIB_FILE} exists"
          elif wget -P /opt/xebialabs/xl-release-server/driver/jdbc \${LIB_URL}
          then
            echo "\${LIB_URL} downloaded"
          else
            echo "Download failed"
          fi         
      volumeMounts:
        - name: custom-jdbc-drivers
          mountPath: /opt/xebialabs/xl-release-server/driver/jdbc
  extraVolumes:
    - name: custom-jdbc-drivers
      emptyDir: {}
  extraVolumeMounts:
    - name: custom-jdbc-drivers
      mountPath: /opt/xebialabs/xl-release-server/driver/jdbc
      readOnly: true
  diagnosticMode:
    enabled: false
EOF

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

  1. Patch the CR in digitalai namespace with the following command:
kubectl patch -n digitalai digitalaireleases.xlr.digital.ai dai-xlr \
  --type=merge --patch-file custom-slim-image-patch.yaml
  1. Restart the Release pods.

After restarting, the 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 and used from xl-release.conf file in the conf folder.