XRAY: Installation Quick Start Guide – Helm

Vignesh Surendrababu
2022-04-14 08:38

What will you get?

User-added image

Installation Requirements:

  • A running Kubernetes cluster with 1.14+ with Dynamic storage provisioning enabled
    Default StorageClass set to allow services using the default StorageClass for persistent storage
    A running Artifactory
    Kubectl installed and setup to use the cluster
    Helm v3 installed

Chart Details:

The Xray chart can install Xray micro services, RabbitMQ and optionally install PostgreSQL. 
For production installations it is recommended to use an external PostgreSQL with versions mentioned below

  • 9.5 (EOL)
  • 9.6 (EOL)
  • 10.x
  • 11.x
  • 12.x
  • 13.x – for Xray version 3.18 above

System Requirements:

Prior to installing, make sure the cluster is configured with the required CPU, Memory, RAM as per the requirements available on the RequirementsMatrix for Xray

Source code and Releases:

Xray charts can be found on GitHub 
Please refer to the release notes for the default Xray version of each chart version and our official documents for the latest update. 
To verify the Xray version to install, use the command

$ helm search repo jfrog/xray --versions

to fetch the list of chart versions

Note, from chart version 103.25.1 and above, the number after chart version 103.x is the default Xray version of that chart. So chart version 103.25.1 comes with Xray 3.25.1.

Steps to Install:

Add the JFrog Helm charts repository using the below commands to download the helm charts

$ helm repo add jfrog https://charts.jfrog.io
$ helm repo update

Artifactory Connection Details:

In order to connect Xray with Artifactory, you will need to use a join key & JFrog URLat the time of Installation. For retrieving the connection details of your Artifactory (Join Key and JFrog URL) from the UI, Navigate to Administration tab | Security | Settings | Connection details to view the Join Key.

Prepare Keys, Secrets for Master Key & Join Key:

Create a unique Master Key:

$ export MASTER_KEY=$(openssl rand -hex 32)
$ echo ${MASTER_KEY}

Create a “masterkey-secret” to hold the value
 

$ kubectl create secret generic masterkey-secret --from-literal=master-key=${MASTER_KEY}

Join Key:

Since the Join Key is retrieved using the Artifactory connection details, create the “joinkey-secret” to hold the value

$ export JOIN_KEY=Value retrieved using the view Join key
$ kubectl create secret generic joinkey-secret --from-literal=join-key=${JOIN_KEY}

 

Database secret

Database credentials can also be supplied with a secret. For this release, we are installing a bundled postgresql, so we will just pass the credentials as a plain text on values.yaml as shown below. 

xray:
jfrogUrl: <Provide JFrogUrl>
joinKeySecretName: joinkey-secret
masterKeySecretName: masterkey-secret
name: xray
persistence:
mountPath: /var/opt/jfrog/xray
postgresql:
enabled: true
postgresqlUsername: xray
postgresqlPassword: "password"
postgresqlDatabase: xraydb
postgresqlExtendedConf:
listenAddresses: "*"
maxConnections: "1500"
rabbitmq:
enabled: true
replicaCount: 1
rbac:
create: true
auth:
username: guest
password: "guest"

 

## Alternatively, you can use a pre-existing secret with a key called rabbitmq-password by specifying existingPasswordSecret
# existingPasswordSecret: <name-of-existing-secret>
erlangCookie: XRAYRABBITMQCLUSTER

We can also let the release generate a random password and retrieve it from a secret.
 

Resources:

Since this is an example deployment reference, we have used the request and limits for Xray microservices as below in the values.yaml file. It is always recommended to consider checking the system requirements page in order to allocate sufficient resources to the JFrog products as needed. Alternatively, it is suggested to refer to the reference values.yaml files available in the Github repository.
 

replicaCount: 1
common:
persistence:
size: 100Gi
xray:
jfrogUrl: <Provide JFrogUrl>
joinKeySecretName: joinkey-secret
masterKeySecretName: masterkey-secret
name: xray
persistence:
mountPath: /var/opt/jfrog/xray
postgresql:
enabled: true
postgresqlUsername: xray
postgresqlPassword: "password"
postgresqlDatabase: xraydb
postgresqlExtendedConf:
listenAddresses: "*"
maxConnections: "1500"
resources:
requests:
memory: "1Gi"
cpu: "1"
limits:
memory: "2Gi"
cpu: "2"
rabbitmq:
enabled: true
replicaCount: 1
schedulers: "1"
vm_memory_high_watermark_absolute: 700MB
rbac:
create: true
auth:
username: guest
password: "guest"
## Alternatively, you can use a pre-existing secret with a key called rabbitmq-password by specifying existingPasswordSecret
# existingPasswordSecret: <name-of-existing-secret>
erlangCookie: XRAYRABBITMQCLUSTER
resources:
requests:
memory: "512Mi"
cpu: "500m"
limits:
memory: "1Gi"
cpu: "1"
server:
resources:
requests:
memory: "300Mi"
cpu: "100m"
limits:
memory: "4Gi"
cpu: "3"
analysis:
resources:
requests:
memory: "300Mi"
cpu: "50m"
limits:
memory: "4Gi"
cpu: "3"
persist:
resources:
requests:
memory: "300Mi"
cpu: "50m"
limits:
memory: "4Gi"
cpu: "3"
indexer:
resources:
requests:
memory: "300Mi"
cpu: "50m"
limits:
memory: "4Gi"
cpu: "4"

How to install Xray using helm?

Important

Currently, it is not possible to connect a JFrog product (e.g., Xray) that is within a Kubernetes cluster with another JFrog product (e.g., Artifactory) 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 not in a cluster.
 
As we have all the properties in place, we are ready to deploy Xray using the below command

$ helm install xray -f values.yaml jfrog/xray --version 103.43.1

Note: If wanted to install HA node of Xray, make sure to update the replicaCount to a desired value > 1
For example:
 

replicaCount: 2
xray:
jfrogUrl: <Provide JFrogUrl>
joinKeySecretName: joinkey-secret
masterKeySecretName: masterkey-secret
name: xray
persistence:
mountPath: /var/opt/jfrog/xray

 

How to install Xray with an external database?

In this example, PostgreSQL is installed using the bitnami charts . It’s recommended to make sure that the database is configured with sufficient RAM, CPU, IOPS, Memory as per the system requirements
 

To install the Database:

  $ helm install xray-database bitnami/postgresql --set auth.postgresPassword=secretpassword --version 10.16.2
 

Once the database is installed, use the below queries to create the Xray database and make sure the user is assigned with necessary privileges.

Query:

CREATE USER xray WITH PASSWORD 'xray';
CREATE DATABASE xraydb WITH OWNER=xray ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE xraydb TO xray;
In order to connect the external database with Xray, certain changes must be made on the values.yaml used.
Step 1: Disable the bundled PostgreSQLpostgresql:
enabled: false
Step 2: Add the external database configuration as shown belowdatabase:
type: "postgresql"
driver: "org.postgresql.Driver"
## If you would like this chart to create the secret containing the database url, user, password - use these below values
url: "postgres://xray-postgresql.default.svc.cluster.local:5432/xraydb?sslmode=disable"
user: xray
password: xray

Final Values should look like below
 unifiedUpgradeAllowed: true
xray:
jfrogUrl: <Provide JFrogUrl>
joinKeySecretName: joinkey-secret
masterKeySecretName: masterkey-secret
name: xray
persistence:
mountPath: /var/opt/jfrog/xray
rabbitmq:
enabled: true
replicaCount: 1
resources:
requests:
memory: "512Mi"
cpu: "256m"
limits:
memory: "1Gi"
cpu: "500m"
auth:
username: guest
password: "Password@123"
postgresql:
enabled: false
database:
type: "postgresql"
driver: "org.postgresql.Driver"
url: "postgres://xray-postgresql.default.svc.cluster.local:5432/xraydb?sslmode=disable"
user: xray
password: xray

Now, deploy Xray using the below command$ helm install xray -f values.yaml jfrog/xray --version 103.43.1

Upgrading Xray:

It’s recommended to pass all the values in the previous release explicitly when running the upgrade command. This is to avoid falling back to any default values. Pay extreme attention to the secret you created, as failing to reference those in an upgrade action could result in new different values generated and breaking Xray. It'd be difficult to recover from such a case.$ helm upgrade --install xray -f values.yaml jfrog/xray --set databaseUpgradeReady=true --version 103.44.1 
Note that you must always pass the version explicitly during the upgrade to avoid falling back to an old version. Also, if the bundled PostgreSQL is used, it is necessary to pass--set databaseUpgradeReady=true
to the helm upgrade command. This is to force you to take cautions and check if any unwanted property change is introduced to the bundled database. Consider using the –dry-run option to check if there’s any unexpected change introduced to the bundled postgresql db. 
 

Uninstalling Xray:

It is important to note that uninstalling Xray using the commands below will also delete your data volumes and you will lose all of your data. You must back up all this information before deletion.$ helm uninstall xray 
Uninstall command will not delete the PVC created during the installation and it has to be manually removed using the command:$ kubectl delete pvc -l app=xray 

Glossary:

  1. System requirements: https://www.jfrog.com/confluence/display/JFROG/System+Requirements#SystemRequirements-Overview
  2. Helm Installation: https://www.jfrog.com/confluence/display/JFROG/Installing+Xray#InstallingXray-HelmInstallatio
  3. Helm Installation with High Availability: https://www.jfrog.com/confluence/display/JFROG/Installing+Xray#InstallingXray-HelmInstallation.1
  4. Source code of Xray charts: https://github.com/jfrog/charts/tree/master/stable/xray
  5. Helm charts for Advanced users: https://www.jfrog.com/confluence/display/JFROG/Helm+Charts+for+Advanced+Users