الانتقال إلى المحتوى الرئيسي
إصدار المخطط 2.xتوثق هذه الصفحة مخطط Helm v2.x المعتمد على المخططات الفرعية. إذا كنت لا تزال تستخدم مخطط v1.x ذي القوالب المضمّنة، فراجع تهيئة Helm (v1.x). للاطلاع على خطوات الترحيل، راجع دليل الترقية.
يغطي هذا الدليل خيارات التهيئة لعمليات نشر ClickStack باستخدام Helm. للتثبيت الأساسي، راجع دليل النشر الرئيسي باستخدام Helm.

​
تنظيم القيم

تنظّم مخطط Helm بالإصدار v2.x القيم حسب نوع مورد Kubernetes ضمن الكتلة hyperdx:: 
hyperdx:
  ports:          # Shared port numbers (Deployment, Service, ConfigMap, Ingress)
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"

  config:         # → clickstack-config ConfigMap (non-sensitive env vars)
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret (sensitive env vars)
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # K8s Deployment spec (image, replicas, probes, etc.)
  service:        # K8s Service spec (type, annotations)
  ingress:        # K8s Ingress spec (host, tls, annotations)
  podDisruptionBudget:  # K8s PDB spec
  tasks:          # K8s CronJob specs
تمرّ جميع متغيرات البيئة عبر موردين ذوي اسمين ثابتين، يشترك فيهما كلٌّ من نشر HyperDX و OTEL Collector عبر envFrom:
  • clickstack-config ConfigMap — يُعبَّأ من hyperdx.config
  • clickstack-secret Secret — يُعبَّأ من hyperdx.secrets
لم يعد هناك ConfigMap منفصل مخصّص لـ OTEL. ويقرأ كلٌّ من عبئي العمل من المصادر نفسها.

​
إعداد مفتاح API

بعد نشر ClickStack بنجاح، اضبط مفتاح API لتمكين جمع بيانات القياس عن بُعد:
  1. ادخل إلى مثيل HyperDX الخاص بك عبر مورد الإدخال المُعَدّ أو نقطة نهاية الخدمة
  2. سجّل الدخول إلى لوحة معلومات HyperDX ثم انتقل إلى إعدادات الفريق لإنشاء مفتاح API أو استرداده
  3. حدّث النشر لديك باستخدام مفتاح API بإحدى الطرق التالية:

​
الطريقة 1: التحديث باستخدام Helm upgrade مع ملف values

أضِف مفتاح API إلى values.yaml: 
hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key-here"
ثم قم بترقية النشر: 
helm upgrade my-clickstack clickstack/clickstack -f values.yaml

​
الطريقة 2: التحديث باستخدام Helm upgrade مع الخيار —set

helm upgrade my-clickstack clickstack/clickstack \
  --set hyperdx.secrets.HYPERDX_API_KEY="your-api-key-here"

​
أعد تشغيل الحاويات القرنية لتطبيق التغييرات

بعد تحديث مفتاح API، أعد تشغيل الحاويات القرنية لكي تعتمد التهيئة الجديدة: 
kubectl rollout restart deployment my-clickstack-clickstack-app
تنشئ مخطط Helm تلقائيًا Kubernetes secret (clickstack-secret) من قيم الإعداد الخاصة بك. ولا تحتاج إلى أي إعداد إضافي لـ secret إلا إذا أردت استخدام External Secret.

​
إدارة الأسرار

للتعامل مع البيانات الحساسة مثل مفاتيح API أو بيانات اعتماد قاعدة البيانات، يوفّر مخطط بالإصدار v2.x موردًا موحّدًا باسم clickstack-secret يُعبَّأ من hyperdx.secrets.

​
القيم الافتراضية للأسرار

تتضمّن المخطط قيماً افتراضية لجميع الأسرار. يمكنك تجاوزها في values.yaml: 
hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key"
    CLICKHOUSE_PASSWORD: "your-clickhouse-otel-password"
    CLICKHOUSE_APP_PASSWORD: "your-clickhouse-app-password"
    MONGODB_PASSWORD: "your-mongodb-password"

​
استخدام Secret خارجي في Kubernetes

في عمليات النشر في بيئة الإنتاج، عندما تريد إبقاء بيانات الاعتماد منفصلة عن قيم Helm، استخدم Secret خارجيًا في Kubernetes: 
# Create your secret
kubectl create secret generic my-clickstack-secrets \
  --from-literal=HYPERDX_API_KEY=my-secret-api-key \
  --from-literal=CLICKHOUSE_PASSWORD=my-ch-password \
  --from-literal=CLICKHOUSE_APP_PASSWORD=my-ch-app-password \
  --from-literal=MONGODB_PASSWORD=my-mongo-password
ثم أشر إليه ضمن values لديك: 
hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-clickstack-secrets"

​
إعداد الإدخال

لنشر واجهة مستخدم HyperDX وواجهة برمجة التطبيقات الخاصة به عبر اسم نطاق، فعِّل الإدخال في ملف values.yaml.

​
التكوين العام للإدخال

hyperdx:
  frontendUrl: "https://hyperdx.yourdomain.com"  # Must match ingress host

  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
ملاحظة مهمة حول الإعداديجب أن يتطابق hyperdx.frontendUrl مع اسم مضيف مورد الإدخال وأن يتضمن البروتوكول (على سبيل المثال، https://hyperdx.yourdomain.com). ويضمن ذلك أن تعمل جميع الروابط وملفات تعريف الارتباط وعمليات إعادة التوجيه المُنشأة على النحو الصحيح.

​
تمكين TLS ‏(HTTPS)

لتأمين عملية النشر باستخدام HTTPS: 1. أنشئ Secret لـ TLS باستخدام شهادتك ومفتاحك الخاص: 
kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key
2. فعّل TLS في إعداد مورد الدخول الخاص بك: 
hyperdx:
  ingress:
    enabled: true
    host: "hyperdx.yourdomain.com"
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

​
مثال على إعداد الإدخال

للاطلاع، إليك كيف يبدو مورد الإدخال الذي أُنشئ: 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hyperdx-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
    - host: hyperdx.yourdomain.com
      http:
        paths:
          - path: /(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: my-clickstack-clickstack-app
                port:
                  number: 3000
  tls:
    - hosts:
        - hyperdx.yourdomain.com
      secretName: hyperdx-tls

​
المشكلات الشائعة في الإدخال

إعداد المسار وإعادة الكتابة:
  • بالنسبة إلى Next.js وغيرها من التطبيقات أحادية الصفحة، استخدم دائمًا مسار Regex وتعليمة إعادة كتابة كما هو موضح أعلاه
  • لا تستخدم path: / فقط من دون إعادة كتابة، لأن ذلك سيؤدي إلى تعطّل تقديم الموارد الثابتة
عدم تطابق frontendUrl و ingress.host:
  • إذا لم يتطابقا، فقد تواجه مشكلات في ملفات تعريف الارتباط وعمليات إعادة التوجيه وتحميل الموارد
سوء تهيئة TLS:
  • تأكد من أن secret الخاص بـ TLS صالح وأنه مُشار إليه بشكل صحيح في الإدخال
  • قد تمنع المتصفحات المحتوى غير الآمن إذا وصلت إلى التطبيق عبر HTTP عندما يكون TLS مفعّلًا
إصدار متحكّم إدخال:
  • تتطلب بعض الميزات (مثل مسارات Regex وعمليات إعادة الكتابة) إصدارات حديثة من متحكّم nginx إدخال
  • تحقّق من إصدارك باستخدام:
kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

​
الإدخال لـ OTEL collector

إذا كنت بحاجة إلى تعريض نقاط نهاية OTEL collector (للتتبعات والمقاييس والسجلات) عبر الإدخال، فاستخدم إعداد additionalIngresses. ويُعد ذلك مفيدًا لإرسال بيانات القياس عن بُعد من خارج العنقود أو لاستخدام نطاق مخصص للـ OTEL collector. 
hyperdx:
  ingress:
    enabled: true
    additionalIngresses:
      - name: otel-collector
        annotations:
          nginx.ingress.kubernetes.io/ssl-redirect: "false"
          nginx.ingress.kubernetes.io/force-ssl-redirect: "false"
          nginx.ingress.kubernetes.io/use-regex: "true"
        ingressClassName: nginx
        hosts:
          - host: collector.yourdomain.com
            paths:
              - path: /v1/(traces|metrics|logs)
                pathType: Prefix
                port: 4318
                name: otel-collector
        tls:
          - hosts:
              - collector.yourdomain.com
            secretName: collector-tls
  • ينشئ هذا مورد إدخال منفصلًا لنقاط نهاية OTel collector
  • يمكنك استخدام نطاق مختلف، وتهيئة إعدادات TLS محددة، وتطبيق تعليقات توضيحية مخصصة
  • تتيح لك قاعدة مسار Regex توجيه جميع إشارات OTLP (التتبعات والمقاييس والسجلات) عبر قاعدة واحدة
إذا لم تكن بحاجة إلى إتاحة OTel collector خارجيًا، فيمكنك تخطي هذا الإعداد. بالنسبة إلى معظم المستخدمين، يكفي إعداد الإدخال العام.
بدلًا من ذلك، يمكنك استخدام additionalManifests لتعريف موارد إدخال مخصصة بالكامل، مثل AWS ALB Ingress.

​
تهيئة OTEL collector

يُنشر OTEL Collector عبر مخطط Helm الرسمي الخاص بـ OpenTelemetry Collector بوصفه المخطط الفرعي otel-collector:. قم بتهيئته مباشرةً ضمن otel-collector: في values الخاصة بك: 
otel-collector:
  enabled: true
  mode: deployment
  replicaCount: 3
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule
تتم مشاركة متغيرات البيئة (نقطة نهاية ClickHouse، وعنوان URL لـ OpAMP، وما إلى ذلك) عبر ConfigMap الموحّد clickstack-config وSecret clickstack-secret. كما أن extraEnvsFrom في المخطط الفرعي مُهيّأ مسبقًا للقراءة من كليهما. اطّلع على مخطط Helm الخاص بـ OpenTelemetry Collector للاطلاع على جميع قيم المخطط الفرعي المتاحة.

​
تهيئة MongoDB

تتولى إدارة MongoDB مشغّل MCK عبر مورد مخصص من النوع MongoDBCommunity. ويُعرَض قسم CR spec كما هو من mongodb.spec: 
mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi
يتم تعيين كلمة مرور MongoDB في hyperdx.secrets.MONGODB_PASSWORD. راجع وثائق MCK للاطلاع على جميع حقول CRD المتاحة.

​
إعداد ClickHouse

تُدار ClickHouse بواسطة ClickHouse Operator عبر الموارد المخصصة ClickHouseCluster وKeeperCluster. وتُولَّد مواصفات CR لكليهما حرفيًا من values: 
clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi
تُؤخذ بيانات اعتماد مستخدم ClickHouse من hyperdx.secrets (وليس من clickhouse.config.users كما في v1.x). راجع دليل تهيئة ClickHouse Operator للاطّلاع على جميع حقول CRD المتاحة.

​
استكشاف أخطاء الإدخال وإصلاحها

تحقق من مورد الإدخال: 
kubectl get ingress -A
kubectl describe ingress <ingress-name>
تحقق من سجلات وحدة تحكم الإدخال: 
kubectl logs -l app.kubernetes.io/name=ingress-nginx -n ingress-nginx
اختبار عناوين URL للموارد: استخدم curl للتحقق من أن الملفات الثابتة تُقدَّم كملفات JS لا كصفحات HTML: 
curl -I https://hyperdx.yourdomain.com/_next/static/chunks/main-xxxx.js
# Should return Content-Type: application/javascript
أدوات المطوّر في المتصفح:
  • تحقّق من علامة التبويب Network بحثًا عن أخطاء 404 أو ملفات تُرجع HTML بدلًا من JS
  • ابحث عن أخطاء مثل Unexpected token < في وحدة التحكّم (وهذا يشير إلى إرجاع HTML بدلًا من JS)
تحقّق من إعادة كتابة المسارات:
  • تأكّد من أن مورد الإدخال لا يزيل مسارات الملفات أو يعيد كتابتها بشكل غير صحيح
امسح ذاكرة التخزين المؤقت للمتصفح وCDN:
  • بعد إجراء التغييرات، امسح ذاكرة التخزين المؤقت للمتصفح وأي ذاكرة تخزين مؤقت لـ CDN/الوكيل لتجنّب تحميل ملفات قديمة

​
تخصيص القيم

يمكنك تخصيص الإعدادات باستخدام خيارات --set: 
helm install my-clickstack clickstack/clickstack --set key=value
بدلًا من ذلك، أنشئ ملف values.yaml مخصّصًا. لاسترجاع القيم الافتراضية: 
helm show values clickstack/clickstack > values.yaml
طبِّق القيم المخصّصة لديك: 
helm install my-clickstack clickstack/clickstack -f values.yaml

​
الخطوات التالية

آخر تعديل في ٢٥ يونيو ٢٠٢٦