--- updatedAt: 2026-08-12T07:25:13.000Z agentTools: siteIndex: https://docs.jfrog.com/llms.txt projectIndex: https://docs.jfrog.com/installation/llms.txt --- # Xray HA Helm Installation Install Xray HA on Kubernetes using Helm with a multi-node cluster, shared PostgreSQL, and RabbitMQ services. Before proceeding with the installation, review the system requirements. Xray's system requirements are dependent on the scale of your environment. ## Sizings **Non-Kubernetes Deployment** Up to 100K indexed artifacts. No High Availability | Component | Nodes | CPU Cores | Memory | Disk Space | | :---------------------- | :---- | :-------- | :----- | :---------------------- | | Xray and DB | 1 | 6 | 24 GB | 500 GB (SSD, 3000 IOPS) | | RabbitMQ | 1 | 4 | 8 GB | 100GB (SSD, 3000 IOPS) | | JFrog Advanced Security | 1 | 6 | 24 GB | 500 GB (SSD, 3000 IOPS) | Up to 1M indexed artifacts | Component | Nodes | CPU Cores | Memory | Disk Space | | :---------------------- | :---- | :-------- | :----- | :---------------------- | | Xray | 2 | 4 | 8 GB | 300 GB | | DB | 1 | 8 | 32 GB | 500 GB (SSD, 3000 IOPS) | | RabbitMQ Split | 3 | 4 | 8 GB | 100GB (SSD, 3000 IOPS) | | JFrog Advanced Security | 2 | 8 | 24 GB | 300 GB | Up to 2M indexed artifacts | Component | Nodes | CPU Cores | Memory | Disk Space | | :---------------------- | :---- | :-------- | :----- | :--------------------- | | Xray | 3 | 6 | 12 GB | 300 GB | | DB | 1 | 16 | 32 GB | 1 TB (SSD, 3000 IOPS) | | RabbitMQ Split | 3 | 4 | 8 GB | 100GB (SSD, 3000 IOPS) | | JFrog Advanced Security | 4 | 8 | 24 GB | 300 GB | Up to 10M indexed artifacts | Component | Nodes | CPU Cores | Memory | Disk Space | | :---------------------- | :---- | :-------- | :----- | :---------------------- | | Xray | 3 | 8 | 24 GB | 300 GB | | DB | 1 | 16 | 64 GB | 2.5 TB (SSD, 3000 IOPS) | | RabbitMQ Split | 3 | 4 | 8 GB | 100GB (SSD, 3000 IOPS) | | JFrog Advanced Security | 8 | 8 | 24 GB | 300 GB | Over 10M indexed artifacts Contact JFrog Support. For Xray HA (High Availability) installations (more than one node and 100k indexed artifacts), we recommend installing RabbitMQ and Xray on separate servers using split mode. For more information, see our page [here](rabbitmq-split-for-xray). **RabbitMQ Note** RabbitMQ is a crucial component of the Xray architecture, acting as a message broker for communication between various application services. Multiple queues facilitate communication channels between producers and consumers. For more information, please refer to our page [here](xray-and-rabbitmq-nodes-recommendations_xray-system-requirements-and-platform-support). **Kubernetes Deployment** 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. **Note**: From Helm chart 103.124 version of JFrog Xray, JFrog added support for Quorum Queues in RabbitMQ. This requires a minimum of three nodes of RabbitMQ and ensures fault tolerance of at least one node.  A non-HA setup of 1 node is also supported. **Note**: We recommend a three-node cluster of RabbitMQ for Xray. Large clusters increase the overhead of replication and could affect the throughput. Our application has been tuned to work in a three-node setup. **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. ```bash helm repo add jfrog https://charts.jfrog.io ``` 2. Update the repository. ```bash 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. ```bash # 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. ```yaml xray: masterKey: ``` Alternatively, you can create a secret containing the master key manually and pass it to the template during installation/upgrade. ```bash # 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. ```yaml xray: masterKeySecretName: masterkey-secret ``` **Note** In either case, pass the same master key on all future `helm install` and `helm upgrade` calls. For the first option, always pass `--set xray.masterKey=${MASTER_KEY}`. For the second option, always pass `--set xray.masterKeySecretName=masterkey-secret` and verify 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. ```yaml xray: joinKey: ``` 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. ```bash kubectl create secret generic joinkey-secret --from-literal=join-key= ``` The following example shows the `values.yaml` file with the join key secret. ```yaml xray: joinKeySecretName: joinkey-secret ``` **Note** In either case, pass the same join key on all future `helm install` and `helm upgrade` calls. For the first option, always pass `--set xray.joinKey=`. For the second option, always pass `--set xray.joinKeySecretName=joinkey-secret` and verify 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. ```yaml xray: jfrogUrl: ``` 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. ```yaml replicaCount: 3 ``` 7. 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 master key as secrets, replicaCount, and JFrog URL. ```yaml replicaCount: 3 xray: jfrogUrl: http://artifactory.rt:8082 joinKeySecretName: joinkey-secret masterKeySecretName: masterkey-secret ``` The following sample shows an example `values.yaml` file with join key, master key, replicaCount, and JFrog URL. ```yaml replicaCount: 3 xray: jfrogUrl: http://artifactory.rt:8082 joinKey: EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE masterKey: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF ``` 8. 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. ```bash helm upgrade --install xray --namespace xray -f values.yaml ``` The following command shows how you can pass the required values along with the command. ```bash helm upgrade --install xray --set xray.masterKey=${MASTER_KEY} \ --set xray.joinKey= \ --set xray.jfrogUrl= --namespace xray jfrog/xray ``` The following command shows how you can pass join key and master key as a secret along with the command. ```bash helm upgrade --install xray --set xray.masterKeySecretName=masterkey-secret \ --set xray.joinKeySecretName=joinkey-secret \ --set xray.jfrogUrl= --namespace xray jfrog/xray ``` 9. To access the logs, find the name of the pod using the following command. ```bash kubectl --namespace get pods ``` 10. To get the container logs, run the following command. ```bash kubectl --namespace logs -f ``` 11. [Customize the product configuration](xray-ha-helm-installation#xray-system-requirements-and-platform-support). **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. ```bash helm upgrade --install xray --namespace xray -f values.yaml ``` 12. Access Xray from your browser at: `http:///ui/` and go to **Xray Security & Compliance** tab in the **Administration** module in the UI 13. Check the status of your deployed helm releases. ```bash helm status xray ``` **Note** For advanced installation options, see [Helm Charts Installers for Advanced Users](helm-charts-for-advanced-users). 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](xray-system-yaml). If you do not 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.` 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. We recommend using 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](xray-system-yaml)** section of the `$JFROG_HOME/xray/var/etc/system.yaml`file. * **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](xray-system-yaml)** section of the `$JFROG_HOME/xray/var/etc/system.yaml` file. Xray comes bundled with a PostgreSQL database out-of-the-box, which come pre-configured with the default credentials. To change the default credentials: ```bash # 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](xray-system-yaml)** section of the `$JFROG_HOME/xray/var/etc/system.yaml` file. Xray comes pre-installed with RabbitMQ, by setting the Erlang cookie value as the RabbitMQ password for guest users. 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](installing-xray) , but do not start the services. 2. Modify the following files according to the installer type. * **Common Change in All Installers** ```yaml In system.yaml: shared: node: id: name: ## For secondary nodes only, provide the hostname of any of the active nodes where RabbitMQ service is running. # shared: # rabbitMq: # active: # node: # name: ``` 3. Start RabbitMQ and the Xray services. 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: ```bash $ chmod -R 640 $JFROG_HOME/xray/var/log ``` 3. Adjust the group read inheritance permissions `setgid bit` using: ```bash $ chmod -R 2755 $JFROG_HOME/xray/var/log ``` This command enables the generated log files to inherit the folder's group permissions. ## Xray System Requirements and Platform Support Xray's system requirements are dependent on the scale of your environment. ###### Sizings **Non-Kubernetes Deployment** Up to 100K indexed artifacts. No High Availability | Component | Nodes | CPU Cores | Memory | Disk Space | | :---------------------- | :---- | :-------- | :----- | :---------------------- | | Xray and DB | 1 | 6 | 24 GB | 500 GB (SSD, 3000 IOPS) | | RabbitMQ | 1 | 4 | 8 GB | 100GB (SSD, 3000 IOPS) | | JFrog Advanced Security | 1 | 6 | 24 GB | 500 GB (SSD, 3000 IOPS) | Up to 1M indexed artifacts | Component | Nodes | CPU Cores | Memory | Disk Space | | :---------------------- | :---- | :-------- | :----- | :---------------------- | | Xray | 2 | 4 | 8 GB | 300 GB | | DB | 1 | 8 | 32 GB | 500 GB (SSD, 3000 IOPS) | | RabbitMQ Split | 3 | 4 | 8 GB | 100GB (SSD, 3000 IOPS) | | JFrog Advanced Security | 2 | 8 | 24 GB | 300 GB | Up to 2M indexed artifacts | Component | Nodes | CPU Cores | Memory | Disk Space | | :---------------------- | :---- | :-------- | :----- | :--------------------- | | Xray | 3 | 6 | 12 GB | 300 GB | | DB | 1 | 16 | 32 GB | 1 TB (SSD, 3000 IOPS) | | RabbitMQ Split | 3 | 4 | 8 GB | 100GB (SSD, 3000 IOPS) | | JFrog Advanced Security | 4 | 8 | 24 GB | 300 GB | Up to 10M indexed artifacts | Component | Nodes | CPU Cores | Memory | Disk Space | | :---------------------- | :---- | :-------- | :----- | :---------------------- | | Xray | 3 | 8 | 24 GB | 300 GB | | DB | 1 | 16 | 64 GB | 2.5 TB (SSD, 3000 IOPS) | | RabbitMQ Split | 3 | 4 | 8 GB | 100GB (SSD, 3000 IOPS) | | JFrog Advanced Security | 8 | 8 | 24 GB | 300 GB | Over 10M indexed artifacts Contact JFrog Support. For Xray HA (High Availability) installations (more than one node and 100k indexed artifacts), we recommend installing RabbitMQ and Xray on separate servers using split mode. For more information, see our page [here](rabbitmq-split-for-xray). **RabbitMQ Note** RabbitMQ is a crucial component of the Xray architecture, acting as a message broker for communication between various application services. Multiple queues facilitate communication channels between producers and consumers. For more information, please refer to our page [here](xray-and-rabbitmq-nodes-recommendations_xray-system-requirements-and-platform-support). **Kubernetes Deployment** 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. **Note**: From Helm chart 103.124 version of JFrog Xray, JFrog added support for Quorum Queues in RabbitMQ. This requires a minimum of three nodes of RabbitMQ and ensures fault tolerance of at least one node.  A non-HA setup of 1 node is also supported. **Note**: We recommend a three-node cluster of RabbitMQ for Xray. Large clusters increase the overhead of replication and could affect the throughput. Our application has been tuned to work in a three-node setup. The following table lists the supported operating systems and their versions: | Product | Debian | RHEL | Ubuntu | Amazon Linux | Windows Server | | :------- | :--------- | :------- | :----------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | **Xray** | 10.x, 11.x | 8.x, 9.x | 20.04, 22.04 | Amazon Linux 2023 | ![(error)](https://files.readme.io/7ccc10487942ebbb83aa6f83e10c29194adc610efd4692fef967cb9dcceabb4f-uuid-743a6924-5713-3f27-4a63-b66e1c78bfa8.svg) | **Note** Debian 12.x and Ubuntu 24.04 are supported from Artifactory 7.104 and Distribution 2.28. Windows 2022 is supported from Artifactory 7.125. #### Supported Platforms The following table lists the supported platforms: | Product | x86-64 | ARM64 | Kubernetes | OpenShift | | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------- | :--------------- | | **Xray** | ![(tick)](https://files.readme.io/c71e6fa39c8e1d5e494b90df587cbf743b3dee9cc1b143eb314c34fb4b1ff066-uuid-ea92c1e1-5d79-3981-c8d5-5a5d13efa637.svg) | ![(tick)](https://files.readme.io/c71e6fa39c8e1d5e494b90df587cbf743b3dee9cc1b143eb314c34fb4b1ff066-uuid-ea92c1e1-5d79-3981-c8d5-5a5d13efa637.svg) | 1.27+ | 4.14+ | Installation on Kubernetes environments is through Helm Charts. Supported Helm version is Helm 3.17+. **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 for Container-Based Installations** Artifactory, Xray, and Distribution support installation on ARM64 architecture specifically through Helm and Docker installations. When deploying a product on an ARM64 platform, an external database must be set up as Artifactory does not support the bundled database for ARM64 installations. The appropriate ARM64 Container Image is automatically pulled during the Helm or Docker installation process. ## Related Topics * [Xray HA Installation](xray-ha-installation) * [Xray Installation](installing-xray) * [PostgreSQL for Xray](postgresql-for-xray) * [RabbitMQ (Split) for Xray](rabbitmq-split-for-xray) * [Quorum Queue Enablement for Xray and Platform Helm Charts](quorum-queue-enablement-for-xray-and-platform-helm-charts) * [Xray System Requirements and Platform Support](xray-system-requirements-and-platform-support) * [Upgrading Xray](upgrading-xray)