Xray HA OpenShift Installation

JFrog Installation & Setup Documentation

Content Type
Installation & Setup
ft:sourceType
Paligo

Xray on OpenShift is available from version 3.80.9 onwards.

Before you proceed with the installation, review the system requirements.

Xray Node Recommendations

Use a dedicated node for Xray with no other software running to alleviate performance bottlenecks, avoid port conflicts, and avoid setting uncommon configurations.

Xray Storage Recommendations

In most cases, our recommendation is to use an SSD drive for Xray to have better performance and it is not recommended to use an NFS drive, as it is a disk I/O-intensive service, a slow NFS server can suffer from I/O bottlenecks and NFS is mostly used for storage replication.

Xray stores node-specific files, such as configuration and temporary files, to the disk. These files are exclusively used by Xray and not shared with other services. Since the local storage used for Xray services is temporary, it does not require replication between the different nodes in a multi-node/HA deployment.

Xray File Handle Allocation Limit

Use the following command to determine the current file handle allocation limit.

cat /proc/sys/fs/file-max

Then, set the following parameters in your /etc/security/limits.conf file to the lower of 100,000 or the file handle allocation limit determined above.

The example shows how the relevant parameters in the /etc/security/limits.conf file are set to 100000. The actual setting for your installation may be different depending file handle allocation limit in your system.

root hard nofile 100000
root soft nofile 100000
xray hard nofile 100000
xray soft nofile 100000
postgres hard nofile 100000
postgres soft nofile 100000
Operating Systems and Platform Support

The following table lists the supported operating systems and the versions.

Product

Debian

RHEL

Ubuntu

Amazon Linux

Windows Server

Artifactory

10.x, 11.x

8.x, 9.x

20.04, 22.04

Amazon Linux 2023

2016 or 2019

Xray

10.x, 11.x

8.x, 9.x

20.04, 22.04

Distribution

10.x, 11.x

8.x, 9.x

20.04, 22.04

Insight

10.x, 11.x

8.x, 9.x

20.04, 22.04

Amazon Linux 2023

Pipelines

8.x

20.04, 22.04

Amazon Linux 2023

Build nodes only

Supported Platforms

The following table lists the supported platforms.

Product

x86-64

ARM64

Kubernetes

OpenShift

Artifactory

1.19+

4.13+

Xray

1.19+

4.13+

Distribution

1.19+

4.13+

Insight

1.19+

Pipelines

1.19+

Installation on Kubernetes environments is through Helm Charts. Supported Helm version is Helm 3+.

Kubernetes Sizing Requirements

We have included YAML files with different sizing configurations for Artifactory , Xray, and Distribution in our GitHub pages. You can use these YAML files when you set up your cluster.

ARM64 Support

Starting from version 7.41.4, Artifactory supports installation on ARM64 architecture through Helm and Docker installations. You must set up an external database as the Artifactory database since Artifactory does not support the bundled database with the ARM64 installation. Artifactory installation pulls the ARM64 image automatically when you run the Helm or Docker installation on the ARM64 platform.

ARM64 support is also available for Xray, Distribution and Insight.

Database and Third-Party Applications in Xray

Every artifact and build indexed by Xray is broken down into multiple components. These components and the relationships between each other are represented in a checksum based components graph. Xray uses PostgreSQL to store and query this components graph.

Xray supports the following versions of PostgreSQL:

  • 16.x (from version 3.107)

  • 15.x (from version 3.78.9)

  • 14.x

  • 13.x (from version 3.18)

  • 12.x

Xray supports PostgreSQL 14.x and 15.x, but currently the Xray installer only bundles the binaries for PostgreSQL 13.x.

RabbitMQ is installed as part of the Xray installation for every node. In case of HA architecture, Xray uses queue mirroring between the different RabbitMQ nodes. External RabbitMQ instances are not officially supported; the recommended method of installation is to use the bundled RabbitMQ.

Xray has multiple flows, such as scanning, impact analysis, and database sync. These flows require processing completed by the different Xray microservices. Flows contain multiple steps that are completed by the Xray services. Xray uses RabbitMQ to manage these different flows and track synchronous and asynchronous communication between the microservices.

Xray also uses Erlang and DB-Util third-party applications. These packages are bundled with all Xray installers except Linux Archive. You need to use Erlang version 25.x and you can use the latest available version db-util.

Xray Network Ports

Xray uses the 8082 port by default for external communication.

Xray uses the following internal ports by default for communication with JFrog Platform microservices.

Microservice

Port

Xray Server

8000

Analysis

7000

Indexer

7002

Persist

7003

Router

HTTP: 8082, 8046, 8049

gRPC: 8047

RabbitMQ

4369, 5671, 5672, 15672, and 25672

PostgreSQL (if you use the bundled PostgreSQL database)

5432

Observability

HTTP: 8036

gRPC: 8037

Note

Currently, it is not possible to connect a JFrog product that is within a Kubernetes cluster with another JFrog product that is outside of the cluster, as this is considered a separate network. Therefore, JFrog products cannot be joined together if one of them is in a cluster.

Note

External RabbiMQ instances are not officially supported; the recommended method of installation is to use the bundled RabbitMQ.

Follow these steps to install the product:

  1. Add the charts.jfrog.io to your Helm client.

    helm repo add jfrog https://charts.jfrog.io
  2. Update the repository.

    helm repo update
  3. Next, create a unique master key. JFrog Xray requires a unique master key to be used by all micro-services in the same cluster. By default the chart has one set in values.yaml (xray.masterKey).

    Note

    For production grade installations it is strongly recommended to use a custom master key. If you initially use the default master key it will be very hard to change the master key at a later stage This key is for demo purpose and should not be used in a production environment.

    Generate a unique key and pass it to the template during installation/upgrade.

    # Create a key
    export MASTER_KEY=$(openssl rand -hex 32)
    echo ${MASTER_KEY}
    

    You can pass this master key to the Helm installation through the Helm command or through the values.yaml file.

    The following example shows the values.yaml file with the master key.

    xray:
      masterKey: <master key value>

    Alternatively, you can create a secret containing the master key manually and pass it to the template during installation/upgrade.

     # Create a secret containing the key. The key in the secret must be named master-key
    kubectl create secret generic masterkey-secret --from-literal=master-key=${MASTER_KEY}
    

    You can pass this master key secret to the Helm installation through the Helm command (by passing masterkey-secret)or through the values.yaml file.

    The following example shows the values.yaml file with the master key secret.

    xray:
      masterKeySecretName: masterkey-secret

    Note

    In either case, make sure to pass the same master key on all future calls to helm install and helm upgrade. In the first case, this means always passing --set xray.masterKey=${MASTER_KEY}. In the second, this means always passing --set xray.masterKeySecretName=masterkey-secret and ensuring the contents of the secret remain unchanged.

    You can also provide the master key or master key secret inside a values.yaml file and pass it along during the installation.

  4. Installation requires a join key.

    You can pass the join key along with the Helm install/upgrade command or pass it in a values.yaml file.

    The following sample shows how to provide join key in the values.yaml file.

    xray:
      joinKey: <join key value>

    Alternatively, you can manually create a secret containing the join key and then pass it to the template during install/upgrade. The key must be named join-key.

    kubectl create secret generic joinkey-secret --from-literal=join-key=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY>
    

    The following example shows the values.yaml file with the join key secret.

    xray:
      joinKeySecretName: joinkey-secret

    Note

    In either case, make sure to pass the same join key on all future calls to helm install and helm upgrade. This means always passing --set xray.joinKey=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY>. In the second, this means always passing --set xray.joinKeySecretName=joinkey-secret and ensuring that the contents of the secret remain unchanged.

  5. You need to enter the JFrog URL.

    You can either pass the JFrog URL along with the Helm install/upgrade command or pass it along with the values.yaml file.

    The following example shows the values.yaml file with the JFrog URL.

    xray:
      jfrogUrl: <JFrog URL>
  6. For an HA Xray installation, set the replicaCount value as >1 (the recommended is 3).

    You can either pass the value along with the Helm install/upgrade command or pass it along with the values.yaml file.

    The following example shows the values.yaml file with the replicaCount values.

    replicaCount: 3
    
  7. When you deploy Xray helm chart on an OpenShift cluster, you need to disable the podSecurityContext and containerSecurityContext. Default OpenShift functionality automatically assigns and arbitrary UID block associated with the project.

    Set the following values in the values.yaml so that you can pass it along with the installation.

    containerSecurityContext:
      enabled: false
    podSecurityContext:
      enabled: false
    
    rbac:
      create: true
    serviceAccount:
      create: true
    
    rabbitmq:
      rbac:
        create: true
      podSecurityContext:
        enabled: false
      containerSecurityContext:
        enabled: false
  8. To make PostgreSQL work on OpenShift, disable the securityContext in the pod and container level in the values.yaml file, and set the following values.

      postgresql:
        postgresqlPassword: password
        securityContext:
          enabled: false
        containerSecurityContext:
          enabled: false
        serviceAccount:
          enabled: true
  9. Create a values.yaml file with all the required configuration if you want to proceed with an installation that holds all the configurations in a values.yaml file.

    You can also use separate configuration files for each configuration and pass them as separate yaml files.

    The following sample shows an example values.yaml file with join key and JFrog URL.

    replicaCount: 3
    xray:
      jfrogUrl: http://artifactory.rt:8082
      joinKey: joinkey-secret
      masterKey: masterkey-secret
    
    containerSecurityContext:
      enabled: false
    podSecurityContext:
      enabled: false
    
    rbac:
      create: true
    serviceAccount:
      create: true
    
    rabbitmq:
      rbac:
        create: true
      podSecurityContext:
        enabled: false
      containerSecurityContext:
        enabled: false
      replicaCount: 1
    postgresql:
      postgresqlPassword: password
      securityContext:
        enabled: false
      containerSecurityContext:
        enabled: false
      serviceAccount:
        enabled: true
    

    The following sample shows an example values.yaml file with join key as a secret and JFrog URL.

    replicaCount: 3
    xray:
      jfrogUrl: http://artifactory.rt:8082
      joinKeySecretName: joinkey-secret
      masterKeySecretName: masterkey-secret
    
    containerSecurityContext:
      enabled: false
    podSecurityContext:
      enabled: false
    
    rbac:
      create: true
    serviceAccount:
      create: true
    
    rabbitmq:
      rbac:
        create: true
      podSecurityContext:
        enabled: false
      containerSecurityContext:
        enabled: false
      replicaCount: 1
    postgresql:
      postgresqlPassword: password
      securityContext:
        enabled: false
      containerSecurityContext:
        enabled: false
      serviceAccount:
        enabled: true
    
  10. Run the Helm install command to proceed with the installation.

    The following command shows how you can pass the required values through a values.yaml file.

    helm upgrade --install xray --namespace xray -f values.yaml
  11. To access the logs, find the name of the pod using the following command.

    kubectl --namespace <your namespace> get pods
  12. To get the container logs, run the following command.

    kubectl --namespace <your namespace> logs -f <name of the pod>
  13. Customize the product configuration.

    Note

    Unlike other installations, Helm Chart configurations are made to the values.yaml and are then applied to the system.yaml.

    Follow these steps to apply the configuration changes.

    1. Make the changes to values.yaml.

    2. Run the command.

      helm upgrade --install xray --namespace xray -f values.yaml
  14. Access Xray from your browser at: http://<jfrogUrl>/ui/ and go to Xray Security & Compliance tab in the Administration module in the UI

  15. Check the status of your deployed helm releases.

    helm status xray

After installing and before running Xray, you may set the following configurations.

You can configure all your system settings using the system.yaml file located in the $JFROG_HOME/xray /var/etc folder. For more information, see Xray System YAML.

If you don't have a System YAML file in your folder, copy the template available in the folder and name it system.yaml.

For the Helm charts, the system.yaml file is managed in the chart’s values.yaml.

Artifactory Connection Details for Xray

Xray requires a working Artifactory server and a suitable license. The Xray connection to Artifactory requires the following parameters.

  • jfrogUrl

    URL to the machine where JFrog Artifactory is deployed, or the load balancer pointing to it. It is recommended to use DNS names rather than direct IPs. For example: http://jfrog.acme.com or http://10.20.30.40:8082. Note that /artifactory context is not longer required.

    Set it in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yamlfile.

  • join.key

    This is the "secret" key required by Artifactory for registering and authenticating the Xray server.

    You can fetch the Artifactory joinKey (join Key) from the JPD UI in the User Management | Settings | Join Key.

    Set the join.key used by your Artifactory server in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

Change PostgreSQL database credentials

Xray comes bundled with a PostgreSQL database out-of-the-box, which come pre-configured with the default credentials.

To change the default credentials:

# Access PostgreSQL as the Xray user adding the optional -W flag to invoke the password prompt
$ psql -d xraydb -U xray -W
  
# Securely change the password for user "xray". Enter and then retype the password at the prompt.
\password xray
  
# Verify the update was successful by logging in with the new credentials
$ psql -d xraydb -U xray -W

Set your PostgreSQL connection details in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

Change RabbitMQ database credentials

Xray comes pre-installed with RabbitMQ, by setting the Erlang cookie value as the RabbitMQ password for guest users.

Docker Compose
  1. Set the new password in the <MOUNT_DIR>/app/third-party/rabbitmq/rabbitmq.conf file.

    default_pass = <new password>
  2. Set your RabbitMQ password in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

  3. Restart all services.

    cd jfrog-xray-<version>-compose   
    docker-compose -p xray restart
RPM/Debian
  1. Set the new password in the$JFROG_HOME/app/bin/rabbitmq/rabbitmq.conffile.

    default_pass = <new password>
  2. Set your RabbitMQ password in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

  3. Restart all services.

    service xray restart / systemctl restart xray.service
Linux Archive
  1. Set the new password in the$JFROG_HOME/app/bin/rabbitmq/rabbitmq.conf file.

    default_pass = <new password>
  2. Set your RabbitMQ password in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

  3. Restart all services.

    xray/app/bin/xray.sh restart
Configure RabbitMQ to use FQDN for clustering

By default, RabbitMQ uses the short hostnames of other nodes in the cluster for communication. However, it be can be configured to use a fully qualified domain name (FQND) host name (a long hostname).

To configure RabbitMQ to use FQDN, follow these steps.

  1. Install Xray , but do not start the services.

  2. Modify the following files according to the installer type.

    • Docker-Compose

      In docker-compose-rabbitmq.yaml:
       
            environment:
            - RABBITMQ_USE_LONGNAME=true
       
      In .env:
       
          HOST_ID=<long hostname>
          ## For secondary nodes only, provide the hostname of any of the active nodes where RabbitMQ service is running.
          #JF_SHARED_RABBITMQ_ACTIVE_NODE_NAME=<long hostname of active node>
    • Linux and Native Installers

      In JFROG_HOME/app/bin/xray.default:
       
         export RABBITMQ_USE_LONGNAME=true
    • Common Change in All Installers

      In system.yaml:
       
      shared:
        node:
          id: <long hostname>
          name: <long hostname>
      ## For secondary nodes only, provide the hostname of any of the active nodes where RabbitMQ service is running.
      #  shared:
      #    rabbitMq:
      #      active:
      #        node:
      #          name: <long hostname of active node>
  3. Start RabbitMQ and the Xray services.

Third Party Log Collector

Xray enables using an external log collector such as Sumologic or Splunk.

To adjust the permissions to allow the log collection service perform read operations on the generated log files.

  1. Add the log collection service user to the relevant group if needed (the user and group that installed and started Xray).

  2. Apply the user and group permissions as needed on the $JFROG_HOME/xray/var/log directory using:

    $ chmod -R 640 $JFROG_HOME/xray/var/log
  3. Adjust the group read inheritance permissions setgid bit using:

    $ chmod -R 2755 $JFROG_HOME/xray/var/log

    This command enables the generated log files to inherit the folder's group permissions.