تهيئة Helm ‏(v1.x)

يستعرض هذا الدليل خيارات التهيئة لعمليات نشر ClickStack عبر Helm. وللتثبيت الأساسي، راجع دليل النشر الرئيسي باستخدام Helm.

بعد نشر ClickStack بنجاح، قم بتهيئة مفتاح API لتمكين جمع بيانات القياس عن بُعد:

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

أضف مفتاح API إلى ملف values.yaml:

hyperdx:
  apiKey: "your-api-key-here"

ثم قم بترقية عملية النشر الخاصة بك:

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

helm upgrade my-clickstack clickstack/clickstack --set hyperdx.apiKey="your-api-key-here"

بعد تحديث مفتاح الـAPI، أعد تشغيل الكبسولات لتحميل التهيئة الجديدة:

kubectl rollout restart deployment my-clickstack-clickstack-app my-clickstack-clickstack-otel-collector

للتعامل مع بيانات حساسة مثل مفاتيح API أو بيانات اعتماد قاعدة البيانات، استخدم كائنات secrets في Kubernetes.

يتضمّن مخطط Helm قالب Secret افتراضيًا موجودًا في charts/clickstack/templates/secrets.yaml. يوفّر هذا الملف بنية أساسية لإدارة الأسرار.

إذا كنت بحاجة إلى تطبيق كائن Secret يدويًا، فعدّل قالب secrets.yaml المتوفّر ثم طبّقه:

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

طبّق كائن Secret على العنقود:

kubectl apply -f secrets.yaml

أنشئ سرّ Kubernetes مخصّصًا يدويًا:

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

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

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

لتأمين عملية النشر باستخدام HTTPS:

1. أنشئ سر TLS باستخدام شهادتك ومفتاحك الخاص:

kubectl create secret tls hyperdx-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

2. فعّل TLS في تكوين الـIngress لديك:

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 مفعّلًا

إصدار متحكّم Ingress:

• تتطلّب بعض الميزات (مثل مسارات regex وعمليات إعادة الكتابة) إصدارات حديثة من متحكّم nginx Ingress
• تحقّق من إصدارك باستخدام:

kubectl -n ingress-nginx get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath="{.items[0].spec.containers[0].image}"

إذا كنت بحاجة إلى إتاحة endpoints الخاصة بـ OTEL collector (للـ traces والـ metrics والـ logs) عبر الولوج، فاستخدم إعداد additionalIngresses. ويكون ذلك مفيدًا لإرسال telemetry data من خارج الـ cluster أو لاستخدام domain مخصص لـ 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 (التتبعات والمقاييس والسجلات) عبر قاعدة واحدة

تحقق من مورد الإدخال:

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

مثال على التهيئة:

replicaCount: 2

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

hyperdx:
  ingress:
    enabled: true
    host: hyperdx.example.com

طبّق قيمك المخصّصة:

helm install my-clickstack clickstack/clickstack -f values.yaml

• خيارات النشر (v1.x) - الأنظمة الخارجية وعمليات النشر الدنيا
• عمليات النشر على Cloud (v1.x) - تهيئات GKE وEKS وAKS
• دليل Helm الأساسي (v1.x) - التثبيت الأساسي
• تهيئة Helm (v2.x) - دليل تهيئة v2.x
• دليل الترقية - الترحيل من v1.x إلى v2.x