Helm

إصدار المخطط 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 وغيرها) إلى جانب المخطط

مناسب لـ

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

خطوات النشر

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

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

أضف مستودع Helm الخاص بـ ClickStack

أضف مستودع Helm الخاص بـ ClickStack:

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

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

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

helm install clickstack-operators clickstack/clickstack-operators

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

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

تثبيت ClickStack

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

helm install my-clickstack clickstack/clickstack

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

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

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

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

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

تتيح إعادة توجيه المنافذ الوصول إلى 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 بدلًا من إعادة توجيه المنافذ. راجع دليل إعداد نقطة الدخول للحصول على إرشادات إعداد مفصّلة.

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

زُر http://localhost:8080 للوصول إلى واجهة HyperDX.أنشئ مستخدمًا، وأدخل اسم مستخدم وكلمة مرور يستوفيان المتطلبات.عند النقر على Create، سيتم إنشاء مصادر البيانات لمثيل ClickHouse الذي تم نشره باستخدام مخطط Helm.

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

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

يمكنك تخصيص الإعدادات باستخدام خيارات --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

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

يستخدم مخطط الإصدار 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

الميزات

الأدلة

مناسب لـ

خطوات النشر

استخدام ClickHouse Cloud

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

تهيئة المهام

ترقية مخطط Helm

إزالة تثبيت ClickStack

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

فحص السجلات

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

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

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

أدلة النشر

وثائق v1.x

موارد إضافية

​مناسب لـ

​خطوات النشر

​استخدام ClickHouse Cloud

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

​تهيئة المهام

​ترقية مخطط Helm

​إزالة تثبيت ClickStack

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

​فحص السجلات

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

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

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

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

​أدلة النشر

​وثائق v1.x

​موارد إضافية

مناسب لـ

خطوات النشر

استخدام ClickHouse Cloud

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

تهيئة المهام

ترقية مخطط Helm

إزالة تثبيت ClickStack

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

فحص السجلات

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

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

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

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

أدلة النشر

وثائق v1.x

موارد إضافية