Helm

نشر ClickStack باستخدام Helm - حزمة observability من ClickHouse

إصدار المخطط 2.x

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

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

يعتمد مخطط v2.x على تثبيت من مرحلتين. تُثبَّت المشغّلات وتعريفات الموارد المخصّصة (CRDs) أولًا عبر مخطط clickstack-operators، ثم يأتي بعد ذلك مخطط clickstack الرئيسي الذي ينشئ موارد مخصّصة تُدار بواسطة المشغّلات لكل من ClickHouse وMongoDB وOpenTelemetry Collector.

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

• ClickHouse — يُدار بواسطة ClickHouse Operator عبر الموردين المخصّصين ClickHouseCluster وKeeperCluster
• HyperDX — واجهة observability وواجهة API
• OpenTelemetry (OTel) collector — يُنشر عبر مخطط Helm الرسمي لـ OpenTelemetry Collector كمخطط فرعي
• MongoDB — يُدار بواسطة MongoDB Kubernetes Operator (MCK) عبر مورد مخصّص MongoDBCommunity

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

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

• إعدادات خاصة بكل بيئة عبر values.yaml
• حدود الموارد والتوسّع على مستوى الـ pod
• إعدادات TLS وIngress
• إدارة الـ secrets وإعدادات authentication
• ملفات manifest إضافية لنشر كائنات Kubernetes عشوائية (NetworkPolicy وHPA وALB 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. ​

   ثبّت المشغِّلات

   ثبّت مخطط Helm الخاص بالمشغِّل أولًا. سيؤدي ذلك إلى تسجيل تعريفات الموارد المخصّصة (CRDs) التي يتطلبها المخطط الرئيسي:

   helm install clickstack-operators clickstack/clickstack-operators
   

   انتظر حتى تصبح وحدات المشغّل جاهزة قبل المتابعة:

   kubectl get pods -l app.kubernetes.io/instance=clickstack-operators
   
4. ​

   تثبيت ClickStack

   بمجرد أن تعمل المشغّلات، ثبّت حزمة Helm الرئيسية:

   helm install my-clickstack clickstack/clickstack
   
5. ​

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

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

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

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

6. ​

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

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

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

   إعداد نقطة الدخول لبيئة الإنتاج

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

7. ​

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

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

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

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

   تجاوز الاتصال الافتراضي

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

8. ​

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

   يمكنك تخصيص الإعدادات باستخدام خيارات --set. على سبيل المثال:

   helm install my-clickstack clickstack/clickstack --set key=value
   

   بدلًا من ذلك، عدّل ملف values.yaml. لاسترجاع القيم الافتراضية:

   helm show values clickstack/clickstack > values.yaml
   

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

   hyperdx:
     frontendUrl: "https://hyperdx.example.com"
   
     deployment:
       replicas: 2
       resources:
         limits:
           cpu: "2"
           memory: 4Gi
         requests:
           cpu: 500m
           memory: 1Gi
   
     ingress:
       enabled: true
       host: hyperdx.example.com
       tls:
         enabled: true
         tlsSecretName: "hyperdx-tls"
   

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

   استخدام الأسرار (اختياري)

   يستخدم مخطط الإصدار v2.x سرًا موحدًا (clickstack-secret) يُعبَّأ من hyperdx.secrets في values لديك. تمر جميع متغيرات البيئة الحساسة — بما في ذلك كلمات مرور ClickHouse وMongoDB ومفتاح API الخاص بـ HyperDX — عبر هذا السر الواحد.

   لتجاوز قيم السر:

   hyperdx:
     secrets:
       HYPERDX_API_KEY: "your-api-key"
       CLICKHOUSE_PASSWORD: "your-clickhouse-password"
       CLICKHOUSE_APP_PASSWORD: "your-app-password"
       MONGODB_PASSWORD: "your-mongodb-password"
   

   لإدارة الأسرار الخارجية (مثلًا باستخدام مشغّل أسرار)، يمكنك الإشارة إلى Kubernetes secret موجود مسبقًا:

   hyperdx:
     useExistingConfigSecret: true
     existingConfigSecret: "my-external-secret"
     existingConfigConnectionsKey: "connections.json"
     existingConfigSourcesKey: "sources.json"
   

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

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

​

استخدام ClickHouse Cloud

إذا كنت تستخدم ClickHouse Cloud، فعطّل مثيل ClickHouse المدمج وأدخِل بيانات اعتماد Cloud:

# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false

hyperdx:
  secrets:
    CLICKHOUSE_PASSWORD: "your-cloud-password"
    CLICKHOUSE_APP_PASSWORD: "your-cloud-password"

  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

أنشئ مورد secret للاتصال بشكل منفصل:

cat <<EOF > connections.json
[
  {
    "name": "ClickHouse Cloud",
    "host": "https://your-cloud-instance.clickhouse.cloud",
    "port": 8443,
    "username": "default",
    "password": "your-cloud-password"
  }
]
EOF

kubectl create secret generic clickhouse-cloud-config \
  --from-file=connections.json=connections.json

rm connections.json

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

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

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

​

ملاحظات خاصة ببيئة الإنتاج

بشكل افتراضي، يثبّت هذا الـ مخطط كلاً من ClickHouse وMongoDB وOTel collector. ويُوصى في بيئات production بإدارة ClickHouse وOTel collector بشكل منفصل.

لتعطيل ClickHouse وOTel collector:

clickhouse:
  enabled: false

otel-collector:
  enabled: false

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

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

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

​

تهيئة المهام

افتراضيًا، توجد مهمة واحدة في إعداد الحزمة على شكل cronjob، وهي مسؤولة عن التحقق مما إذا كان ينبغي إطلاق التنبيهات. في الإصدار v2.x، نُقلت تهيئة المهام إلى hyperdx.tasks:

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

​

ترقية مخطط Helm

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

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

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

helm search repo clickstack

الترقية من v1.x

إذا كنت تُجري الترقية من مخطط inline-template للإصدار v1.x، فراجِع دليل الترقية للحصول على إرشادات الترحيل. هذا تغيير غير متوافق — ولا يُدعَم تنفيذ helm upgrade مباشرةً على التثبيت الحالي.

​

إزالة تثبيت ClickStack

أزِل التثبيت بالترتيب العكسي:

helm uninstall my-clickstack            # Remove app + CRs first
helm uninstall clickstack-operators     # Remove operators + CRDs

ملاحظة: لا تتم إزالة PersistentVolumeClaims التي يُنشئها مشغّلا MongoDB وClickHouse عند تنفيذ helm uninstall. وهذا سلوك مقصود لتجنّب فقدان البيانات عن طريق الخطأ. لتنظيف PVCs، راجع:

• وثائق MongoDB Kubernetes Operator

​

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

​

فحص السجلات

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 وإصلاحها - عرض الملفات الثابتة، وإعادة كتابة المسارات، ومشكلات المتصفح
• عمليات النشر السحابية - مشكلات GKE OpAMP والمشكلات الخاصة بـ Cloud

​

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

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

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

​

الوثائق ذات الصلة

​

أدلة النشر

• خيارات النشر - ClickHouse خارجي، وOTel collector، وعمليات النشر بالحد الأدنى
• دليل التهيئة - مفاتيح API، وsecrets، وإعداد Ingress
• عمليات النشر السحابية - إعدادات GKE وEKS وAKS، وأفضل الممارسات لبيئات الإنتاج
• دليل الترقية - الترحيل من v1.x إلى v2.x
• ملفات manifest إضافية - نشر كائنات Kubernetes مخصصة إلى جانب مخطط

​

وثائق v1.x

• Helm (v1.x) - دليل نشر v1.x
• التهيئة (v1.x) - تهيئة v1.x
• خيارات النشر (v1.x) - خيارات نشر v1.x
• عمليات النشر السحابية (v1.x) - تهيئات Cloud لـ v1.x

​

موارد إضافية

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