Helm (v1.x)

نشر ClickStack باستخدام مخطط Helm ذي القالب المضمّن للإصدار v1.x

متروك — مخطط v1.x

توثّق هذه الصفحة مخطط Helm بنمط v1.x inline-template، وهو في وضع الصيانة ولن يتلقّى مزايا جديدة بعد الآن. لعمليات النشر الجديدة، استخدم مخطط v2.x. ولترحيل عملية نشر حالية من v1.x، راجع دليل الترقية.

يمكن العثور على مخطط Helm الخاص بـ ClickStack هنا، وهو الطريقة الموصى بها لعمليات النشر في بيئة الإنتاج.

يوفّر مخطط Helm افتراضيًا جميع المكوّنات الأساسية، بما في ذلك:

• ClickHouse
• HyperDX
• جامع OpenTelemetry (OTel)
• MongoDB (لحالة التطبيق الدائمة)

ومع ذلك، يمكن تخصيصه بسهولة ليتكامل مع عملية نشر ClickHouse قائمة — على سبيل المثال، مستضافة على ClickHouse Cloud.

يدعم المخطط أفضل ممارسات Kubernetes القياسية، بما في ذلك:

• إعدادات خاصة بكل بيئة عبر values.yaml
• حدود الموارد والتوسعة على مستوى الـ pod
• إعداد TLS وIngress
• إدارة الأسرار وإعداد المصادقة

​

مناسب لـ

• تجارب إثبات المفهوم
• بيئات الإنتاج

​

خطوات النشر

1. ​

   المتطلبات الأساسية

   • Helm v3+
   • عنقود Kubernetes (يُوصى بالإصدار v1.20+)
   • kubectl مُعَدّ للتعامل مع عنقودك
2. ​

   أضف مستودع Helm لـ ClickStack

   أضف مستودع Helm لـ ClickStack:

   helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
   helm repo update
   
3. ​

   تثبيت ClickStack

   لتثبيت chart الخاص بـ ClickStack باستخدام القيم الافتراضية:

   helm install my-clickstack clickstack/clickstack
   
4. ​

   تحقّق من التثبيت

   تحقّق من التثبيت:

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

   عندما تصبح جميع وحدات الـPod جاهزة، تابع.

5. ​

   إعادة توجيه المنافذ

   تتيح إعادة توجيه المنافذ الوصول إلى HyperDX وإعداده. أمّا المستخدمون الذين ينشرون في بيئات الإنتاج، فينبغي لهم بدلًا من ذلك إتاحة الخدمة عبر مورد Ingress أو موازن تحميل لضمان وصول شبكي مناسب، وإنهاء TLS، وقابلية التوسع. وتُعد إعادة توجيه المنافذ أنسب للتطوير المحلي أو للمهام الإدارية لمرة واحدة، وليست مناسبة للبيئات طويلة الأمد أو عالية التوافر.

   kubectl port-forward \
     pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
     8080:3000
   

   إعداد Ingress لبيئة الإنتاج

   في عمليات النشر المخصّصة لبيئة الإنتاج، اضبط Ingress مع TLS بدلًا من إعادة توجيه المنفذ. راجع دليل تكوين Ingress للاطلاع على تعليمات إعداد مفصّلة.

6. ​

   الانتقال إلى واجهة المستخدم

   زُر http://localhost:8080 للوصول إلى واجهة HyperDX.

   أنشئ مستخدمًا بإدخال اسم مستخدم وكلمة مرور يستوفيان المتطلبات.

   عند النقر على Create، ستُنشأ مصادر البيانات لمثيل ClickHouse الذي نُشر باستخدام مخطط Helm.

   تجاوز إعداد الاتصال الافتراضي

   يمكنك تجاوز إعداد الاتصال الافتراضي لمثيل ClickHouse المدمج. لمزيد من التفاصيل، راجع “Using ClickHouse Cloud”.

7. ​

   تخصيص القيم (اختياري)

   يمكنك تخصيص الإعدادات باستخدام خيارات --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
   ingress:
     enabled: true
     annotations:
       kubernetes.io/ingress.class: nginx
     hosts:
       - host: hyperdx.example.com
         paths:
           - path: /
             pathType: ImplementationSpecific
   

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

   استخدام Kubernetes Secrets (اختياري)

   للتعامل مع البيانات الحساسة مثل مفاتيح API أو بيانات اعتماد قاعدة البيانات، استخدم Kubernetes Secrets. توفّر مخططات Helm الخاصة بـ HyperDX ملفات secrets افتراضية يمكنك تعديلها وتطبيقها على الـ cluster لديك.

   ​

   استخدام secrets مُعدّة مسبقًا

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

   إذا كنت بحاجة إلى تطبيق 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

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

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

   إدارة مفاتيح API

   للاطلاع على إرشادات تفصيلية لإعداد مفتاح API، بما في ذلك أساليب التهيئة المتعددة وإجراءات إعادة تشغيل الكبسولات، راجع دليل إعداد مفتاح API.

​

استخدام ClickHouse Cloud

عند استخدام ClickHouse Cloud، يجب على المستخدمين تعطيل مثيل ClickHouse الذي ينشره مخطط Helm وتحديد بيانات اعتماد Cloud:

# specify ClickHouse Cloud credentials
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # full https url
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# how to overwrite default connection
helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} \
  --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} \
  --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD}

بدلاً من ذلك، يمكنك استخدام ملف values.yaml:

clickhouse:
  enabled: false
  persistence:
    enabled: false
  config:
    users:
      otelUser: ${CLICKHOUSE_USER}
      otelUserPassword: ${CLICKHOUSE_PASSWORD}

otel:
  clickhouseEndpoint: ${CLICKHOUSE_URL}

hyperdx:
  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# or if installed...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

الإعدادات الخارجية المتقدمة

لعمليات النشر في بيئات الإنتاج التي تستخدم تهيئة قائمة على Secret، أو OTel collectors خارجية، أو إعدادات مبسطة، راجع دليل خيارات النشر.

​

ملاحظات حول بيئة production

يثبّت هذا مخطط، افتراضيًا، أيضًا ClickHouse وجامع OTel. ومع ذلك، في بيئة production، يُنصح بإدارة ClickHouse وجامع OTel بشكل منفصل.

لتعطيل ClickHouse وجامع OTel، اضبط values التالية:

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

أفضل الممارسات لبيئة الإنتاج

لعمليات النشر في بيئة الإنتاج، بما في ذلك إعداد التوافر العالي، وإدارة الموارد، وإعداد Ingress/TLS، والإعدادات الخاصة بـ Cloud ‏(GKE وEKS وAKS)، راجع:

• دليل التكوين - Ingress وTLS وإدارة الأسرار
• عمليات النشر على Cloud - الإعدادات الخاصة بـ Cloud وقائمة التحقق الخاصة ببيئة الإنتاج

​

تهيئة المهمة

افتراضيًا، توجد مهمة واحدة في إعدادات الـمخطط على شكل cronjob، وهي مسؤولة عن التحقق مما إذا كان ينبغي إطلاق التنبيهات. وفيما يلي خيارات تهيئتها:

المَعلمة	الوصف	الافتراضي
tasks.enabled	تمكين/تعطيل مهام cron في الـcluster. افتراضيًا، ستشغّل صورة HyperDX مهام cron ضمن العملية نفسها. غيّرها إلى true إذا كنت تفضّل استخدام مهمة cron منفصلة في الـcluster.	false
tasks.checkAlerts.schedule	جدول Cron لمهمة check-alerts	*/1 * * * *
tasks.checkAlerts.resources	طلبات الموارد والحدود لمهمة check-alerts	راجع values.yaml

​

ترقية المخطط

للترقية إلى إصدار أحدث:

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

للتحقق من إصدارات مخطط Helm المتاحة:

helm search repo clickstack

الترقية إلى v2.x

إذا كنت تريد الترحيل إلى المخطط المعتمد على المخطط الفرعي في v2.x، فراجع دليل الترقية للحصول على إرشادات الترحيل. هذا تغيير غير متوافق — لا يُدعَم إجراء helm upgrade موضعيًا.

​

إلغاء تثبيت ClickStack

لإزالة النشر:

helm uninstall my-clickstack

سيؤدي هذا إلى إزالة جميع الموارد المرتبطة بالإصدار، لكن قد تظل البيانات الدائمة (إن وُجدت).

​

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

​

فحص السجلات

kubectl logs -l app.kubernetes.io/name=clickstack

​

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

helm install my-clickstack clickstack/clickstack --debug --dry-run

​

التحقق من عملية النشر

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

موارد إضافية لاستكشاف الأخطاء وإصلاحها

للمشكلات المتعلقة بـ Ingress، أو مشكلات TLS، أو استكشاف أخطاء عمليات النشر على Cloud وإصلاحها، راجع ما يلي:

• استكشاف أخطاء Ingress وإصلاحها - تقديم الأصول، وإعادة كتابة المسارات، ومشكلات المتصفح
• عمليات النشر على Cloud - مشكلات GKE OpAMP والمشكلات الخاصة بالبيئات السحابية

​

اختيار المخطط: Map مقابل JSON

يخزّن ClickStack السمات في أعمدة Map(LowCardinality(String), String) افتراضيًا. هذا هو المخطط الموصى به لأعباء عمل Observability. وعند دمجه مع تسلسل map المقسّم إلى buckets وفهارس النص على مفاتيح map وقيمه، فإنه يوفّر عمليات بحث انتقائية من دون الكلفة الإضافية لإدخال كل مفتاح على حدة كما في JSON subcolumns الديناميكية.

يتوفر مخطط من النوع JSON في مرحلة بيتا للتقييم على أعباء العمل التي تتضمن مجموعة صغيرة ومستقرة من مفاتيح السمات. وهو غير موصى به كخيار افتراضي. راجع Map مقابل نوع JSON للاطلاع على المقارنة الكاملة ومتغيرات البيئة المطلوبة لتمكين دعم JSON.

​

الوثائق المرتبطة

​

أدلة النشر للإصدار v1.x

• خيارات النشر (v1.x) - ClickHouse خارجي، وجامع OTel، وعمليات النشر المصغّرة
• دليل التهيئة (v1.x) - مفاتيح API، والأسرار، وإعداد Ingress
• عمليات النشر في Cloud (v1.x) - تهيئات GKE وEKS وAKS وأفضل الممارسات في بيئات الإنتاج

​

وثائق الإصدار v2.x

• Helm (v2.x) - دليل نشر الإصدار v2.x
• دليل الترقية - الترحيل من v1.x إلى v2.x

​

موارد إضافية

• دليل البدء في ClickStack - مقدمة إلى ClickStack
• مستودع مخططات Helm الخاص بـ ClickStack - الشفرة المصدرية للمخطط ومرجع القيم
• وثائق Kubernetes - مرجع Kubernetes
• وثائق Helm - مرجع Helm