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

تهيئة مفاتيح API وكائنات Secret وIngress لعمليات نشر ClickStack عبر Helm في الإصدار v1.x

مهمل — مخطط Helm ‏v1.x

توضح هذه الصفحة إعدادات التهيئة الخاصة بمخطط Helm v1.x ذي القالب المضمّن، وهو الآن في وضع الصيانة. للاطلاع على مخطط v2.x، انظر تهيئة Helm. وللترحيل، راجع دليل الترقية.

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

​

إعداد مفتاح API

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

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

​

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

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

hyperdx:
  apiKey: "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.apiKey="your-api-key-here"

​

أعد تشغيل الكبسولات لتطبيق التغييرات

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

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

ينشئ المخطط تلقائيًا Kubernetes secret (<release-name>-app-secrets) يتضمّن مفتاح API الخاص بك. ولا يلزم أي إعداد إضافي لهذا الـ secret إلا إذا كنت تريد استخدام secret خارجي.

​

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

للتعامل مع بيانات حساسة مثل مفاتيح 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 مخصّص

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

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

​

الإشارة إلى secret في ملف values.yaml

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"

ملاحظة مهمة حول الإعداد

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

​

تمكين TLS (HTTPS)

لتأمين عملية النشر باستخدام 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}"

​

ولوج OTEL collector

إذا كنت بحاجة إلى إتاحة 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 (التتبعات والمقاييس والسجلات) عبر قاعدة واحدة

إذا لم تكن بحاجة إلى إتاحة OTel collector خارجيًا، فيمكنك تخطي هذا الإعداد. وبالنسبة إلى معظم المستخدمين، يكون إعداد الإدخال العام كافيًا.

​

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

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

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