OpenResty XRay™ Helm Deployment on Kubernetes Cluster

# Overview

Deploying OpenResty XRay in a Kubernetes cluster with Helm simplifies the installation, upgrade, and overall lifecycle management of the application. Helm uses a packaging format called a chart. OpenResty XRay does not yet provide a public Helm repository, so deployment is done from a local chart package.

This document covers the following topics:

• Prerequisites
• Installation
• Configuration
• Basic Ops
• Conclusion

# Prerequisites

Before you begin, please make sure that the following requirements are met:

• A running Kubernetes cluster.
• The Helm CLI is installed and configured to connect to the target cluster.
• You have the permissions required to deploy applications to the cluster.
• You are familiar with the StorageClasses available in your cluster, which will be used to provision persistent storage.

# Installation

# Obtain the Helm Chart

OpenResty XRay does not currently provide a public Helm repository. The chart is distributed as a local package (.tar.gz).

# Install Using the Local Helm Chart

1. Download the OpenResty XRay Helm chart package (.tar.gz file) that we provide.

2. Unpack the chart package into any local directory.

3. Change into the extracted directory:

   cd path_to_directory/orxray
   

4. Before running the install command, adjust values.yaml according to your environment by following the Configuration section below.

# Configuration

# values.yaml Overview

The values.yaml file lists all configurable options for the OpenResty XRay Helm chart. Please review and modify it carefully before deployment.

# Ingress Configuration

If you plan to expose the service through an Ingress Controller or an Application Gateway, configure the ingress section in values.yaml accordingly:

ingress:
  enabled: true
  annotations: {}
  # kubernetes.io/ingress.class: nginx
  # kubernetes.io/tls-acme: "true"
  paths: []
  hosts:
    - host: xray-console.example.com
      paths: ["/"]
  tls: []
  # - secretName: chart-example-tls
  #   hosts:
  #     - chart-example.local

# Persistent Volume Claim Override

For persistent data storage, the persistentVolumeClaimOverride section lets you specify a custom storageClassName and volumeName. Configure these values according to the storage options available in your cluster:

persistentVolumeClaimOverride:
  consoleData:
    storageClassName: <your-storage-class-name>
    volumeName: <your-volume-name>

For a quick trial, you can set storageClassName to local-path.

# Resource Limits and Requests

The values.yaml file ships with default resource requests and limits. You can tune them to match your nodes’ capacity and your actual workload:

resources:
  console:
    limits:
      cpu: "2"
      memory: 4Gi
    requests:
      cpu: "500m"
      memory: 512Mi

# HTTP Proxy Configuration (Optional)

If your network requires an HTTP proxy to reach the Internet, configure values.yaml as follows:

customInfo:
  env:
    httpProxy: "http://proxyserver.example.com:8080"
    httpProxyAuthorization: "Basic `base64 'username:password'`"

# Deploy OpenResty XRay

Once the configuration above is in place, run the following command to deploy OpenResty XRay to your Kubernetes cluster:

helm install openresty-xray ./orxray -f ./orxray/values.yaml

# Basic Ops

# Check Pod Status

Check the running status of the OpenResty XRay pods:

kubectl get pods -l "app.kubernetes.io/name=orxray"

Inspect the details of a pod returned by the previous command:

kubectl describe pod POD-NAME

If a pod reports errors such as pod has unbound immediate PersistentVolumeClaims, inspect the PVCs and StorageClasses for more information:

kubectl get pvc
kubectl get storageclass
kubectl describe pvc PVC-NAME

Open a shell inside a specific container to troubleshoot (using build-box-rockylinux-8 as an example):

kubectl exec -it POD-NAME -c build-box-rockylinux-8 -- bash

# View Service Logs

View the OpenResty XRay console logs:

kubectl logs CONSOLE-POD-NAME -c xray-console
# View the logs from the previous (pre-crash) run of the container
kubectl logs CONSOLE-POD-NAME -c xray-console --previous

View the logs of the tenant-db and build-box containers:

kubectl logs TENANT-POD-NAME -c xray-tenant-db
kubectl logs TENANT-POD-NAME -c xray-tenant-db --previous

kubectl logs TENANT-POD-NAME -c build-box-rockylinux-8
kubectl logs TENANT-POD-NAME -c build-box-rockylinux-8 --previous

# Upgrade Components

To upgrade OpenResty XRay, first download the latest chart package and unpack it, then run:

helm upgrade openresty-xray ./orxray -f ./orxray/values.yaml

If this upgrade does not change the PVCs, there is no need to delete existing PVCs and the stored data will not be affected.

# Conclusion

Deploying OpenResty XRay in a Kubernetes cluster with Helm makes installation, upgrades, and day-to-day operations more standardized and controllable. Before deploying, carefully review the Ingress, persistent volume claim, and resource settings in values.yaml to ensure they match your target cluster environment and actual business requirements.